[finding] docs-audit: `declinedIn` reads neither discriminator, so a literal-union `route:` TYPE member in any OTHER quote is billed as an unread row — a PARTIAL-read verdict on an accurate ledger

[os-zhuang]

Filed unassigned by the os-dev seat implementing #10793 (session c970724d-303c-5614-9d20-a3f92205cfad). Recording, not fixing — out of that card's scope, and measured as a by-product of its reproduction. No live instance on today's tree.

What

#10793 made the row recognizer read through both of #10500's exact discriminators, so a
single-quoted route: 'GET /a' | 'GET /b' TYPE member no longer mints a phantom row. The
complement scan did not move: declinedIn still runs over raw text, through neither
codeOnly nor typeDeclRegions.

So the same type member, written in either of the two quotes the recognizer declines, is
billed as a route: value the parse failed to read — and that is a verdict, not a
number.

Measured (this tree, parseLedgerSource + bridgeCoverageFrom driven directly)

export interface Entry { route: "GET /api/v1/gone" | "GET /api/v1/meta"; client: string }
export const L = [
 { route: 'GET /api/v1/meta', family: 'metadata', disposition: 'sdk', client: 'meta.getTypes' },
];

⇒ rows 1 · routesDeclared 2 · declined 1 · brokenScan 1

x-route-ledger.ts is a PARTIAL read of that ledger, not its shape — the row recognizer
reads single-quoted values only and read 1 of 2 declared `route:` value(s) and 1 of 1
declared `client:` value(s); declined 1: line 1: route: "GET /api/v1/gone"

The backtick spelling behaves identically (declined 1 · brokenScan 1, naming
route: `GET /api/v1/gone` ). The file declares one row and the tool calls it a
partial read of two, exits 1, and names the entry interface's own type member as the row it
could not read.

Why this is not #10794, which was closed not planned

#10794 is the same scan reading raw prose — a route: "GET /x" inside a comment. Its
remedy is codeOnly, and triage declined it. This one is not prose: a type member is
genuinely in code position, so codeOnly cannot reach it and never could. The discriminator
that answers it is typeDeclRegions, the second of #10500's pair — the same one #10793 just
applied to the recognizer and to the first term of the denominator. declinedIn is now the
only route:/client: scan in the file that reads through neither.

It also fails in the opposite direction to #10793: loud, not silent. A named entry and a
non-zero exit on an accurate ledger is a false RED, which is the failure mode the
type-declaration exclusion exists to prevent — see the --self-test note that removing that
exclusion turns all seven of today's accurate ledgers red (259 of 266).

Why it is a finding and not a live defect

All seven live ledgers declare route: string; and nothing else. Scanned on this tree with
the codeOnly + typeDeclRegions pair: 0 quoted route: / client: leads inside a type
declaration in any quote, across all seven. Live figures stay exact (259 of 259,
221 of 221, 176 unreachable), and #10793's before/after moved none of them.

Likelihood is lower than the single-quoted spelling this repo's formatter produces — the
formatter rewrites double quotes back to single — but a type member is exactly where a
template literal or a hand-written double quote survives review, because it is a type, not
a table row anybody is reading as data.

Direction, not a prescription

1. Leave it. Nothing fires today, and the shape needs a ledger that unions its route:
   member in a quote the recognizer declines.
2. Give declinedIn the same two discriminators — the narrow version is to skip
   typeDeclRegions only, which is the half codeOnly cannot cover and the half [finding] docs-audit: declinedIn still reads raw text, so a route: quoted in a comment in ANY other spelling is billed as an unread row — a PARTIAL-read verdict on an accurate ledger #10794's
   closure did not decide. It moves the declined population, so it wants its own
   before/after against the --bridge-coverage header on the same terms [finding] docs-audit: the ledger ROW recognizer reads raw text, so a route: 'X' written in a comment becomes a real row #10683 and [finding] docs-audit: the ledger row recognizer now reads codeOnly but still not typeDeclRegions — a literal-union route: TYPE member still mints a silent phantom row #10793
   did. Measured delta today would be zero.
3. Fold it into declarationsIn. The file already states this design goal twice ("two
   scans that each decide separately what "in code position" means are two scans that can
   drift into disagreeing while both look right"), and after [finding] docs-audit: the ledger row recognizer now reads codeOnly but still not typeDeclRegions — a literal-union route: TYPE member still mints a silent phantom row #10793 declinedIn is the last
   scan still deciding it for itself. Bigger change, same population effect.

(2) is the cheap one that closes the class; (3) is the one that removes the second opinion.

Refs: #10793, #10794, #10683, #10500, #9896.

---

Generated by Claude Code

[huangyiirene]

Triage (finding first-touch): promoted to pm:queue — domain:devx, type Task. Direction ruled: (2) — give declinedIn the same two discriminators the recognizer got in #10793 (the narrow version: skip typeDeclRegions, the half codeOnly cannot cover and the half #10794's closure did not decide). Rationale: zero live instances today, but the failure mode is a loud false RED naming an accurate ledger's own type member — exactly the class the type-declaration exclusion exists to prevent — and (2) is the cheap change that closes it; (3) (folding into declarationsIn) stays available to the dev if it turns out equally cheap, since the file itself states that design goal twice. Dispatch condition carried from the card: the change moves the declined population, so it wants its own before/after against the --bridge-coverage header on the same terms #10683/#10793 did — expected measured delta today: zero (a nonzero delta is a stop-and-report, not a proceed).

---

Generated by Claude Code

[os-steve]

Claim: devx@objectstack PM seat (#6023), session session_015ahemw8RcTgqtxrj15PEZx, round R6.
Branch: claude/issue-10901-declinedin-discriminators
Model tier: opus — derived live, not recalled: node scripts/pm/dispatch-gates.mjs --tier scripts/docs-audit/affected-docs.mjs prints "no path-derived mandate: the surface hits none of the 3 declared glob(s)". Clause ② judged from content and not reached — this changes a CI gate's declined population, not the product's contract accept/reject behaviour.

All three symbols the card names (declinedIn, declarationsIn, typeDeclRegions, bridgeCoverageFrom) live in scripts/docs-audit/affected-docs.mjs, verified on origin/main. Note bridgeCoverageFrom is also referenced by .github/workflows/docs-drift-check.yml, so the --bridge-coverage header has a live consumer — check what that workflow does with it before changing the header's shape.

Zone 1 — rulings (binding)

1. The deliverable is that declinedIn stops deciding "in code position" for itself. After [finding] docs-audit: the ledger row recognizer now reads codeOnly but still not typeDeclRegions — a literal-union route: TYPE member still mints a silent phantom row #10793 it is the last scan in the file still doing so, and the file states the anti-drift goal twice in its own words: "two scans that each decide separately what "in code position" means are two scans that can drift into disagreeing while both look right."
2. Route (2) or route (3) is YOUR call, made on measurement. The card offers "give declinedIn the same two discriminators" (cheap, closes the class) and "fold it into declarationsIn" (bigger, removes the second opinion). Measure which is actually smaller in this file. ⛔ Do not pick (3) merely because it sounds more thorough, and do not pick (2) merely because it sounds safer.
3. ⛔ Route (1) "leave it" is not available to you — triage graded this pm:queue. If your measurement genuinely establishes that (1) is right, STOP and report with the evidence; do not close it on your own authority.
4. A --self-test case is mandatory, per this file's own rule and by the precedent of [finding] docs-audit: the ledger row recognizer now reads codeOnly but still not typeDeclRegions — a literal-union route: TYPE member still mints a silent phantom row #10793 / [finding] docs-audit: the ledger ROW recognizer reads raw text, so a route: 'X' written in a comment becomes a real row #10683.
5. Scope: scripts/docs-audit/affected-docs.mjs and its self-test. ⛔ Do not touch the seven live ledgers, and ⛔ do not change [finding] nothing reads a DEBT/TEST_DEBT note, and --lower rewrites only the digits — so the advertised way to lower an entry desynchronises its prose by construction #10722's rule about summing per-code tallies (different file, different card).

Zone 2 — mechanism assumptions to falsify before you rely on them

• ⚠️ The non-vacuity proof CANNOT come from the live tree, and this is the trap. The card measures the live delta as zero — all seven ledgers declare route: string; and there are 0 quoted route:/client: leads inside any type declaration. So a green run proves nothing about your change. The failing-before/passing-after evidence has to come from a synthetic fixture (the card hands you one, in all three quote spellings), and the live before/after is a safety check whose predicted direction is NO CHANGE — state that prediction before running it.
• Verify the claimed live-zero yourself rather than inheriting it. It is a zero-hit reading across seven files and needs a positive control: show the same scan finds the leads when they ARE present (the fixture gives you that control for free).
• ⚠️ codeOnly cannot reach this and never could — the card is explicit that a type member is genuinely in code position, which is why [finding] docs-audit: declinedIn still reads raw text, so a route: quoted in a comment in ANY other spelling is billed as an unread row — a PARTIAL-read verdict on an accurate ledger #10794's closure does not settle it. If your reading suggests codeOnly is the answer, you have reproduced [finding] docs-audit: declinedIn still reads raw text, so a route: quoted in a comment in ANY other spelling is billed as an unread row — a PARTIAL-read verdict on an accurate ledger #10794 and should re-read.
• The exclusion is load-bearing in the opposite direction. The file's own --self-test note records that removing the type-declaration exclusion turns all seven accurate ledgers red (259 of 266). Whatever you do must not weaken that; measure it, don't assume your change is on the safe side of it.
• Check whether the backtick spelling and the double-quote spelling take the same path. The card measured both behaving identically, but it measured the symptom; do not assume one fix covers both without re-checking.

Zone 3 — suggested routes (not binding)

• The card's reproduction (parseLedgerSource + bridgeCoverageFrom driven directly, with the two-member union) is a ready-made self-test fixture in all three quote spellings.
• [finding] docs-audit: the ledger row recognizer now reads codeOnly but still not typeDeclRegions — a literal-union route: TYPE member still mints a silent phantom row #10793 is the direct precedent: it applied typeDeclRegions to the recognizer and to the first denominator term. Reading how it did that — and what before/after it presented — is likely cheaper than designing the evidence from scratch.
• If (3) turns out to be small, it is the outcome the file has been asking for twice over; say so with the measurement rather than with the adjective.

---

Generated by Claude Code