fix(wiki): compare drift against what NodeBB stored, not what we rendered #104

2026-08-07T20:44:31Z

archvillainette commented

2026-08-07 20:44:31 +00:00

Fixes #103.

What was wrong

crucible wiki deploy decided a page had drifted by hashing NodeBB's stored
copy and comparing it to the hash of the text Crucible rendered. Those match
only if NodeBB gives our HTML back byte for byte. It does not, so every
sow-topdata tag deploy failed:

local pages: 1200, updated: 1, skipped: 1176, drifted: 23
remote managed wiki content drifted; rerun with --force to overwrite

Nobody had edited those pages. The operator's only way out was to leave
--force on, which removes the protection the guard exists for.

What changed

New manifest field remote_hash: the managed-region hash of the post NodeBB
hands back right after we write it. Drift compares against that, so it means
"the live page changed after we last wrote it".
A post with no sourceContent is not drift. It predates sourceContent
sync, reads back as rendered HTML, and belongs to the existing
SourceContentSynced repair — which the drift refusal used to block.
The error names the drifted pages, capped at ten plus a count.
Deleted the dead wikiDeployPlan.RemoteHash field.

Old manifests keep the previous comparison until each page is next written, so
no re-seed is needed. Cost: one extra post read per page written. Pages that
skip are still never fetched.

Tests

internal/topdata/wiki_deploy_test.go, same seam as the rest of the file
(DeployWikiWithOptions against the fake NodeBB): normalized remote copy is not
drift, a hand-edited page still is and the error names it, --force overwrites
it and re-records the hash, a post without sourceContent is repaired instead
of refused, and an old-format manifest deploys and gains a remote_hash.

make check passes.

🤖 Generated with Claude Code

Fixes #103. ## What was wrong `crucible wiki deploy` decided a page had drifted by hashing NodeBB's stored copy and comparing it to the hash of the text Crucible rendered. Those match only if NodeBB gives our HTML back byte for byte. It does not, so every `sow-topdata` tag deploy failed: ``` local pages: 1200, updated: 1, skipped: 1176, drifted: 23 remote managed wiki content drifted; rerun with --force to overwrite ``` Nobody had edited those pages. The operator's only way out was to leave `--force` on, which removes the protection the guard exists for. ## What changed - New manifest field `remote_hash`: the managed-region hash of the post NodeBB hands back right after we write it. Drift compares against that, so it means "the live page changed after we last wrote it". - A post with no `sourceContent` is not drift. It predates `sourceContent` sync, reads back as rendered HTML, and belongs to the existing `SourceContentSynced` repair — which the drift refusal used to block. - The error names the drifted pages, capped at ten plus a count. - Deleted the dead `wikiDeployPlan.RemoteHash` field. Old manifests keep the previous comparison until each page is next written, so no re-seed is needed. Cost: one extra post read per page written. Pages that skip are still never fetched. ## Tests `internal/topdata/wiki_deploy_test.go`, same seam as the rest of the file (`DeployWikiWithOptions` against the fake NodeBB): normalized remote copy is not drift, a hand-edited page still is and the error names it, `--force` overwrites it and re-records the hash, a post without `sourceContent` is repaired instead of refused, and an old-format manifest deploys and gains a `remote_hash`. `make check` passes. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

archvillainette added 1 commit 2026-08-07 20:44:32 +00:00

fix(wiki): compare drift against what NodeBB stored, not what we rendered

ci / ci (pull_request) Successful in 3m41s

Details

63a0f6f044

The drift guard hashed NodeBB's stored copy of a page and compared it to the
hash of the text Crucible rendered. Those only match if NodeBB round-trips our
HTML byte for byte, so every sow-topdata deploy failed with "remote managed
wiki content drifted; rerun with --force" on pages nobody had edited.

Record the managed-region hash of the post NodeBB hands back right after each
write (manifest field remote_hash) and compare the next run against that. A
post with no sourceContent is no longer drift either: it predates sourceContent
sync, so it reads back as rendered HTML and belongs to the existing repair
path. The error now names the drifted pages, capped at ten.

Old manifests without remote_hash keep the previous comparison, so no re-seed
is needed. Costs one extra post read per page written; skipped pages are still
never fetched.

Closes #103

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

archvillainette scheduled this pull request to auto merge when all checks succeed 2026-08-07 21:00:25 +00:00

archvillainette added the Kind/Bug label 2026-08-07 21:15:21 +00:00

xtul approved these changes 2026-08-07 21:46:34 +00:00

archvillainette merged commit 3f1e33a39a into main

2026-08-07 21:46:37 +00:00

archvillainette deleted branch fix/wiki-drift-remote-hash

2026-08-07 21:46:37 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: ShadowsOverWestgate/sow-tools#104