Skip to content

Commit f7a954d

Browse files
wshallwshallclaude
andcommitted
docs(backlog): file #1445, the integer-seam vocabulary #1443 deferred
Kept in its own commit, last, per the Lander's rule: a docs/BACKLOG.md conflict confined to one commit is a scripted row-merge, while one interleaved with prose hunks needs a full re-read of the intent. This is a pure append at the file tail, so it should meet a sibling ledger edit only as an append and resolve by keeping both rows in numeric order. Verify a resolution with parse_items rather than by reading -- a conflicted ledger parses without error and yields a census counting both sides. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 parent 39da640 commit f7a954d

1 file changed

Lines changed: 46 additions & 0 deletions

File tree

docs/BACKLOG.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21997,3 +21997,49 @@ So `test_the_script_prefers_its_own_repo_over_an_earlier_path_entry` supplies th
2199721997
**Verification:** 8 passed in `tests/test_webconsole_seam_snapshot.py`. Mutation check run rather than argued -- with the `sys.path.insert` line deleted, the decoy test reds naming the decoy import, and the by-path digest test **stays green**, which is the luck described above measured rather than predicted. Anchor restored, 8 passed again.
2199821998

2199921999
**Adjacent and NOT fixed here, named rather than numbered.** `docs/WEBCONSOLE-PACKAGE.md`'s seam-refresh procedure is stale in three steps left behind by #1220: it says to bump `ENGINE_UI_SEAM` by hand (`1` to `2`) when the value is a derived digest, it says to update curated lists in this script that #1220 retired, and its step 5 prescribes `python scripts/webconsole_seam_snapshot.py > tests/golden/...`, the shell redirect this script's own docstring forbids because PowerShell's `>` writes UTF-16LE with a BOM into a file the test reads as UTF-8. That is doc drift with its own cause and it wants its own item; folding a documentation rewrite into a `sys.path` fix would make both harder to review.
22000+
22001+
---
22002+
22003+
## 1445. The web console package still speaks the retired integer-seam vocabulary in the sites #1443 deferred
22004+
22005+
> 🔢 **Filed 2026-09-04 - FIXED IN THIS COMMIT, not yet landed.** Found by the audit #1443 ran while rewriting the seam-refresh procedure, which named these sites in its own closing paragraph and deliberately left them out so a documentation rewrite stayed separately reviewable. LIMB 3 is why one more site than that paragraph named is fixed here.
22006+
> **Scored at filing 2026-09-04.** Value **2/10** · Difficulty **1/10** · _fill-in_. Value sits below #1443 on purpose: #1443 removed a procedure that manufactured a false green, and this removes the vocabulary left behind after it. No engine, PHI or deployment axis; the population is developers reading the console package. It is not a 1 because LIMB 1 is a comment that cannot be read to completion at all, which costs a reader more than a stale word. Difficulty 1 prices the remainder: five prose spans across four files, no code path, no test, no CI leg.
22007+
22008+
**Cluster:** repository tooling. **Priority:** P3. **Verdict:** build.
22009+
**Severity:** no engine effect, no PHI axis, and **no deployment axis (sec. 0)** -- every span here is a comment, a changelog line, a generator docstring or an ADR note. The shipped digest is unchanged: `python scripts/webconsole_seam_snapshot.py --digest` returns the same value before and after. The cost is a reader's session, and it is the same shape #1439 and #1443 record: prose that teaches a mechanism the code retired.
22010+
22011+
**What:** BACKLOG #1220 turned `ENGINE_UI_SEAM` from a hand-picked incrementing integer into a 16-hex-character SHA-256 digest of a surface `scripts/seam_discovery.py` discovers. #1443 rewrote the procedure page onto that. The sites below still speak the retired vocabulary.
22012+
22013+
| Site | Said | Shipped behaviour |
22014+
|---|---|---|
22015+
| `messagefoundry_webconsole/__init__.py:27-29` | "The engine contract **versions** this console build supports ... A pair **outside this set**", above a truncated fragment naming "Seam 9" | one seam, refused if it is not the one built against (#279) |
22016+
| `packaging/messagefoundry-webconsole/CHANGELOG.md:16`, `:25` | `[Unreleased]` supports "engine UI seam `2`, `3`", `SUPPORTED_ENGINE_SEAMS = {2, 3}` | a `frozenset[str]` holding exactly ONE digest |
22017+
| `packaging/messagefoundry-webconsole/CHANGELOG.md:10` | "each entry notes the supported engine seam(s)" | a value written into an entry cannot be kept current |
22018+
| `scripts/webconsole_seam_snapshot.py:13` | "failing CI on any **unbumped** incompatible change" | nobody bumps a derived digest |
22019+
| `docs/adr/0143:169` | `app.state.loopback` was "**curated** into the webconsole seam snapshot (no `ENGINE_UI_SEAM` bump)" | #1220 retired curation; true when written |
22020+
22021+
**LIMB 1 -- THE COMMENT WAS NOT STALE, IT WAS AMPUTATED, AND GIT NAMES THE CUT.** `messagefoundry_webconsole/__init__.py:29` read `# Seam 9 is the S8a console-dashboard lane (#76/#131/#136, ADR 0065 + ADR 0007 amendments): the` and stopped, mid-sentence, on the article "the". Commit `e5992c10f` wrote it as the first line of a five-line sentence. Commit `c01cb8294` -- the #279 narrowing, landed as `3ca4e6bb0` -- deleted the four continuation lines and left the opener standing as unchanged diff context. A reader reaching line 30 does not find the rest of the sentence; they find a different sentence about #279 and read on.
22022+
22023+
The fragment is **deleted rather than restored**, for three reasons. Its content survives in full and in better shape at `messagefoundry/api/_ui_seam.py:61-66`, so restoring it here would recreate the restatement SDS-3.5 forbids. It speaks the retired form: `_ui_seam.py:46-47` says the `vN` labels "are RETIRED as identifiers -- they no longer name the shipped value, they date the change", and the sanctioned shape is the framed `#: seam v9:` history entry, not a bare `Seam 9 is`. And it annotates a constant it now describes falsely: since #279 the console supports exactly one seam, and it is not 9.
22024+
22025+
**LIMB 2 -- DELETING THE FRAGMENT ALONE WOULD HAVE LEFT THE CONTRADICTION IT WAS HIDING.** The two `#:` lines ABOVE it carry the same pre-#279 range framing: "The engine contract **versions** this console build supports ... A pair **outside this set** is refused." Two lines below, the `#` block says the opposite -- "EXACTLY the engine seam it was built against, deliberately a single value, not a range". Removing the fragment between them puts the contradiction on adjacent lines.
22026+
22027+
An adversarial pass caught this, and it is the reason the fix is a three-line rewrite rather than a one-line deletion. The `#:` docstring now states what the constant IS, singular and without a set; the `#` block below keeps the WHY and the #279 citation, so the one-value rule is stated once (SDS-3.5).
22028+
22029+
**LIMB 3 -- ONE SITE WAS ADDED BECAUSE #1443's OWN DIFF ORPHANS IT.** `scripts/webconsole_seam_snapshot.py:13` still says "failing CI on any unbumped incompatible change". #1443 rewrites that exact word in the doc twin at `docs/WEBCONSOLE-PACKAGE.md:134` into "an incompatible change the seam did not follow", and its two hunks in the generator (`@@ -38,8 +38,17 @@` and `@@ -300,8 +309,8 @@`) do not reach line 13. So #1443 would land a corrected page beside the uncorrected code it documents, and a defer would leave the line owned by nobody. It is taken here, at line granularity.
22030+
22031+
**THE TWO SPANS #1443 DOES REWRITE IN THAT FILE ARE DELIBERATELY NOT TOUCHED** -- the module docstring's redirect paragraph and its duplicate in `write_seam_and_golden`. Editing them from here would conflict on exactly the lines an open change is rewriting, which is the collision #1220 exists to prevent, arrived at by hand.
22032+
22033+
**Merge safety was measured, not assumed.** `gh pr list --state open --limit 100` returned 24 open pull requests; two touch `messagefoundry_webconsole/__init__.py` and both edit only line 48, the constant. A three-way merge of this branch's `__init__.py` against each returned exit 0 with zero conflict markers, and the line-13 generator edit merges clean against #1443's head the same way.
22034+
22035+
**LIMB 4 -- THE CHANGELOG'S CONVENTION IS THE DEFECT, NOT ONLY THE TWO WRONG LINES.** `[Unreleased]` claimed the console supports "engine UI seam `2`, `3`" and printed `SUPPORTED_ENGINE_SEAMS = {2, 3}`, retaining seam `2` "because the new field has a default, so a seam-`2` engine still renders here". That reasoning is precisely what #279 retired as untested -- CI installs ONE engine, so every accepted seam but that one was exercised by nothing. Both lines are PRESENT-state claims about an unreleased build, and the shipped constant is a `frozenset[str]` of one digest.
22036+
22037+
The header three screens up is what would reproduce them: "each entry notes the supported engine **seam(s)**" instructs the next author to write a value into a changelog line, where it can never be updated. That is the rule `docs/WEBCONSOLE-PACKAGE.md` already states for its own heading, which said "currently 1" until seam 11. The banner now points at `SUPPORTED_ENGINE_SEAMS` instead of quoting it, and the header says why an older entry still quotes an integer.
22038+
22039+
**No value is written into any of this prose, and the reasoning is not restated either.** A first draft of the banner explained what a digest is and why the set holds one. That is a third copy of a fact `_ui_seam.py:27-29` states and #1443 states again on the procedure page, so the SDS-3.5 rule this item applies to the code applies to it: the banner points, and the citations carry the rest. `[0.2.15]`'s "Supported engine UI seam: `1`" is left alone -- it records what that release actually shipped.
22040+
22041+
**LIMB 5 -- THE ADR IS DATED, NOT EDITED, AND THE RULE IS WRITTEN DOWN.** `docs/adr/README.md:3-5`: ADRs "are append-only history -- supersede an ADR with a new one rather than rewriting it." `docs/adr/0143`'s acceptance checklist records that `app.state.loopback` was "curated into the webconsole seam snapshot (no `ENGINE_UI_SEAM` bump)". Both retired tokens sit on one line, and both were true on 2026-07-21. Editing the row would falsify the record of what was done at acceptance; leaving it bare would let a reader take a retired mechanism as live. A dated blockquote after the checklist does neither, and it matches how 0143's own Status line already carries its 2026-08-22 supersession by ADR 0172.
22042+
22043+
**Verification:** the commands run and their results are recorded in the pull request body, together with the legs only a hosted runner reports. The load-bearing one is that no contract moved: `python scripts/webconsole_seam_snapshot.py --digest` returns the same digest as `ENGINE_UI_SEAM` and `SUPPORTED_ENGINE_SEAMS`, before and after this diff.
22044+
22045+
**Adjacent and NOT fixed here, named rather than numbered, and at least these.** A sweep of the retired vocabulary across `messagefoundry_webconsole/`, `packaging/`, `scripts/`, `tests/`, `docs/` and `messagefoundry/api/` returned four more live sites this diff leaves alone. `tests/test_webconsole_seam_snapshot.py:11`, `:110` and `:125-127` carry "unbumped", "A seam bump has always required editing BOTH constants" and an assertion message opening "Bumping ENGINE_UI_SEAM requires updating..." -- #1443 examined that file, ruled it test prose rather than the procedure a developer follows, and left it "for whoever next edits that file"; nothing found here overturns that ruling, and a third hand on one gate's files in one week is how #1220's fault arrived. `messagefoundry_webconsole/_auth.py:297` and `docs/INSTALL-GUIDE.md:250` carry the same vocabulary in passing. And the root `CHANGELOG.md:302` says "A console wheel older than this engine refuses to mount, as designed" -- an ORDERING claim, where `assert_engine_seam` is a set-membership test (`messagefoundry_webconsole/__init__.py:62`), so a NEWER wheel is refused identically; that line was wrong when written and #1220's unordered digest only widens the gap. It sits inside a frozen `[0.3.1]` release block, which is why it is named rather than edited.

0 commit comments

Comments
 (0)