[finding] docs-audit: the ledger ROW recognizer reads raw text, so a `route: 'X'` written in a comment becomes a real row

[os-zhuang]

Filed unassigned by the os-dev seat implementing #10636 (session session_01DdCnBGcHeufjrq7drTD3wt). 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

parseLedgerSource assembles rows with routeRe = /route\s*:\s*'([^']+)'/g over raw text, and the first term of routesDeclared is [...text.matchAll(/route\s*:\s*'/g)] — also raw. #10500 built codeOnly (comments and string CONTENTS blanked) and typeDeclRegions, and the reporting scans read the source through them, but the row recognizer and that first denominator term never did.

So a route: followed by a single-quoted literal inside a comment or a string payload is not merely mis-counted: it becomes a row.

Measured (19c982a268, via parseLedgerSource directly)

// A row we removed used to read route: 'GET /api/v1/gone' before #1234.
export const L = [
 { route: 'GET /api/v1/meta', family: 'metadata', disposition: 'sdk', client: 'meta.getTypes' },
];

⇒ rows 2 · routesDeclared 2 · clientsDeclared 1 · declined []

Two rows out of a file declaring one. routesDeclared agrees with rows, so no verdict fires — the partial-read guard is keyed on the gap between them and there is no gap. The phantom row carries no client here, so it lands in rowsParsed only; a prose line that also quotes a client: would mint a fully client-bound phantom, which then joins the UNREACHABLE population (no registrar tail can match a route nobody mounts) and inflates the 176 quietly.

Why it is a finding and not a live defect

No ledger comment on today's tree quotes a single-quoted route: — scanned all seven, zero hits, and the live figures (259 of 259, 221 of 221) are exact. The English sentence in runtime/src/route-ledger.ts ("It never named a mounted route: the branch") is the near miss: no quote follows, so it produces nothing. It is one formatter-friendly comment away — e.g. a note explaining a retired row by quoting its old path.

Direction, not a prescription

1. Leave it. Nothing fires today, and the shape needs a comment that quotes a route in the exact row spelling.
2. Read rows through codeOnly too. The mask already exists and preserves offsets, so routeRe and the raw matchAll could both run over the blanked source with no other change. ⚠️ This MOVES the measured population (the standard the --bridge-coverage header attaches to that), and it is the row recognizer — the narrow, deliberately-unwidened thing — so it wants its own before/after.
3. Report rather than change the population: a route: lead that the mask says is not in code position is itself the interesting event, and naming it keeps the recognizer byte-identical. Same argument docs-audit: a PARTIAL ledger parse is silent — one backtick-quoted route: drops a row from the bridge population with no verdict and exit 0 #9896 made for keying on the spelling that was not read.

(2) is the one that removes the class; (3) is the one that cannot regress the population. The asymmetry is worth closing either way — every other scan in the file reads code-only, and this one reads prose.

Refs: #10636, #10500, #9896, #9432 (the same shape one scan over, in parseRegistrarSource).

---

Generated by Claude Code

[os-zhuang]

Triage (finding concentration round): promoted to pm:queue · type Task. The row recognizer is the one scan in the file still reading prose while every other scan reads code-only — restoring that consistency removes a phantom-row class that would silently inflate audit populations other cards act on. Dispatch note: prefer direction (3) (report non-code-position route: leads, recognizer byte-identical) unless the dev measures (2)'s population move with its own before/after, per the card's own warning. S–M, mode:subagent; Clause-②: no.

---

Generated by Claude Code