feat(devx): discover check-route-envelope's express population instead of enumerating it

[os-zhuang]

Fixes #9937

Surface 4 of scripts/check-route-envelope.mjs shipped enumerated in #9813 — one file named by hand — while surfaces 1 and 3 refuse any undeclared response-writing module. This builds the walk.

Why it needed a discriminator, and what the discriminator cost

res.json is one spelling for two opposite acts, byte-identical in receiver name:

res.json({ success: true, data })     // express WRITE, one argument
const body = await res.json();        // fetch READ, zero arguments

Triage's sizing note said the false-positive surface was unmeasured and had to be measured before sweeping. It was, on origin/main (736cfb1), and the result is what made a full sweep affordable rather than a narrower shape:

discriminator	files swept	false positives
receiver res only	20	13 pure fetch readers (65%)
argument count only	18	11 DSL files — Field.json({…}), t.json(c.name), table.json(name)
both (shipped)	7	0

301 res .json calls under packages/: 218 writes in 7 files, 83 reads in 13 others, and no file mixes the two. The 20 in row 1 reproduces the card's own "~20 res.json( files measured on main" exactly.

Both express spellings are writes, because the second is where the refusals live: res.json(body) (81 calls) and the chained res.status(400).json(body) (137). A bare-form-only walk would have counted the successes and missed the errors — this gate's recurring failure, one dialect at a time (#7295, #8884, #9267).

What landed

• discoverExpressRoutes() — parses every non-test .ts under packages/ and refuses any undeclared express writer, with failure text mirroring surface 3's. Surfaces 3 and 4 now share one discoverResponseWriters(), so the two populations cannot drift apart in whichever copy nobody edits.
• The discriminator, self-tested in both directions. The reject side is asserted positively as reads: 1, not as bodies: 0 — a scanner that had simply stopped matching the receiver produces bodies: 0 too. The audit prints the reject side as well (13 file(s) skipped as fetch readers, 83 zero-argument calls), because a walk can otherwise only ever show what it swept in.
• Excluded, not unaudited: surface 1's MODULES and SHARED_BUILDER — rest-server.ts (137 of the write calls), error-response.ts and response-envelope.ts are held there by write-site counts that see these same calls.
• IHTTP_ROUTE_MODULES → EXPRESS_RESPONSE_MODULES. The card's third open question — one population or two — is answered one, and not as a preference: the walk found a middleware and two refusal helpers, none of them route modules, and the repo types its handlers any at exactly the seam a mounting-mechanism split would need (query-allowlist.ts says so in its own signature). No references to the old name exist outside this file.

First-audit verdict for every file swept in

file	bodies	verdict
packages/runtime/src/dispatcher-plugin.ts	9	{} — already declared; unchanged
packages/runtime/src/security/inbound-rate-limit.ts	1	conformant {} — the 429 is { success: false, error: buildApiError({…}) }, the same door dispatcher-plugin.ts's conformant exits use
packages/rest/src/query-allowlist.ts	1	ratchet unenveloped: 1 (L194)
packages/rest/src/query-multiplicity.ts	1	ratchet unenveloped: 1 (L139)

The two ratchets are the finding this walk was worth building for: the shared 400 refusals rest-server.ts delegates to are ADR-0112-nested already (error: { code, message }, the reference shape security-suggested-bindings-envelope.test.ts pins the family onto) but carry no success above them, so unwrapResponse hands them to callers raw. Neither file is a route module, neither follows the *-routes.ts convention, and both were invisible to all four surfaces. They ratchet against #9559, the standing owner of packages/rest's convergence onto the shared sendOk/sendError; converting the wire answers is that line's work, not this card's.

The premise, re-derived on current main

Half of it held, half did not, and the report says which:

• Still enumerated — yes. IHTTP_ROUTE_MODULES was hand-named with no walk.
• Ratchet still at 1 — no. dispatcher-plugin.ts reads {} on main today: runtime dispatcher's SSE-fallback { events } body is off-envelope — the one non-conforming literal body left in dispatcher-plugin.ts after #9813's discovery flip #9936 landed (PR fix(runtime): implement the buffered-send streaming fallback on both dispatcher write-less-transport branches #9973) and its unenveloped: 1 was already stepped down. So the walk's population starts from one conformant declared entry, not a drifting one.

Verification

Every gate quoted by its own verdict line, exit codes captured before any pipe, all on the final commit 4594bd26.

$ pnpm check:route-envelope                → EXIT=0
✓ Express-style response modules — 4 module(s) discovered and audited (walked, not
  enumerated — #9937), 12 hand-built body/bodies (count reported, NOT pinned):
  2 conformant, 2 ratcheted, 0 exempt
  read/write discriminator: 13 file(s) skipped as fetch readers (83 zero-argument
  `res.json()` call(s), none swept in)
$ pnpm check:cross-package-test-inputs      → EXIT=0   All 60 self-test cases passed.
$ pnpm check:nul-bytes                      → EXIT=0   scanned 6090 text file(s); no raw ASCII control bytes

Surfaces 1, 2 and 3 are unmoved by the scanner change — 10 route modules, 16 dispatcher domains, 11 Hono modules / 165 bodies, identical to the baseline run on 736cfb14. That is the no-collateral evidence for touching the shared scanner.

A green self-test proves nothing until it can go red

Six mutations, each confirmed on disk before running (injected marker present, anchor text gone) and each restored byte-identically afterwards:

mutation	audit	--self-test
M1 drop the argument-count half	red — 13 fetch readers arrive as NOT DECLARED	red — a zero-argument res.json() must read as a READ
M2 drop the receiver-name half	red — the DSL files arrive as NOT DECLARED	red — a res.json write must not enter surface 3
M3 drop chained-receiver support	red — no longer writes an express-style response	red — res.status(n).json(body) must read as a WRITE
M4 break the walk (discover nothing)	red	red — the walk must re-find every declared express module
M5 un-declare inbound-rate-limit.ts	red — NOT DECLARED … EXPRESS_RESPONSE_MODULES	green (a table fact, not a scanner fact)
M6 mis-declare a count (1 → 0)	red — unenveloped: found 1, declared 0	green (same reason)

M4 is the reproduce-before-believing pin, kept permanently in the self-test: the walk must re-find every file the enumerated list named on the real tree, before it is trusted on files nobody enumerated.

Scope

skip-changeset: root scripts/ is not a publish surface and no packages/* file is touched. Clause ② does not attach — its path limb is packages/spec/src/** and nothing here is under it, and on the content limb this changes a lint gate's accept/reject behaviour, not any wire contract, Zod schema or published API. No route behaviour changed; not one byte of product code is in this diff.

---

Generated by Claude Code