fix(docs-audit): give declinedIn the type-declaration discriminator (#10901) (#11500)

`declinedIn` was the last `route:`/`client:` scan in `affected-docs.mjs` still
deciding "is this in code position?" for itself. #10793 taught the row recognizer
and the first term of its denominator to read through both of #10500's exact
discriminators; its complement did not move, so a literal-union `route:` TYPE
member written in either of the two quotes the recognizer declines was billed as
a value the parse FAILED to read — a named entry, a PARTIAL-read verdict and
exit 1, on a ledger that is completely accurate.

The region list now arrives as a required parameter from the one caller that
already computes it, with no default: a call site that forgot the discriminator
would silently reintroduce exactly the second opinion this closes. `offset`
makes the returned index absolute, so the in-window slice's coordinate
translation happens once inside the function instead of at one of the two call
sites.

Both call sites were reachable and both are covered: a leading entry interface
arrives through the file-wide `route:` sweep, a trailing one lands inside a row
window and reached the in-window `client:` sweep (measured before the fix:
`clientsDeclared` 2 on a file declaring one client, exit 1).

⛔ The other discriminator is deliberately NOT applied. This still reads raw
bytes, so a declined spelling quoted in a COMMENT is still billed as an unread
row — that is #10794, closed `not planned`, and not this change's to reverse.
The boundary is pinned in `--self-test` so whichever card eventually takes on #10794
moves the pin rather than finding none.

Self-test: 339 -> 366 cases. 15 of the new cases fail against the previous
`declinedIn` and pass after. Live delta is zero and predicted so in advance:
0 quoted `route:`/`client:` leads inside any type declaration across all seven
ledgers, and `--bridge-coverage` is byte-identical before and after
(268 of 268 route / 222 of 222 client / 177 unreachable, exit 0).


Claude-Session: https://claude.ai/code/session_015ahemw8RcTgqtxrj15PEZx

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

scripts/docs-audit/affected-docs.mjs

@@ -1422,12 +1422,51 @@ function unclaimedClientsIn(text, claimed) {
  * A FUNCTION DECLARATION rather than a `const` arrow, deliberately: `--self-test`
  * short-circuits near the top of this file, before any `const` down here has initialized,
  * and a TDZ error there takes the whole self-test down instead of failing one check.
+ *
+ * IT NO LONGER DECIDES "IS THIS A TYPE MEMBER?" FOR ITSELF (#10901). It used to run over
+ * raw text through NEITHER of #10500's discriminators while the recognizer read through
+ * both, so a literal-union `route: "GET /a" | "GET /b"` TYPE member — the identical shape
+ * #10793 kept out of `rows`, written in either of the two quotes this scan reads — was
+ * billed as a value the parse FAILED to read. That is a verdict, not a number: the entry
+ * is NAMED with its line and `bridgeCoverageFrom` raises a PARTIAL read with exit 1, on a
+ * ledger that is completely accurate. Measured on the tree this landed on, one file
+ * declaring ONE row:
+ *
+ *     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   (backtick: identical)
+ *
+ * So the region list arrives as a PARAMETER, from the one caller that already computes it,
+ * and there is no default: a call site that forgot the discriminator would silently
+ * reintroduce exactly the second opinion this closes, and the file argues twice that two
+ * scans each deciding "in code position" separately are two scans that can drift into
+ * disagreeing while both look right. `offset` is the absolute position of `s` in the file,
+ * so the translation between the in-window slice's coordinates and the region list's
+ * happens HERE, once, instead of at one of the two call sites — the returned `index` is
+ * absolute for both.
+ *
+ * ⛔ THE OTHER DISCRIMINATOR IS DELIBERATELY NOT APPLIED HERE. This still reads RAW bytes,
+ * so a `route: "GET /x"` written in a COMMENT is still billed as a declined row. That is
+ * #10794, closed `not planned` on the reasoning that it is the LOUD direction and has no
+ * puller — and it is not this card's to reverse. It is also not a free change of lens:
+ * `codeOnly` blanks string CONTENTS, and this scan's whole job is to quote the unread
+ * spelling back at the reader, so a masked window would name `route: ""` for every entry.
+ * `--self-test` pins that boundary in place, and a future card closing #10794 is expected
+ * to move that pin rather than to find it missing.
  */
-function declinedIn(s) {
-  return [...s.matchAll(/(route|client)\s*:\s*(["`])([^\n]{0,120})/g)].map((d) => {
+function declinedIn(s, offset, inTypeDecl) {
+  const out = [];
+  for (const d of s.matchAll(/(route|client)\s*:\s*(["`])([^\n]{0,120})/g)) {
+    const index = offset + d.index;
+    // …and never a TYPE member (#10901), on the SAME region list the recognizer and the
+    // denominator read — not a second idea of what a type member is.
+    if (inTypeDecl(index)) continue;
     const end = d[3].indexOf(d[2]);
-    return { index: d.index, key: d[1], text: `${d[1]}: ${d[2]}${end === -1 ? d[3].slice(0, 60) : d[3].slice(0, end)}${d[2]}` };
-  });
+    out.push({ index, key: d[1], text: `${d[1]}: ${d[2]}${end === -1 ? d[3].slice(0, 60) : d[3].slice(0, end)}${d[2]}` });
+  }
+  return out;
 }
 
 /**
@@ -1580,20 +1619,27 @@ function parseLedgerSource(text) {
     // …over the RAW bytes of that same window. `declinedIn`'s whole job is to NAME an
     // unread spelling, and the masked window would name `client: ""` for every one of them.
     // The BYTE RANGE is the code-derived window's, so this is the same span, read for its
-    // text. ⛔ That leaves `declinedIn` itself still reading prose — a `route: "GET /x"`
-    // written in a comment is still billed as a declined row. It is the SAME asymmetry one
-    // scan over, but it fails in the opposite direction (a declined entry is NAMED and
-    // carries a verdict, so it is a false RED, not a phantom row), which makes it a
-    // separate call with its own before/after rather than a rider here. Filed as #10794.
-    for (const d of declinedIn(text.slice(m.index, m.index + window.length))) {
+    // text — but it now reads that span through the TYPE-DECLARATION discriminator (#10901),
+    // on the same `typeDecls` list the loop above and the denominator below read. An entry
+    // interface trailing the table lands INSIDE this window (measured: `client: "a" | "b"`
+    // on the line after the table's `];` was billed as a declined client, `clientsDeclared`
+    // 2 on a file declaring 1, exit 1), and a type member is not a row this parse failed to
+    // read — it is a correct declaration of a TYPE.
+    //
+    // ⛔ Still RAW, and still through no `codeOnly`: a `route: "GET /x"` written in a
+    // COMMENT is still billed as a declined row. That is #10794, closed `not planned`
+    // (loud direction, no puller), and this card does not reverse it — see `declinedIn`.
+    for (const d of declinedIn(text.slice(m.index, m.index + window.length), m.index, inTypeDecl)) {
       if (d.key !== 'client') continue;
-      claimed.add(m.index + d.index);
-      declined.push({ key: 'client', line: lineAt(m.index + d.index), text: d.text });
+      claimed.add(d.index);
+      declined.push({ key: 'client', line: lineAt(d.index), text: d.text });
     }
   }
   // `route:` is counted file-wide, because a declined row has no window to be found in —
-  // which is precisely why it was invisible.
-  for (const d of declinedIn(text)) {
+  // which is precisely why it was invisible. Type members are skipped here on the same list
+  // (#10901): a leading entry interface sits in no row window at all, so this is the call
+  // site the card's own fixture arrives through.
+  for (const d of declinedIn(text, 0, inTypeDecl)) {
     if (d.key === 'route') declined.push({ key: 'route', line: lineAt(d.index), text: d.text });
   }
   // …and the values no quote-keyed scan can see at all (#10500). File-wide for the same
@@ -2419,6 +2465,130 @@ function selfTest() {
   check('bridgeCoverageFrom', 'and it is not billed as a prose lead either', 'leadsOutsideCode',
     0, typeUnionCov.leadsOutsideCode);
 
+  // ---- THE SAME TYPE MEMBER, IN THE TWO QUOTES THE RECOGNIZER DECLINES (#10901) ----
+  // #10793 (above) taught the ROW RECOGNIZER and the first term of its denominator to read
+  // through both of #10500's discriminators. Its complement did not move: `declinedIn` ran
+  // over RAW text through NEITHER, so the very same member — a `route:` union written in a
+  // double quote or a backtick instead of a single one — was billed as a value the parse
+  // FAILED to read. That is the LOUD twin of the bug above: not a phantom row joining the
+  // population in silence, but a named entry and a PARTIAL-read verdict with exit 1, on a
+  // ledger that is completely accurate. The type-declaration exclusion exists to prevent
+  // exactly that false red, and this is the last scan in the file that was not reading it.
+  //
+  // BOTH SPELLINGS ARE PINNED SEPARATELY. They come out of one regex alternation and one
+  // code path, and were measured behaving identically — which is the reason to pin them
+  // apart rather than to trust one for both: a later narrowing of that alternation would
+  // otherwise take one of them with nothing to say so.
+  for (const [spelling, q] of [['double-quoted', '"'], ['backtick-quoted', '`']]) {
+    const src = [
+      `export interface Entry { route: ${q}GET /api/v1/gone${q} | ${q}GET /api/v1/meta${q}; client: string }`,
+      'export const L = [',
+      "  { route: 'GET /api/v1/meta', family: 'metadata', disposition: 'sdk', client: 'meta.getTypes' },",
+      '];',
+    ].join('\n');
+    const r = parseLedgerSource(src);
+    const cov = bridgeCoverageFrom([{ file: 'j-route-ledger.ts', ...r }], ['/api/v1/meta']);
+    check('parseLedgerSource', `a ${spelling} literal-union \`route:\` TYPE member is not an unread row`,
+      'declined', 0, r.declined.length);
+    check('parseLedgerSource', `and a ${spelling} member moves no denominator either`, 'declared',
+      '1 row / 1 route / 1 client',
+      `${r.rows.length} row / ${r.routesDeclared} route / ${r.clientsDeclared} client`);
+    check('parseLedgerSource', `and the row in CODE still reads, beside a ${spelling} member`, 'row',
+      'GET /api/v1/meta → meta.getTypes', `${r.rows[0]?.route} → ${r.rows[0]?.client}`);
+    // The verdict is the whole point: the number moving is a symptom, the exit code is the
+    // defect. An accurate ledger must carry NO broken-scan verdict in any spelling.
+    check('bridgeCoverageFrom', `a ${spelling} type member carries NO broken-scan verdict`, 'brokenScan',
+      0, cov.brokenScan.length);
+    // ⚠️ PINNED IN BOTH DIRECTIONS, like #10793's fixture: an exclusion that reached the
+    // member by swallowing the table after it would pass every assertion above while
+    // silently dropping every live row. Deleting the interface must change NOTHING.
+    const noInterface = parseLedgerSource(src.split('\n').slice(1).join('\n'));
+    check('parseLedgerSource', `and deleting a ${spelling} member's interface changes NOTHING`, 'declared',
+      `${r.rows.length} row / ${r.routesDeclared} route / ${r.declined.length} declined`,
+      `${noInterface.rows.length} row / ${noInterface.routesDeclared} route / ${noInterface.declined.length} declined`);
+  }
+
+  // THE OTHER CALL SITE, and the one no `route:` fixture can reach: declined `client:`
+  // values are collected per ROW WINDOW, so a member only arrives there when the entry
+  // interface TRAILS the table and lands inside the 1200-byte window. Measured before the
+  // fix on exactly this shape: `clientsDeclared` 2 on a file declaring one client, one
+  // named declined entry, exit 1. The `route:` twin below trails the table too, which is
+  // the file-wide call site reached from the other side.
+  for (const [spelling, q] of [['double-quoted', '"'], ['backtick-quoted', '`']]) {
+    const trailingClient = parseLedgerSource([
+      'export const L = [',
+      "  { route: 'GET /api/v1/meta', family: 'metadata', disposition: 'sdk', client: 'meta.getTypes' },",
+      '];',
+      `export interface Entry { route: string; client: ${q}meta.getTypes${q} | ${q}meta.getAudit${q} }`,
+    ].join('\n'));
+    check('parseLedgerSource', `a ${spelling} literal-union \`client:\` TYPE member inside the row window is not an unread row`,
+      'declined', 0, trailingClient.declined.length);
+    check('parseLedgerSource', `and a ${spelling} \`client:\` member moves no denominator`, 'declared',
+      '1 route / 1 client', `${trailingClient.routesDeclared} route / ${trailingClient.clientsDeclared} client`);
+    const trailingRoute = parseLedgerSource([
+      'export const L = [',
+      "  { route: 'GET /api/v1/meta', family: 'metadata', disposition: 'sdk', client: 'meta.getTypes' },",
+      '];',
+      `export interface Entry { route: ${q}GET /api/v1/meta${q} | ${q}GET /api/v1/gone${q}; client: string }`,
+    ].join('\n'));
+    check('parseLedgerSource', `a TRAILING ${spelling} \`route:\` member is not an unread row either`,
+      'declared', '1 route / 0 declined',
+      `${trailingRoute.routesDeclared} route / ${trailingRoute.declined.length} declined`);
+  }
+
+  // `type X = { … }` is the other spelling `typeDeclRegions` recognises, and this scan now
+  // reads the same region list rather than a second idea of what a type member is.
+  const declinedTypeAlias = parseLedgerSource([
+    'export type 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' },",
+    '];',
+  ].join('\n'));
+  check('parseLedgerSource', 'a `type X = { … }` member is skipped in the declined spellings too',
+    'declared', '1 row / 1 route / 0 declined',
+    `${declinedTypeAlias.rows.length} row / ${declinedTypeAlias.routesDeclared} route / ${declinedTypeAlias.declined.length} declined`);
+
+  // ⚠️ THE LOAD-BEARING DIRECTION, asserted positively. Everything above says a spelling
+  // STOPS being reported; an exclusion that swallowed the declined report wholesale would
+  // pass every one of those and give back the silence #9896 closed. A real table row whose
+  // `route:` is spelled in a quote the recognizer declines is NOT a type member, and must
+  // still be named, still move the denominator, and still carry the verdict.
+  for (const [spelling, q] of [['double-quoted', '"'], ['backtick-quoted', '`']]) {
+    const realRow = parseLedgerSource([
+      'export interface Entry { route: string; client: string }',
+      'export const L = [',
+      `  { route: ${q}GET /api/v1/gone${q}, family: 'metadata', disposition: 'sdk' },`,
+      "  { route: 'GET /api/v1/meta', family: 'metadata', disposition: 'sdk', client: 'meta.getTypes' },",
+      '];',
+    ].join('\n'));
+    const realCov = bridgeCoverageFrom([{ file: 'k-route-ledger.ts', ...realRow }], ['/api/v1/meta']);
+    check('parseLedgerSource', `a ${spelling} route in a REAL table row is still declined`, 'declined',
+      1, realRow.declined.length);
+    check('parseLedgerSource', `and the ${spelling} entry still NAMES itself, with its line`, 'line 3',
+      `3: route: ${q}GET /api/v1/gone${q}`,
+      realRow.declined.map((d) => `${d.line}: ${d.text}`).join(' | '));
+    check('parseLedgerSource', `and the partition still holds for the ${spelling} row — read + declined === declared`, 'partition',
+      realRow.routesDeclared, realRow.rows.length + realRow.declined.filter((d) => d.key === 'route').length);
+    check('bridgeCoverageFrom', `and the PARTIAL-read verdict still fires for a ${spelling} real row`, 'brokenScan',
+      true, realCov.brokenScan.some((v) => v.includes('PARTIAL read')));
+  }
+
+  // ⛔ THE BOUNDARY THIS CARD DELIBERATELY DID NOT CROSS. `declinedIn` still reads RAW
+  // bytes, so a `route:` quoted in a COMMENT in a declined spelling is still billed as an
+  // unread row — #10794, closed `not planned` because it is the loud direction with no
+  // puller. Pinned so the boundary is a recorded decision rather than an oversight, and so
+  // the card that eventually closes #10794 MOVES this pin instead of finding none.
+  const proseDeclined = parseLedgerSource([
+    '// 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' },",
+    '];',
+  ].join('\n'));
+  check('parseLedgerSource', 'a declined spelling in PROSE is still billed as unread — #10794, deliberately unmoved',
+    'declined', 1, proseDeclined.declined.length);
+  check('parseLedgerSource', 'and its denominator still counts it — the type-member fix moved this none',
+    'declared', '1 row / 2 route', `${proseDeclined.rows.length} row / ${proseDeclined.routesDeclared} route`);
+
   // ⛔ REPORTED, NEVER A VERDICT. A comment explaining a retired row by quoting its old path
   // is legitimate prose; reddening CI over it is the false red the #9747 family declines.
   const phantomCov = bridgeCoverageFrom([{ file: 'h-route-ledger.ts', ...phantom }], ['/api/v1/meta']);