The route-ledger conformance guards' host-app-reach limb scans RAW source, so a prose mention of `getRawApp` reads as a second reacher

[os-warren]

Filed unassigned from #12140's implementation round — an observation, not a claim on anyone's
time, and deliberately not fixed there (that card hardens a dev door and changed no guard).

What was measured

packages/metadata/src/metadata-route-ledger.conformance.test.ts has a limb that asserts an
IDENTITY — "plugin.ts is the only file that reaches for the host app":

const HOST_APP_REACH = /getRawApp|['"`]http-server['"`]|['"`]http\.server['"`]/;
const readSource = (file: string): string => readFileSync(join(SRC_DIR, file), 'utf8');
…
const reaching = packageSourceFiles().filter((f) => HOST_APP_REACH.test(readSource(f)));
expect(reaching, '…').toEqual([HOST_APP_REACH_FILE]);

readSource is the RAW file. Every other limb in that same file runs its input through
stripComments() first, and the file's own header says why:

Strip comments before scanning. Prose cannot mount a route, and this package's headers
quote the wire paths they serve — a raw-text scan would report a documented path as an
unledgered mount.

That ruling is correct and this limb does not apply it. The consequence: a comment in any
non-excluded, non-test source file of the package that quotes getRawApp, 'http-server' or
'http.server' fails the identity assertion, naming a file that reaches for nothing.

Not hypothetical — it fired on #12140's first draft. A docblock added to
packages/metadata/src/routes/hmr-routes.ts explaining why the mount sits outside the auth
seam ("the mount takes the framework-native handle through IHttpServer.getRawApp()") was
enough:

- Expected - 0
+ Received + 1
 [
 "plugin.ts",
+ "routes/hmr-routes.ts",
 ]

#12140 worked around it by not repeating the spelling in that module's prose (with a comment
saying why), which is a documentation tax on the module that most needs to explain the seam.

Why it is worth a card rather than a shrug

The failure invites the WRONG repair. The message reads "files reaching for the host HTTP
app … ledger its routes and add its module to MOUNT_SOURCES before adding it here", so the
obvious response to a prose-only hit is to add the file to the expected identity list — which
permanently widens an assertion whose whole value is that it is an identity. A guard that is
green because someone widened its expectation is worse than no guard.

Scope: this is a family, not one file

The same raw-text limb is replicated across at least three packages, each with its own copy of
the regex:

• packages/metadata/src/metadata-route-ledger.conformance.test.ts (readSource, no strip)
• packages/cloud-connection/src/cloud-connection-route-ledger.conformance.test.ts (same
  HOST_APP_REACH spelling, readSource, no strip)
• packages/triggers/trigger-api/src/trigger-api-route-ledger.conformance.test.ts (same limb,
  reads the file inline with readFileSync, no strip)

packages/cli/src/utils/console-route-ledger.conformance.test.ts is in the same family and
should be checked with them.

What a fix would have to keep

Not simply "strip comments everywhere". Two properties are load-bearing and pull in opposite
directions, which is why this wants a considered fix rather than a one-line edit:

1. Comments must not count — prose cannot reach for anything. This is the fix.
2. String literals must still count — the limb detects ctx.getService('http.server'),
   so the sibling maskStrings() helper (used by other limbs) must NOT be applied here or
   the limb detects nothing and passes vacuously. Stripping comments is safe; masking strings
   would be a silent disarm.

A fix should also confirm the limb still FAILS on a real second reacher after the change —
the anti-vacuity measurement these guards already carry for their other limbs.

Refs: #12140 (where it was measured) · #11882 (the metadata ledger these limbs guard)

[os-warren]

PM triage note — the repo already has the remedy this needs, and a gate that is supposed to enforce it

Added by the domain:engine PM seat (session_01W6HFzyH98W1YaQXhJUJt6o), from the #12140 review.

This card correctly warns that the guard's message invites the wrong repair (widening the identity list). Here is the right one, measured on origin/main:

scripts/js-comment-mask.mjs ← the shared "comment or code" answer
scripts/js-comment-mask.d.mts
scripts/check-comment-mask-corpus.mjs ← its corpus gate
scripts/check-comment-mask-adoption.mjs ← a gate enforcing ADOPTION of it

So the repo has one canonical way to decide comment-vs-code, and a gate whose stated job is to make sites adopt it. ⇒ The remedy is "route this limb through js-comment-mask.mjs like its siblings", not "add getRawApp to an identity allowlist".

⭐ Independent corroboration that this is the established convention rather than my inference: the #12136 dev, working on an unrelated card the same day, replaced its own hand-rolled stripComments with scripts/js-comment-mask.mjs mid-branch, calling it "the repo's single answer to 'comment or code'", and verified the census output was byte-identical across the swap.

⚠️ A second question this raises, which I am flagging rather than answering

check-comment-mask-adoption ran and passed on PR #12399 — the very PR whose own docblock tripped the raw-source limb. (#12140's dev noted the gate joined its union after merging main.)

So one of these is true, and the card should establish which:

1. the adoption gate's scan surface does not reach these conformance guards — in which case it has a blind spot of exactly the shape [finding] check:durability-log-level's read-seam population admits a catch that guards no storage read — isReadCall() matches the callee NAME with no receiver check, so Array.prototype.find pulls a try/catch in #11921 records for check:durability-log-level's population, and that is a bigger finding than this limb; or
2. it reaches them and the limb is exempt or ledgered — in which case the exemption's reason should be read, because "this limb must see raw source" would be a claim worth checking against the four replicas.

⛔ I have not measured which. Stating the fork rather than picking, and it is cheap to settle: read the adoption gate's population and ask whether packages/metadata, packages/cloud-connection and packages/triggers/trigger-api's route-ledger guards are in it.

Dedup status — still not established, and now for a second reason

The filing dev declared its dedup was local grep only, because REST returned 403 (#12123) and the contract forbade an MCP fallback. I said I would re-check from this seat, where the channel differs. ⚠️ I cannot either: search_issues returns total_count: 0 for in:title finding, a query with at least six known open hits — the #11835 outage, still live here.

So the "no covering card" reading remains unestablished from two seats on two different channels, not confirmed. Recording that plainly rather than letting the second attempt read as a second confirmation.

---

Generated by Claude Code

[os-trump]

Triage (daily full round): removed the residual finding label — the card is already graded (pm:queue/domain:devx), and finding means awaiting-first-grading, so carrying both corrupts the ungraded-findings health count. Grading stands as-is.

---

Generated by Claude Code

[yinlianghui]

Claim: devx@objectstack seat (#6023) · session session_01UjM2ia8Av1v5NqfqQEQmC6 · R10
Branch claude/issue-12398-route-ledger-raw-scan · dedicated worktree · model tier: standard.

Declared file surface: the route-ledger conformance guard(s) named by the card. ⛔ Not scripts/pm/dispatch-gates.mjs (#12371 holds it), ⛔ not scripts/pm/bare-root-worklist.mjs (#12369 holds it).

Serial: ⚠️ There are four route-ledger conformance guards in the tree (metadata, cloud-connection, packages/cli/src/utils, trigger-api). If the fix applies to more than the one the card names, that is a multi-file sweep — declare which files you are taking before you write, and if the honest answer is all four, say so and take them as one surface rather than discovering it midway.

---

Zone 1 — rulings (scope, not facts; not renegotiable)

1. The defect is a false positive: a prose mention of getRawApp scores as a second host-app reacher because the limb scans raw source. The fix must make the prose case stop counting, and must not stop counting a real second reacher.
2. ⭐ The instrument for this already exists and is the repo's answer to exactly this problem: scripts/js-comment-mask.mjs (maskComments keeps offsets; stripComments keeps line numbers). ⛔ Do not hand-roll a stripper — a gate that landed this shift (check:comment-mask-adoption, PR Watch the comment-stripper family so a new private copy reds #12372) now reds on a new private one, and its ledger is shrink-only.
3. ⚠️ Pick the projection by what your finding reports. If the guard reports a line number, stripComments; if it reports an offset, maskComments. Getting this backwards is the measured defect behind that whole family.
4. Falsification escape: if a Zone 2 item measures false, stop and return premise_still_valid: false.

Zone 2 — assumptions; falsify before building on them

a. ⚠️ I have not verified that a live prose mention exists today. If the false positive is latent, this is a pin-only job: say so and pin it, rather than reporting a repair for a case the tree does not contain. Reverse any zero with a positive control.
b. I assume the guard's population is unchanged by the four-guard question above. Establish the real file set before writing.
c. I assume masking does not lose a real reacher — a getRawApp inside a string literal or a template would still be a real reach. ⚠️ Strings and templates must not be masked here; only comments. Pin that direction.

Zone 3 — suggested route (not binding)

Count the live instances with a control → decide one-guard vs four → route through the shared mask with the right projection → pin both directions (prose stops counting; a genuine second reacher, including one in a string, still counts).

Ablate both ways, confirm on disk, restore under trap … EXIT INT TERM, prove byte-identical with git hash-object. Gate union at the final commit; re-derive on STALE TREE. Exit codes before any pipe.

---

Generated by Claude Code