fix(docs-audit): widen the ledger key anchor past the word boundary (#11630)

[os-steve]

Fixes#11630

declLead in scripts/docs-audit/affected-docs.mjs anchored the ledger route: / client: key with a word boundary. A word boundary fails only against a preceding word character ([A-Za-z0-9_]). $ is not one, and $route is a legal JS identifier, so $route: was read as a declaration by all eight lead scans — they agreed, and they agreed by being wrong together. That is exactly the "agreed-and-wrong" end state #11542's card rejected on sight when it was proposed as the other direction for the key.

The anchor is now a negative lookbehind, still spelled once, in declLead. It is spelled verbatim in declLead's docblock and in the --self-test boundary comment, and deliberately not here: GitHub's body sanitizer strips the less-than + bang digraph out of an issue or PR body — inside code spans and fenced blocks alike — and silently leaves a different, valid-looking regex behind. Measured twice on #11634.

The character SET is the load-bearing half — and it is not the one the card named

The card and the old docblock both named the excluded set as word characters plus $. That is dottedRe's set, and it is the wrong analogue. Three lookbehind idioms already live in this file and they exclude three different classes:

idiom	excludes	because its token is
symbolRe	word chars, $, .	a bare token — not a longer identifier, not a member
dottedRe	word chars, $	a dotted token, which must tolerate its own dots
rulePatternFor / commandPatternFor	word chars, $, ., -	a doc-side prose span, where - glues tokens in English

declLead's key is a bare token, so symbolRe's set is the analogue and the shipped set is word characters, $and .. Copying the nearest idiom blindly is how a fix comes out right about the mechanism and wrong about the class.

. was found by measurement, not assumed from the card: a . before the key makes the token a member access, and the colon then belongs to a ternary and never to a key. cond ? defaults.route : 'GET /api/v1/gone' minted a phantom row on a path nobody declares. Pinned as its own fixture.

- is deliberately left out, which is the one place this departs from rulePatternFor. a-route is two tokens (a - route), so that routeis the whole token route — it is not a declaration for a different reason (expression position), and that reason is shared with the bare cond ? route : x that no lookbehind can reach. Excluding - would close one spelling of that class while leaving its plainest spelling open: enumerating escapees wearing a character class. Pinned as still-admitted, deliberately.

It can only ever REMOVE — swept, not argued

The key alternation always opens with a word character, so the old word boundary failed exactly when the previous character was a word character, which makes the new anchor a strict subset. Swept over code points 0..0x2FFF:

	admits
old word-boundary anchor	12225
this branch's anchor	12223
admitted by this branch but not by the old anchor	0

Exactly 2 characters move: $ and .. Both numbers are pinned in --self-test, so a future widening that admits something the old anchor did not fails there.

TWO populations priced, not one — this is the harder move

⚠️#11634's before/after was priced specifically to leave declarationsIn byte-identical. Widening past the word boundary moves declarationsIn too. That is a second population with its own before/after, and it is priced separately below. This is not the same measurement as #11634's and is not reported as such.

Both are priced at row identity, not counter equality — counters agreeing is consistent with two rows swapping places.

Population 1 — the ledger rows (--bridge-coverage)

	base ffbb7a100	ablated (anchor reverted)	this branch 6de837d30
rowsParsed / routesDeclared	269 of 269	269 of 269	269 of 269
clientRows / clientsDeclared	222 of 222	222 of 222	222 of 222
reachable / unreachable	45 / 177	45 / 177	45 / 177
leadsOutsideCode	0	0	0
brokenScan	0 (exit 0)	0 (exit 0)	0 (exit 0)
tails / ledger files / registrar files	43 / 7 / 12	43 / 7 / 12	43 / 7 / 12

Which rows move: none.--bridge-coverage --json carries all 177 unreachableRows by {file, route, client}, and git hash-object gives d04a5cedfb613370e5b46ac4725db1d941e5dc88 on all three trees — base, ablated and fixed. Set difference over {file, route, client} is 0 in each direction. The human-rendered output diffs empty. That is the same hash #11634 reported, so this ledger population has not moved since it merged.

Population 2 — declarationsIn, the eighth scan (NEW to this card)

Measured by slicing declarationsIn and its dependency closure (codeOnly, typeDeclRegions, declLead — walked, not hand-listed) out of the file and running the file's own bodies over the seven live ledgers:

tree	ledgers	declarations	git hash-object
base ffbb7a100	7	491	7f89c810a6060a3a2755f16a00295f42774749e3
ablated	7	491	7f89c810a6060a3a2755f16a00295f42774749e3
this branch 6de837d30	7	491	7f89c810a6060a3a2755f16a00295f42774749e3

Positive control — the instrument is sensitive, and proven so before the zero was believed. Run over a synthetic ledger carrying both escapees, the same harness reports 5 declarations on the base tree and 3 on this branch, and the diff names exactly the two that disappear:

< "index": 43, "key": "route", "quote": "'", "text": "route: 'GET /api/v1/dollar'"
< "index": 183, "key": "route", "quote": "'", "text": "route: 'GET /api/v1/dotted'"

Why both are free on today's tree — re-derived, not inherited from #11634

Across the seven live ledgers there are 499route: / client: lead occurrences, and every one of them is preceded by a space: 0 preceded by $, 0 by ., 0 by any non-word character at all. Positive control: the same tally reports $ and . correctly (and a word character as blocked) the moment a fixture carries them, so the zero is a reading and not a blind scan.

The pin is FLIPPED, not deleted

--self-test pinned $route:'s behaviour as deliberately unmoved so this card would flip an existing pin. Both pinned assertions are moved, and the boundary comment above them is rewritten to record what moved — the same treatment #11542 gave the pin #11584 left it.

pinned assertion	before	after
a `$route:` still mints a phantom row — deliberately unmoved	2 rows	flipped → a `$route:` mints NO row , 1 row
and it is still SILENT — all eight scans agree, so both terms move together	2 route / 0 declined	flipped → and the DENOMINATOR drops it too, 1 route / 1 client / 0 declined
the run between a colon and its value is spelled ONCE	matched the word-boundary spelling	updated to the new anchor's spelling
and the KEY anchor is spelled once too — no call site restates it	rejected a restated word boundary	widened to reject a restated word boundary or a call site's own lookbehind
every key spelling a call site passes comes back ANCHORED	three word-boundary spellings	updated to the three new spellings

Two new boundary pins are added in the same shape, so the next card of this family moves a pin rather than finding none: - still admits, and a Unicode identifier character still admits (\w is ASCII-only, so éroute: passes exactly as it did before — closing it means a \p{L} class under the u flag, which changes escape semantics for every source these leads are composed with at the eight call sites). 0 occurrences of either across the seven live ledgers.

Reverse verification (ablation) — mutation proven on disk, restore under a trap

The one line the fix moved was reverted to its exact pre-fix spelling, under trap … EXIT INT TERM armed before the mutation. affected-docs.mjs is run directly from source by node — there is no dist/ in its path, so no rebuild leg is involved and none is claimed. Mutation confirmed on disk by counting the injected and the removed text separately, anchored on the exact text meant to move (a bare diff --stat goes green on any same-round edit), plus hashes:

CLEAN_HASH=15da4f14a5971922e38c2f60874b60c220f07c85
ON DISK: injected=1 (want 1) removed=0 (want 0) # declLead anchor
MUTATED_HASH=e6b954a887cff518da2190e8b286e84a298b2188
RESTORED_HASH=15da4f14a5971922e38c2f60874b60c220f07c85 (byte-identical)

Direction predicted before running: turn red on the new pins, and a named set of controls stay green. Observed exactly that — ABLATED_SELFTEST_EXIT=1, 16 checks fail, and each got value is the before state:

✗ "a `$route:` mints NO row — the anchor excludes identifier CONTINUATION" expected 1, got 2
✗ "and the row that survives is the REAL one, carrying its binding" got "GET /api/v1/gone → null"
✗ "and the DENOMINATOR drops it too, so no phantom gap opens" got "2 route / 1 client / 0 declined"
✗ "a `$route:` does not CLOSE the real row window" got "2 row · GET /api/v1/meta → null | GET /api/v1/gone → meta.getTypes"
✗ "a `$client:` does not become the row BINDING" got "wrong.binding"
✗ "and the real `client:` is bound, not swept up as unclaimed" got "2 client / 1 declined"
✗ "a double-quoted `$route:` is not billed as a DECLINED row" got "1 row / 2 route / 1 declined"
✗ "so no PARTIAL-read verdict fires on an accurate ledger" got brokenScan 1
✗ "a `$route:` in PROSE is not reported as a prose-quoted lead" got outsideCode 1
✗ "a non-literal `$route:` is billed to nothing — the EIGHTH scan moved" got "1 row / 2 route / 1 declined"
✗ "and `declarationsIn` moving fires no PARTIAL-read verdict either" got brokenScan 1
✗ "a member-access `.route :` in a TERNARY mints NO row" expected 1, got 2
✗ "and it leaves the denominator alone as well" got "2 route / 1 client / 0 declined"
✗ "the run between a colon and its value is spelled ONCE" expected 1, got 0
✗ "every key spelling a call site passes comes back ANCHORED" got the three word-boundary spellings
✗ "and the characters it moves are exactly `$` and `.`" expected 2, got 0

The controls that stayed green are the point, not an omission — each is a fixture that must be green both ways, and a red one would mean the fixture, not the fix, was doing the work:

• a `-`-prefixed lead still mints a row and a UNICODE-prefixed lead still mints a phantom row — the two boundaries this card deliberately does not cross.
• and the widened read carries no verdict on an accurate ledger (brokenScan 0) and and a `$route:` in CODE position is not reported as a prose-quoted lead — this is the silence the card is about: both terms move together, so no verdict ever fired.
• and the KEY anchor is spelled once too — 0 restatements on both trees.
• the anchor only ever REMOVES — 0 on both trees, since the ablated anchor is the one being compared against.
• and the real row keeps its binding across it (the . fixture) — the real row is ahead of the phantom there, so it keeps its binding either way.

Non-vacuity in the other direction is carried by the same fixtures: the genuine route: 'GET /api/v1/meta' is still read, still carries meta.getTypes, and the 269 live rows are unchanged.

Ablated row identity is also reported: both populations hash identically to base and fixed under ablation (d04a5ced… and 7f89c810…), which is what makes the "free on today's tree" claim a three-way measurement rather than a two-way one.

Verification

Base origin/mainffbb7a100; measured and re-measured on final commit 6de837d30.

Gate union derived, not recalled — node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no paths; the script takes the change set from the merge base itself), 9 families, plus check:nul-bytes and the self-test directly. The derivation is fresh for this card: it names check:agent-test-spelling, which #11634's run did not carry. Exit codes captured before any pipe; each verdict below is the line the gate itself printed.

gate	exit	its own verdict line
pnpm check:agent-test-spelling	0	✓ check-agent-test-spelling: 0 violations — 351 file(s) · 3319 bare -- token(s)…
pnpm check:cross-package-test-inputs	0	OK: 16 package(s) read outside themselves, all declared…
pnpm check:docs-audit-scope	0	✓ docs-accuracy-audit scope is in sync with content/docs/: 189 hand-written doc(s).
pnpm check:entry-guard	0	✓ check:entry-guard: 143 scripts/ file(s) — every entry guard goes through invoked-as.mjs
pnpm check:parse-guard	0	✓ check:parse-guard: 142 scripts/ file(s) — every TypeScript parse goes through ts-parse.mjs.
pnpm check:pm-governed-merges	0	✓ check-governed-merges --self-test: 129 assertions
pnpm check:pnpm-filter-targets	0	✓ check:pnpm-filter-targets: 134/167 --filter occurrence(s)… resolve
node scripts/check-cross-package-test-inputs.mjs	0	OK: 16 package(s) read outside themselves, all declared…
node scripts/docs-audit/check-affected-docs.mjs	0	✓ affected-docs self-test: 413 cases pass.
pnpm check:nul-bytes	0	✓ check-nul-bytes --self-test: 75 assertions over a temp git repo
affected-docs.mjs --self-test	0	✓ affected-docs self-test: 413 cases pass. (base: 395 — +18)

Lint — the full repo-wide run, not a narrowing.pnpm lint (eslint . --no-inline-config) was run in full on 6de837d30: exit 0, no findings, 54s under the shared verify lock. No narrowing is claimed and none is needed.

No changeset — checked against the actual rule, not inherited.changeset-check in .github/workflows/pr-automation.yml has no path exemption; the skip-changeset label (or the changesets release PR) is the only route. This diff is one file under scripts/, which publishes nothing: the root package is private: true with no files field, scripts/ is not inside any pnpm-workspace.yaml glob, and it has no package.json of its own. skip-changeset applied and read back.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

[os-steve]

ACCEPT. Verified by content, and both of my Zone 2 falsifications fired — which is the point of putting them there.

The card named the wrong character class, and you caught it

I warned that copying the precedent idiom blindly would give "a fix that is right about the mechanism and wrong about the class." That is exactly what would have happened:

symbolRe (?<[\w$.]) word chars + $ + . ← the analogue for a BARE token
dottedRe (?<[\w$]) word chars + $ ← what the card and the old docblock named
branch declLead → (?<[\w$.])${keys}\s*:\s*

The card, and the docblock #11634 left behind, both pointed at dottedRe. declLead's key is a bare token, so symbolRe is the analogue — and reading all three idioms to discover they exclude three different classes is the step that separates a correct fix from a plausible one.

And it found a second escapee nobody named

A preceding . makes the token a member access whose colon belongs to a ternary — cond ? obj.route : 'X' — minting the identical phantom row. That is not the same defect as $route:; it arrives through a different grammar and would have survived a fix built to the card's spec. Closed and pinned.

- correctly left out, with the reason stated rather than the omission left silent: a-route is two tokens, so route genuinely is the whole token — it is not a declaration for a reason no lookbehind can reach, which it shares with the bare cond ? route : x. Declining with a reason is worth more than closing it by accident.

The second population move — measured, not argued

This is the part I flagged as harder than what it inherits, and it was done properly. #11634's before/after was priced to leave declarationsInbyte-identical; yours moves it, so it needed its own instrument:

• declarationsIn plus its dependency closure walked, not hand-listed, run over the seven live ledgers: 491 declarations, hash 7f89c810… identical on base, ablated and fixed.
• ⭐ The positive control was run before the zero was believed — over a synthetic ledger carrying both escapees the same harness reports 5 vs 3 and names exactly the two that disappear. So the live byte-identity is a reading, not a blind scan. That ordering is the whole difference between a measurement and a hope.

Population 1 held to #11634's standard too: --bridge-coverage --json hashing d04a5ced… across all three trees, set difference 0 in each direction.

⭐ "Free on today's tree" re-derived rather than inherited — 499 live leads, every one preceded by a space, 0 by $, 0 by ., 0 by any non-word char, with a control confirming the tally can report them. I explicitly forbade inheriting #11634's argument and you re-earned it instead.

⭐ The subset invariant swept, not asserted: over code points 0..0x2FFF the old anchor admits 12225, the new 12223, and the new admits 0 the old did not. Exactly two characters move. Both numbers pinned. "Anchoring only ever removes" stops being a claim and becomes a fact under test.

Pins went UP

deliberately-unmoved pins 2 → 4

The one #11634 left is flipped, three source pins updated, two new residue pins added. Nothing deleted — verified by count, not by assertion.

⭐ The self-test caught you, and you did the right thing with it

my first draft of the subset-sweep probe compiled declLead directly and tripped the 'all eight lead scans, none inline' pin (expected 8, got 9). Rebuilt it through a named intermediate … rather than bumping the pin to 9, which would have blunted the pin that exists to catch a real ninth scan.

Bumping 8 to 9 would have been green in one minute and would have destroyed the only thing that catches a genuine ninth scan. Reporting that you were caught, rather than quietly fixing it, is what makes the rest of the report credible.

Ruling on your open question — B, and it is my call, not the maintainer's

You recommended B as the end state, A as the next step, and flagged B as a maintainer decision. I agree with the first two and take the third back.

This is not a maintainer question. It is an implementation-approach choice inside one file on this lane's own surface — no product tradeoff, no fleet shape, no permission I lack — and you have already measured the thing that decides it: all 499 live leads are preceded by a space, so an allowlist is provably free on today's tree by the same argument each lookbehind card has used. Escalating a decision I have the evidence to make would be padding a queue whose four remaining items all genuinely need a human.

So: B is the end state. I am filing it as its own card now, with your measurement as its affordability argument, and ⛔ #11711 is blocked on it rather than dispatched — B subsumes the Unicode residue, and shrinking one more character class first is work B discards.

A was the right next step and it is this PR. The chain stops here.

Flipping ready; arming once every check is green.

---

Generated by Claude Code