[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

Filed unassigned by the os-dev seat implementing #10683. Recording, not fixing — deliberately left out of that card's scope because it fails in the opposite direction and therefore wants its own before/after. No live instance on today's tree.

What

#10683 fixed the row recognizer's lens. Its complement, declinedIn, is still called on raw bytes at both of its call sites in parseLedgerSource:

for (const d of declinedIn(text.slice(m.index, m.index + window.length))) { … }   // in-window `client:`
for (const d of declinedIn(text)) { … }                                          // file-wide `route:`

That is not an oversight in #10683 — a masked window would name client: "" for every entry, because codeOnly blanks string contents and declinedIn's whole job is to quote the unread spelling back at the reader. But it means a route:/client: written in a comment or string payload in a spelling the recognizer declines (double quote, backtick) is still read as a declaration.

Measured (this branch, parseLedgerSource driven directly)

// The retired row read route: "GET /api/v1/gone" before #1234.
export const L = [
  { route: 'GET /api/v1/meta', family: 'metadata', disposition: 'sdk', client: 'meta.getTypes' },
];

⇒ rows 1 · routesDeclared 2 · declined [{ key: 'route', line: 1, text: 'route: "GET /api/v1/gone"' }]

routesDeclared (2) now exceeds rowsParsed (1), so bridgeCoverageFrom raises a PARTIAL read verdict and --bridge-coverage exits 1 — on a ledger that is completely accurate. The prose sentence is billed as a row the recognizer could not read.

Why this is the opposite failure direction, and why that matters for triage

#10683 was a false green: a phantom row entered the population silently and joined the UNREACHABLE count with no verdict. This one is a false red: the entry is NAMED, with its line, and carries a verdict. Loud and self-announcing, so it costs a reader an afternoon rather than corrupting a number other cards act on — which is why it is a separate card and not a rider. It is still the same asymmetry the #10683 card names ("every other scan in that file reads code-only and this one reads prose"), one scan over.

Why it is a finding and not a live defect

All seven live ledgers are wholly single-quoted (259 of 259, 221 of 221, declined 0), and no ledger comment quotes a route:/client: in any spelling — outsideCode (#10683's new report) measures 0 across all seven, and declined is 0 across all seven.

Direction, not a prescription

1. Leave it. It is loud, and the trigger needs a comment quoting a route in a non-recognizer spelling.
2. Filter by code position. parseLedgerSource already computes code; a declaration is in code position iff its key spelling survives there (code.startsWith(d.key, abs)), so declinedIn's results can be filtered without masking the text it quotes. One predicate, both call sites, snippets stay readable. ⚠️ Moves the measured declined population — needs its own before/after against the --bridge-coverage header.
3. Fold declinedIn into declarationsIn. It is already the missing third filter over that one scan (unreadableIn is quote === null, unclaimedClientsIn is the claimed-client: complement, this would be quote === '"' || quote === ' + "''" + '). The file states this design goal twice. ⚠️ Not a drop-in: declinedInaccepts\s*before the quote wheredeclarationsInaccepts[ \t]*, so some declarations would change bucket, and declarationsInrecomputescodeOnly` — which is wrong for the in-window call, since masking an arbitrary substring can mis-lex.

Refs: #10683, #10500, #10636, #9896.

Generated by Claude Code