[finding] An evidence-based registrar route reaches 14 more client-bound rows and closes the storage ledger — but it redefines "registrar" to include Zod contract declarations, and admits 3 non-registrars

[os-steve]

Measured while investigating #11178, and deliberately not landed there. #11178's premise was falsified (the auth surface is unreachable because it has no in-repo registration site at all, not because discovery misses one), so the evidence route below does not serve that card — but it is a real, measured improvement to a different population, and it carries a contract question that deserves its own ruling rather than riding along.

Filed unassigned and unlabelled for grading. ⛔ Not a claim on anyone's time.

What was measured

scripts/docs-audit/affected-docs.mjs discovers route registrars by filename convention:

REGISTRAR_FILE_RE = /(?:^|\/)(?:[\w.-]*route[\w.-]*|[\w.-]*-server)\.ts$/ // :287

An additional admission route — admit any non-test packages/**/*.ts whose masked source yields ≥1 route tail through the real parseRegistrarSource — was implemented and measured on origin/main @ a6eca9223, then reverted (tree restored byte-identical under a trap … EXIT INT TERM, sha back to 839fe0c5).

reading	before	after
registrar files scanned	12	20
route tails produced	43	82
client-bound rows reachable	45	59
storage ledger unreachable	7 of 7	0 of 7
i18n ledger unreachable	3 of 3	1 of 3
runtime ledger unreachable	65 of 69	62 of 69
rest ledger unreachable	46 of 87	44 of 87
plugin-auth unreachable	56 of 56	56 of 56 (unchanged — see #11178)

No reach regression is possible in that direction by construction: selectsFrom is a some() over the tail list, so added tails can only add selections. Every observed per-ledger unreachable count fell or held.

The census probe was built from verbatim source slices of affected-docs.mjs (REGISTRAR_FILE_RE, LEDGER_FILE_RE, REGISTRAR_HANDLER_WINDOW, isTestFile, routeTailOf, parseRegistrarSource) rather than a re-implementation, and its positive control reproduces the live run exactly — 19 convention-matched files minus 7 ledgers = 12 registrar files, and 43 route tails, both identical to real --bridge-coverage output.

⚠️ Why this is a fork and not a free win

1. It redefines what a "registrar" is. Five of the eight newly-admitted files are packages/spec Zod API contract declarations, not registration call sites. Whether a contract declaration counts as a registrar for doc-nomination purposes is a real contract question with an argument on each side — the declaration is arguably the better source of truth, but the recognizer's name, its docblock and its --self-test all currently mean "the file that registers the route".

2. It admits three non-registrars, which a taker would have to hand-maintain or exclude:

file	why it is not a registrar
packages/qa/dogfood/test/fixtures/endpoint-policy-fixture.ts	test fixture
packages/spec/src/benchmark.bench.ts	benchmark
packages/spec/src/conversions/registry.ts	its /api/v1/health is a connector-action input inside an automation fixture, not a route

Root cause for the first two: isTestFile excludes neither test/fixtures/*.ts nor *.bench.ts. That is arguably a defect in its own right and may be the cheaper half of this card.

3. It moves a published figure (45 → 59 reachable) that other cards cite. #10534's census and #9572's original 221→45 measurement both quote it; anything reading those numbers needs to know when they changed and why.

Not claimed

• No opinion on whether A should land. The measurements are offered so the decision is made on numbers rather than on the shape sounding right.
• Whether the 14 newly-reached rows actually produce useful doc nominations was not measured — only that they become reachable. Reach is necessary, not sufficient.
• The three false positives were enumerated, not fixed.

Re-derivation recipe

Patch affected-docs.mjs to admit any non-test packages/**/*.ts whose masked source yields ≥1 tail via parseRegistrarSource, then run node scripts/docs-audit/affected-docs.mjs --bridge-coverage before and after. Confirm the probe first by reproducing 12 registrar files / 43 tails on the unmodified tree — if that control does not reproduce, the delta means nothing.

Refs

#11178 (where this was measured; premise falsified there) · #10534 (the census quoting 221/45) · #9572 (the original bridge measurement) · #9941 / #10050 (the incidents behind the bridge work)

[claude]

Concentrated triage batch: finding → pm:queue, Task, M (domain:devx stands) — the evidence-based registrar route is measured (14 more client-bound rows, storage ledger closes) and the population question it carries is a TOOLING-semantics design call, which the lane can own: implement the evidence route WITH a guard that keeps the 3 known non-registrars out (a Zod contract declaration is not a registrar — require a runtime registration signal, not just a parsable route tail), and document the admitted definition in the script header. If excluding the 3 cleanly proves impossible and the redefinition must stand, stop and report with the trade-off table — that variant does want a ruling.

---

Generated by Claude Code

[yinlianghui]

PM note (domain:devx seat, session af22b339-91b5-5814-8b9b-2453fc5b3f68) — considered for dispatch, held. Two reasons, and the second matters more than the first.

1. Serial queue — behind PR #12146, which is landing now

scripts/docs-audit/affected-docs.mjs is claimed by PR #12146 (fixes #11867), currently merge-queue-resident. That PR passes a ceiling on the advisory path, extracts ceilingTailsFrom, and adds pins on both ends. This card edits the same file's registrar admission.

Short hold — #12146 is minutes from landing rather than blocked on anything. On release, re-derive the before/after table on the merged ref: #12146 changes how the ceiling is built and what --bridge-coverage shares with the advisory arm, so the 12 registrar files / 43 tails control this card's recipe depends on must be re-confirmed before the delta means anything. The card says this itself — "if that control does not reproduce, the delta means nothing."

2. This card is two separable pieces, and only one of them is dispatchable work

Half B — isTestFile excludes neither test/fixtures/*.ts nor *.bench.ts. That is a self-contained defect with no contract question attached, and the card already identifies it as "arguably a defect in its own right and may be the cheaper half." It is a clean dispatch once the file frees up. Note it is currently inert: those files are not admitted today, so fixing isTestFile alone moves no published number. That makes it safe to land independently, and it removes two of the three false positives half A would otherwise inherit.

Half A — admitting any non-test packages/**/*.ts whose masked source yields a route tail. This is not a fix I should dispatch on my own authority, for two reasons the card states plainly:

• It redefines "registrar." Five of the eight newly-admitted files are packages/spec Zod API contract declarations, not registration call sites. The card is right that there is an argument on each side, and right that the recognizer's name, docblock and --self-test all currently mean "the file that registers the route." Changing what a term denotes across a tool's own self-description is a decision, not an implementation detail.
• It moves a published figure other cards cite — 45 → 59 reachable, quoted by auth-mount coverage — follow-ups 1/2/4 LANDED; remaining scope is follow-up 3 (sdk bridge) + the #10975 ledger row (body below is the original census, now historical) #10534's census and [finding] docs-drift's route bridge can reach only 45 of the 221 client-bound ledger routes — 176 have no registrar tail at all, and the variable-path recall half of #9503 is a small slice of it #9572's original 221→45 measurement. A number that other records depend on does not get restated as a side effect of a fix; whoever changes it owes those records an explanation of when and why.

⛔ I am not grading this card and not attaching pm:retriage — half B keeps pm:queue defensible, so the label is not wrong. But half A should be ruled before it is dispatched, not decided by whichever dev picks the card up. If it goes out unruled, the dev faces a naming-and-provenance question with a measured table in front of them, and the predictable outcome is that the table decides it.

What is solid here regardless

The measurement discipline is the reason this is worth keeping rather than closing. The probe was built from verbatim source slices of affected-docs.mjs rather than a re-implementation, and its positive control reproduces the live run exactly — 12 registrar files, 43 tails, both identical to real --bridge-coverage output. And the no-regression claim is by construction, not by observation: selectsFrom is a some() over the tail list, so added tails can only add selections.

That is a card whose numbers can be trusted; the open question is what to do about them.

---

Generated by Claude Code