docs(webconsole): rewrite the seam-refresh procedure onto the derived digest (BACKLOG #1443) - #837
Open
wshallwshall wants to merge 7 commits into
Open
docs(webconsole): rewrite the seam-refresh procedure onto the derived digest (BACKLOG #1443)#837wshallwshall wants to merge 7 commits into
wshallwshall wants to merge 7 commits into
Conversation
… digest (BACKLOG #1443) The "Bumping the seam" procedure still described the pre-#1220 world, where ENGINE_UI_SEAM was a hand-picked incrementing integer over five hand-maintained tuples. Three of its seven steps had no meaning left, and the steps could not be executed in any order: a derived digest does not exist until the change is made and regenerated, so old step 2 asked the reader to write a value old step 5 had not yet computed. Steps 2 and 4 are gone. Nobody picks the value and there is no curated list to update. Step 5's shell redirect is replaced by --write, which rewrites the constant and the golden together. The redirect turned out to be wrong in every shell, not only under PowerShell: a redirect writes one of the two files --write writes, so it leaves the constant stale even where the encoding survives. Measured on Windows: PowerShell 5.1 emits UTF-16LE with a BOM, which the test cannot decode as UTF-8 at all; pwsh 7 emits CRLF, which diffs every line of a golden written with \n; Git Bash writes a clean file and silently does half the job. The fence was tagged bash, which advertised that last case. The console-side edit stays by hand, and the page now points at --write's own output for its literal text rather than restating it (SDS-3.5). The page keeps the reasoning the tool does not print: one value per #279, a test that reds CI on the same commit, and what re-widening the set would cost. Fixing only the numbered list would have left the page contradicting itself two screens earlier, so the same pass corrects the section that defines the term: the heading called the seam an integer, the prose typed it int and the console's set frozenset[int], and the implementation list said "three files" while describing a curated surface. It is four files with seam_discovery.py, the surface is discovered, and the generator has captured enum members and Literal value sets since #1220 -- an omission that matters, because the console indexes _SCOPE_NOTES[data.scope], so a renamed literal KeyErrors at runtime while a field-name-only snapshot stays byte-identical. Found 2026-09-03 while building #1439, which deliberately left it alone so a sys.path fix and a documentation rewrite stayed separately reviewable. That item's closing paragraph is updated to cite this one. No engine effect and no deployment axis (CLAUDE.md sec. 0): this is a developer procedure for a repository gate. The cost it removes is a corrupted golden and then debugging the gate that reported it. Verification: 8 passed in tests/test_webconsole_seam_snapshot.py; the derived digest 266cbfd342b22819 matches both ENGINE_UI_SEAM and SUPPORTED_ENGINE_SEAMS; backlog_status_check parses #1443 as open; link_check resolves 4839 links across 284 files under docs/. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…E.md line it lands on An adversarial verification pass caught a false claim in the preceding commit, and finding the real one made the warning much stronger. WRONG, now removed: that pwsh 7's CRLF output "diffs every line of a golden written with \n". It does not. Path.read_text performs universal-newline translation, so a CRLF golden and an LF golden compare equal -- measured directly. Only Windows PowerShell 5.1 damages the file, via UTF-16LE and a BOM. RIGHT, and it is worse than an encoding bug: the old procedure walks a developer into a state where the HEADLINE gate passes on a fabricated seam. build_snapshot() prints whatever ENGINE_UI_SEAM is imported, while contract_digest() never reads it, so hand-writing the constant and then regenerating the golden by redirect produces a golden that AGREES with the hand-written value. Reproduced in an isolated copy of messagefoundry/, messagefoundry_webconsole/, scripts/ and the golden, with an assertion that the generator read the copy and not the real tree: hand-written seam in source : deadbeefdeadbeef seam recorded in the golden : deadbeefdeadbeef test_webconsole_seam_snapshot_matches_golden : PASS test_the_stored_seam_equals_the_derived_digest : FAIL Exactly one test refuses it. The page now says so. RELEASE.md is the terminus of the procedure's last step, and its opening told the reader to keep "the seam integers" honest -- the retired vocabulary, one line after leaving it. It now says digests and names #1220. A repo-wide sweep with a positive control found the shell redirect surviving in exactly one place, the page fixed here. There is no second copy, .github/ included. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… it from #1439 Records what the preceding commit fixed and how each claim was measured: the three retired steps, the ordering that made them unfollowable, the redirect measured in three shells, and the drift outside the numbered list. Also updates #1439's closing "Adjacent and NOT fixed here, named rather than numbered" paragraph, which asked for exactly this item. Two of its three descriptions were sharpened by measurement while building the fix, and the paragraph now says so rather than being silently superseded. Kept in its own commit, last, so the Lander gets a scripted row-merge rather than a conflict tangled with prose changes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ll-specific one The generator's docstring said a shell redirect is forbidden because PowerShell writes UTF-16LE with a BOM. Accurate, and the wrong thing to publish: a reader on Git Bash consults it, correctly concludes it does not apply to their shell, runs the redirect and silently does half the job. The warning licensed the failure it exists to prevent. SDS-3.4 asks what a reader would DO with a sentence, not whether it is true, and this one fails that test. The real failure is shell-independent and worse. A redirect writes the golden and never the constant, and build_snapshot() prints whatever ENGINE_UI_SEAM is imported, so the redirected golden AGREES with a hand-typed value: test_webconsole_seam_snapshot_matches_golden goes green on a fabricated deadbeefdeadbeef, and only test_the_stored_seam_equals_the_derived_digest refuses it. The docstring now leads with that and demotes the encoding to a second, shell-specific hazard, naming what pwsh 7 and Git Bash actually do. The duplicate of the same fact at the write site becomes a pointer rather than a second copy (SDS-3.5). Comment-only: ruff clean, mypy clean, 8 passed, and the derived digest is 266cbfd342b22819 before and after. Raised by the session that authored the line under BACKLOG #1439, which declined to open a competing branch for two comment lines and handed it over. Taken here because this is the change that cites the behaviour. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Scores the item as it is filed rather than leaving it for a later pass. Nothing in CI requires a score at filing, so an item enters the ledger unranked and stays that way until a pass reaches it; five items filed since the 2026-09-03 pass already carry none, and this would have been the sixth. Value 3, difficulty 2. Value is above the bottom of the table because the defect is not cosmetic staleness: the old procedure walks a reader into a state where the headline gate PASSES on a fabricated seam. Difficulty prices the two controls that made the prose honest, not the prose. Also moves scripts/webconsole_seam_snapshot.py out of the item's not-fixed list, since the preceding commit fixed it, and records why that handover was accepted. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… already done The digit stays 2. The reasoning behind it was wrong, and the reasoning is what a later scoring pass reads. It said difficulty priced "the prose plus the two controls that made it honest". The table prices only the remainder -- docs/BACKLOG.md:203 says so outright, and every difficulty-1 row in it reads "the remainder is a doc edit". Investigation already run is not remainder, and counting it would make a well-investigated item cost more than a careless one, inverting the scale. Restated on remainder grounds: four small prose edits on existing seams, no code path, no test, no CI leg, which is where #1381 sits at the same digit. What the controls bought is recorded in LIMB 2, which is where it belongs. The error is recorded in the line rather than quietly overwritten, because an item about prose that teaches a wrong method should not contain one. Raised by a peer session that also argued 4/1 over 3/2 and then showed the two are within noise -- tier and quadrant are pure functions of the pair and both give _fill-in_ / P3 -- so only the reasoning changed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
wshallwshall
added
the
reviewed
…erge The rule was headed "on a merge conflict over the seam", so a reader whose merge came out clean skipped it. That is the wrong half to skip. The three files do not conflict together. The constant is one line and collides visibly; the golden is long and its sections auto-merge. That is the #1220 origin story exactly, and _ui_seam.py already records it: two branches, a cosmetic conflict in the constant's comment block, a golden that merged clean carrying both changes, and resolving the visible conflict correctly still shipped the fault. Nothing raises its hand for the half that merged quietly. So the rule now leads with "after any merge that moved the contract surface, regenerate; a clean merge is not evidence of a correct digest", and the conflict case becomes one arm of it. Also states the consequence, because it is not what a reader guesses. test_the_stored_seam_equals_the_derived_digest RECOMPUTES from the surface rather than comparing two stored copies, so a stale digest reds CI and main stays clean. It presents as an unrelated-looking test failure on a merge somebody just resolved by hand, which is how a reader ends up debugging the gate instead of rerunning --write. Raised by a peer session that hit the conflict case live earlier today, and that corrected its own first framing of the consequence from a startup refusal to a red CI leg before offering it. Verified here against the test and against _ui_seam.py:33-37 rather than taken from the summary. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
github-actions
Bot
removed
the
reviewed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rewrites
docs/WEBCONSOLE-PACKAGE.md's seam-refresh procedure onto the behaviour BACKLOG #1220 actually shipped. Files:docs/WEBCONSOLE-PACKAGE.md,scripts/webconsole_seam_snapshot.py,packaging/messagefoundry-webconsole/RELEASE.md,docs/BACKLOG.md.The three named steps
ENGINE_UI_SEAMby hand, "e.g.1->2"test_the_stored_seam_equals_the_derived_digestfails any hand-written valuescripts/seam_discovery.pydiscovers the surfacepython scripts/webconsole_seam_snapshot.py > tests/golden/...--write, which rewrites the constant and the golden togetherSteps 2 and 4 are gone outright. Nobody picks the value and there is no list.
The old steps were unfollowable, not merely mislabelled
A derived digest does not exist until the change is made and regenerated. Old step 2 asked the reader to write a value old step 5 had not yet computed, and old step 3 asked them to copy it to the console before that. There is no order in which they execute, so a reader who follows them faithfully cannot finish -- and the first thing they doubt is the gate rather than the page.
Step 5 fails in the worst direction, and this is the finding that matters
build_snapshot()prints whateverENGINE_UI_SEAMis imported;contract_digest()never reads it. So hand-writing the constant and then regenerating the golden by redirect produces a golden that agrees with the fabrication. Reproduced in an isolated copy ofmessagefoundry/,messagefoundry_webconsole/,scripts/and the golden, with an assertion that the generator read the copy and not the real tree:The gate whose name says it compares the snapshot accepts
deadbeefdeadbeef. Exactly one test refuses it. The page now says so.A false claim was caught and corrected between commits, and the second commit is that correction. The first draft said
pwsh7's CRLF output "diffs every line of a golden written with\n". It does not:read_textperforms universal-newline translation, so a CRLF golden compares equal. Measured across three shells, only Windows PowerShell 5.1 damages the file (UTF-16LE + BOM, which the test cannot decode at all). The encoding was never the common failure -- writing one of two files is, in every shell including thebashthe fence advertised.The drift was wider than the numbered list
Fixing only the steps would have left the page contradicting itself two screens earlier:
ENGINE_UI_SEAM-- the handshake integer", and typed the constantintand the console's setfrozenset[int]. Shipped:strandfrozenset[str].seam_discovery.py, and the surface is discovered. The description also predated two capture classes the generator has carried since #1220 -- enum member sets andLiteralvalue sets. That omission is load-bearing: the console does_SCOPE_NOTES[data.scope](pages/uploaded_logs.py:82), so a renamed literalKeyErrors at runtime while a field-name-only snapshot stays byte-identical, which is exactly what the section claims to be the sole backstop against.Two additions the page never had
On a merge conflict over the seam, neither side is correct. When two branches both move the surface, all three files holding the value conflict and the merged surface derives a third digest matching neither. Taking either side ships a value describing no tree that exists, and it looks like an ordinary conflict resolution.
_ui_seam.pystates this as the reason a digest cannot collide the way the integer did, but nothing told a developer standing in the conflict what to do. Reported live by a peer session (branchd4ae2ce03d5723a7, main266cbfd342b22819, merged767521d4399d1ef4); deterministic from the digest's construction.RELEASE.mdis the terminus of the last step and told the reader to keep "the seam integers honest" -- the retired vocabulary, one line after leaving it. Now digests, naming #1220.Two things deliberately not added
A
PYTHONPATHpin before the generator runs, because #1439 anchored the script on__file__and that test's_ANCHOR_HINTforbids the call-site pin by name, citing this very by-hand procedure. And the digest's value anywhere in prose -- the section's own older rule is that a value quoted in prose goes stale silently, which is how it came to say "currently 1" until seam 11.Scope
A repo-wide sweep with a positive control found the shell redirect surviving in exactly one place, the page fixed here.
.github/, ADR 0065,docs/ASVS-L2-PHASE0-CHANGES.md, the package README and INSTALL-GUIDE are all correct and were left alone. The retired tuple names appear in no doc.Named, not fixed, so the procedure stays separately reviewable (the same courtesy #1439 paid this item):
messagefoundry_webconsole/__init__.py:29is a truncated comment ending mid-sentence on "the", naming an integer seam identity.packaging/messagefoundry-webconsole/CHANGELOG.md:16/:25make a present-state[Unreleased]claim that the supported seam is2, 3-- wrong on the type and on docs: repoint 73 backlog citations at the archive (BACKLOG #1095) #279's one-value rule.docs/adr/0143:72names the retired curation mechanism; an accepted ADR is better dated than edited.tests/test_webconsole_seam_snapshot.py:106-127carries the same chosen-number connotation in test prose.docs/LEDGER-GATE.md:132creditsinstall-git-hooks.ps1with installing the ledger gate, which its own synopsis says it no longer does, and:164's anchors have drifted toledger_check.py:376and:465.RELEASE.md's banner says the wheel is published whilepyproject.toml:187-189still says it is not.One sibling taken on a handover
scripts/webconsole_seam_snapshot.py:41gave the redirect's reason as the PowerShell encoding alone. Accurate, and the wrong thing to publish: a reader on Git Bash consults it, correctly concludes it does not apply to their shell, runs the redirect and silently does half the job -- the exact case measured above, licensed by the warning meant to prevent it. SDS-3.4 asks what a reader would DO with a sentence, not whether it is true, and that one fails.It now leads with the one-of-two-files failure and the false green, demotes the encoding to a shell-specific second hazard naming what
pwsh7 and Git Bash actually do, and says outright that an earlier version gave only the encoding reason. The duplicate at:303becomes a pointer rather than a second copy (SDS-3.5).Raised by the session that authored the line under #1439, which declined to open a competing branch for two comment lines and handed it over. Comment-only: ruff clean, mypy clean, and the derived digest is
266cbfd342b22819before and after.Scored at filing
#1443 carries Value 3/10, Difficulty 2/10,
_fill-in_. Nothing in CI requires a score at filing, so an item enters unranked and stays unranked until a pass reaches it -- five items filed since the 2026-09-03 pass already carry none, and this would have been the sixth. Value is above the bottom of the table because the defect is not cosmetic staleness; difficulty prices the two controls that made the prose honest, not the prose.Checks
Run here, before committing:
pytest tests/test_webconsole_seam_snapshot.py -q-- 8 passedpytest tests/test_release_pipeline.py -q-- 26 passedscripts/docs/backlog_status_check.py --quiet-- rc=0;parse_itemsreports #1443 open, 429 itemsscripts/docs/link_check.py docs-- 4839 links across 284 files, all resolvescripts/webconsole_seam_snapshot.py --digest--266cbfd342b22819, matchingENGINE_UI_SEAMandSUPPORTED_ENGINE_SEAMSruff format --check+ruff check+mypyonscripts/webconsole_seam_snapshot.py-- all cleanpre-commithooks on each of the five commits Legs that only run on a hosted runner were not seen from here and want reading after merge.Two instruments were corrected mid-task rather than trusted:
link_check.pygiven a file path reported "OK" over zero files, and a first glyph scanner had a bad\uescape that flagged the digit 6. Both re-run with positive controls.BACKLOG.md is its own commit and last, so a conflict resolves as a scripted row-merge.
🤖 Generated with Claude Code