fix(docs-audit): a registration bounds the previous handler window even when its path is a variable

[claude]

Fixes#9503

Third and last layer of the same defect family in scripts/docs-audit/affected-docs.mjs:
#9294/#9431 kept container symbols out of the route bridge, #9432/#9502 made the
identifier scan read comment-masked source, and this one is the window boundary.
Neither of those two behaviours is touched.

The defect, re-measured on today's main (e7daea169)

parseRegistrarSource conflated two different questions on one line. "Does a registration's
property list start here?" decides the window boundary; "which route is it?" decides the
tail. Only the second needs a literal, but both were answered by the same
literal-only regex — so a registration written path: publishedPath was neither a site nor a
boundary, and the previous route's window ran its full 150 lines straight through it.

The card's numbers hold exactly. packages/** registrar files carry 86 literal path:
lines and 33 that are not literals, and there is exactly one place where a
non-literal one falls inside a live window:

/:name/state/:field site rest-server.ts:5661
next LITERAL path: 5916 (255 lines later), so the window
runs its full 150 lines and ends at 5810
path: publishedPath at 5747 is inside it and invisible
=> 64 lines of the `published` handler sit in the
`state` route's window

The measurement the card did not have: today that costs ZERO rows

This is the finding worth reading before the diff. Of those 64 over-run lines, 55 are the
ADR-0033/#8278 commentary that #9432 masks to blank, and the remaining 9 are
for/register/method/handler/try/const boilerplate whose every token already
occurs earlier in the same window. So the over-run reaches no identifier the route did not
already have:

	before	after
registrar tails, whole tree	42	42
identifier slots, whole tree	3320	3320
/:name/state/:field window ids	87	87
identifiers gained / lost	—	0 / 0

60-commit recall sweep (the #9432 bar), every commit touching packages/ back to
fab693bee, each run twice from the same parent with only this hop swapped: 60 runs, 0
substantive differences, 380 advisory rows identical. The only textual delta in 6 of the 60
JSON outputs is computedOn.dirty, which flips because the harness itself overwrites the
script in the checked-out tree — not a row.

So: the mechanism is real and verified, the harm is latent.#9432's comment mask is what
is holding it down, and it holds it down by accident of comment length.

What is underneath it

Measure the same span against the foreign handler's own 150 lines and it carries 18
identifiers the state route does not otherwise see:

getMetaItemLayered getPublished resolveProtocol publishedProtocol overlayError
resolveExecCtx resolveMetadataService publishedCtx overlay layered kernel
organizationId tenantId svc data number Not throw

That is the published route's implementation — including the exact name
rest-route-ledger.ts binds /:type/:name/published to (meta.getPublished). Shorten that
comment block by a screenful and a published-handler diff starts putting the state-machine
page on the advisory with a via naming a symbol it really does implement, for a route it
does not. The window's invariant is "this span is ONE route's handler"; the invariant is
false today and free today. Both halves are true, and the fix costs nothing to take now.

The change

Three lines. A path: line is always a site; only a literal one carries a tail. The
loop already tolerated tail-less sites — 38 of the 86 literal lines yield no tail (a bare
/api/v1, a mount prefix) and are skipped for window production while still bounding the
previous site. A non-literal line now behaves identically.

Tests — 233 to 242 self-test cases, pinned in three directions

• the foreign handler's symbol must not bridge to the previous route;
• the site's own symbol must still bridge (a boundary rule that over-truncates would
  trade this precision bug for the recall hole the bridge exists to fill);
• a path: written in a comment must still bound nothing — new risk this change
  introduces and docs-drift's route bridge counts identifiers found inside COMMENT text — an English sentence in a handler can mint a route anchor #9432 could not have pinned, because before it a commented path: could
  only mint a phantom tail, and now it could also truncate a real window;
• counterfactual, parseRegistrarSource verbatim as it stood before this hop, asserting
  the fixture really does carry the defect and that the boundary, not the 150-line cap, is
  what closes it.

Reverse-verified from the committed state — reverting only the code hop and keeping the
tests turns exactly the two precision assertions red:

✗ "the NEXT route's handler symbol is not this route's implementation": getMetaItemLayered
→ expected parseRegistrarSource=false, got true
✗ "a diff touching only the FOREIGN handler's symbol selects no route": tails
→ expected bridge="[]", got "[\"/:name/state/:field\"]"
✗ affected-docs self-test failed (2 case(s)).

Deliberately NOT in scope

The recall half. A variable-path route still gets no window of its own, so nothing
bridges to/:type/:name/published. Resolving publishedPath needs a one-hop binding
lookup, and the hole it would dent is a small slice of a much larger one: 176 of the 221
client-bound ledger rows have no registrar tail at all today, most of them plugin-auth
routes that never take a path: property. That is a different card with a different
measurement; filed separately. The self-test states the omission as an assertion on the
emitted tails rather than leaving it to be discovered.

Also corrected from the card: metadata/src/routes/hmr-routes.ts:107 is not a
registration — it is a path: key in a broadcast({ ... }) payload. It is a boundary now
regardless, and falls inside no window either way.

Gates run locally, on 486b43dff (the final commit)

pnpm check:docs-audit-scope ✓ affected-docs self-test: 242 cases pass
✓ check-audit-scope self-test: 22 cases pass
node scripts/docs-audit/check-affected-docs.mjs ✓ 242 cases pass
pnpm check:nul-bytes ✓ 75 assertions; 6157 files, no control bytes

Derived at runtime from the changed path with
node scripts/pm/dispatch-gates.mjs scripts/docs-audit/affected-docs.mjs, after the final
commit. Scripts-only, publishes nothing: skip-changeset.

---

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.