dispatch-gates: declare check:route-envelope's wide population, admit exact-file hints

[os-trump]

Fixes #16828

Which side the fix belongs to, and the reading that decided it

The gate, via the wide-population channel — not a ROOT_DIR_WATCH_HINTS subtree literal, and not the deriver's placement logic.

check:route-envelope's real population (discover() + discoverResponseWriters()) is an AST-content filter over every non-test .ts file under packages/ — does it write a Hono/Express JSON response? — not a filename convention, so no glob spells it short of the whole subtree. scripts/pm/bare-root-worklist.mjs's own CENSUS_REFUSE_WIDE ledger had already measured and recorded this exact verdict: check:route-envelope packages, REFUSE-WIDE, 2181/5837 tracked packages/ files opened (37.4%, base 2aa8456cf) — the same width trade as check:authz-resolver (39%). Re-measured fresh on HEAD: 2403/6491 non-test .ts files under packages/ (37.0%), corroborating it. The ledger recorded the verdict; the gate's own source never acted on it.

A wrinkle the ledger didn't anticipate, found by trying it: widePopulationRefusal refused ANY named hint, and check:route-envelope has 30 (the MODULES table's own keys) that must stay — deleting them to fit the marker would turn a precise matched lead on every already-known route module into an undifferentiated wide-population one, a real precision loss. All 10 gates that carry the marker today have zero hints, so this case was untested. placeFamily's own runtime logic already does the right thing with hints + a wide-population marker (matched stays matched; everything else is promoted out of Silent) — only the validation-only widePopulationRefusal was stricter than the mechanism it guards. Refined it (see Files below).

Files

• scripts/check-route-envelope.mjs — one dispatch-gates: wide-population -- marker, citing the measured population fraction and the ledger row.
• scripts/pm/dispatch-gates.mjs — widePopulationRefusal refined via a new widePopulationHintCompatible helper: an exact-file hint (matched only by equality) never contradicts the marker; a hint that reaches beyond itself (a directory, or a glob) is compatible only when the marker's own reason text names it (check:route-envelope's one such hint, DISPATCHER_DOMAIN_DIR, is a second, independently-audited surface named in the reason for exactly that reason); a glob is never exempt this way, named or not. New self-test coverage for every branch. No change to placeFamily's existing runtime behaviour and no change to check:route-envelope's own audited behaviour — same files error, same files pass.

Positive control (#16730 situation) — predicted before running, then measured

Predicted: a brand-new response-writing module outside MODULES shows Silent in --residue before the fix, Declared WIDE population after — and an existing declared module stays matched either way (no precision lost).

Measured, node scripts/pm/dispatch-gates.mjs --residue packages/plugins/plugin-auth/src/some-brand-new-notification-endpoint.ts (a synthetic new file, not the original list-user-invitations-verification.ts, which is now itself an already-declared MODULES member and no longer reproduces the bug):

• Before (original file, restored via a git-blob-hash-verified swap/restore, not git stash): Declared WIDE population — 10 famil(ies); Silent (…): 188 famil(ies), and check:route-envelope prints under Silent, byte-identical to the card's own quoted symptom (names: packages/services/service-storage/src/storage-routes.ts, …).
• After (this diff): Declared WIDE population — 11 famil(ies); Silent (…): 187 famil(ies), and check:route-envelope prints under Declared WIDE population with the full reason text.
• Regression check: --residue packages/services/service-storage/src/storage-routes.ts (an existing MODULES member) still prints check:route-envelope … matched via … ⇢ gate source 'packages/services/service-storage/src/storage-routes.ts' after the fix — the precise lead on known modules is unchanged.

Restore verified by git hash-object equality (761a3b0e5… before mutation = after restore) and an empty git diff against the pre-mutation working tree.

The sweep (mandatory per the card)

Two instances individually confirmed (not merely heuristic):

1. check:route-envelope — fixed here.
2. The check:generated family, which wraps check:migration-registry internally — re-verified independently (not just trusted from the card/PRs feat(service-analytics)!: refuse an aggregate a datetime measure's field type cannot carry, and reconcile the storage-form annotations to one measured statement #16778, fix(deps): take the fix for the fifteen OSV advisories blocking every PR #17029): check:generated's own dispatch-gates hints (10) name neither packages/spec/src/migrations/registry.ts nor any entries/ path; placeFamily places both a direct edit to registry.ts and a new entries/ file silent. Root cause read from source: check-generated.ts's GATED array spells that entry's artifact field as prose ('src/migrations/registry.ts — its generated regions, from src/migrations/entries/'), which fails extractWatchHints's path-shaped admission regex outright — a formatting gap, not a width one, and precisely spellable (no wide-population marker needed). Filed as dispatch-gates: check:generated's hints never name the migration-registry artifact it wraps, so the family reads Silent on the diffs that regenerate it #17049 — different file, different package's gate pipeline, doesn't meet this card's bounded in-place-fix bar (④: not the same gate family).

A broader heuristic sweep (Silent-bucket family with hints.length > 0 whose own script shows a recursive-readdirSync/scoped-git ls-files walk signature) found 12 more distinct scripts (23 rows counting --self-test pairs); 2 already tracked in bare-root-worklist.mjs (check-position-name-fold-loaders, check-whole-set-label-write); the other 10 unlisted anywhere. Reading their headers, most look like uniform invariant scans with no per-file "declared-conformant members" table — a different, already-recognised species (undeclared wide/subtree population), not this card's specific self-concealing-registry shape. check-system-context-census.mjs (30 hints, git ls-files-backed) is the strongest other candidate and was not independently confirmed (no positive control run against it). Filed as #17050 for individual triage.

⛔ Per the card's own warning: this sweep only examined the Silent bucket for this one signature. It is not exhaustive, and a heuristic zero for a script that doesn't match the walk signature is not a clearance.

Verification

• node scripts/check-route-envelope.mjs --self-test — green (✓ check-route-envelope self-test passed). Unaffected by design: the marker is a comment, no audited-file behaviour changed.
• node scripts/pm/dispatch-gates.mjs --self-test, run against the original, unfixed source — green, 1580 cases (✓ dispatch-gates self-test: 1580 cases pass.).
• Same self-test against an earlier version of this fix — red: ✗ dispatch-gates self-test: 1 of 1585 case(s) failed (a glob hint is refused even when the reason text repeats it back verbatim). Root cause: my own fixture used packages/rest/src/**, which this file's judgedAsPattern does not treat as a glob (a bare trailing /** collapses to a plain directory prefix, collapseHint's own rule) — confirmed with a direct call before editing further. Fixed by using an actual non-final-segment glob (packages/*/src) for the "never exempt" case and adding a companion case proving a bare trailing /** IS treated like an ordinary directory hint, on purpose.
• node scripts/pm/dispatch-gates.mjs --self-test, run against this diff (final) — green, 1586 cases (✓ dispatch-gates self-test: 1586 cases pass., os-verify-lock: VERDICT command-exit 0).
• node scripts/pm/bare-root-worklist.mjs --self-test (it imports widePopulationRefusal/discoverFamilies from the edited file directly) — green: OK self-test: 78 live row(s) … none stale, none missing, none contradicted (12 row(s) whose gate carries the dispatch-gates wide-population declaration … none of them is covered, so none is excused by it today), os-verify-lock: VERDICT command-exit 0.
• Gate reconciliation for THIS diff (dispatch-gates.mjs --commands/--ran): derived family count for a diff touching only scripts/check-route-envelope.mjs + scripts/pm/dispatch-gates.mjs includes each script's own identity-matched self-test/production families (both edited files match themselves via the identity key). Both self-tests above are those families' own gates, run directly and green — the reconciliation's "run vs derived" question is answered by construction for this diff (the only two runnable families a change to these two files owes are the two self-tests just run).

What this does NOT close

This fixes "the gate was never named" — it does not touch the separate, sharper failure #17041 records: "the gate was named, ran, and could not fail" (a derived, green check whose assertions are too coarse for the actual diff). Being in the Declared WIDE population bucket (or matched) is necessary, not sufficient; #17041 is open and this PR does not close that class.

Scope note

⛔ Does not touch a .github/workflows/*.yml file — confirmed, git diff --stat shows only the two scripts/** files. ⛔ Does not widen check:route-envelope's audited behaviour — same files error, same files pass (MODULES, discover(), discoverResponseWriters(), scanSource all untouched). scripts/ is not a governed surface; scripts/pm/** is this seat's lane per the claim comment. Clause-②: no (no published-package symbol, payload key, or packages/spec/src/** path touched — confirmed by the file list above).

---

🤖 Generated with Claude Code

https://claude.ai/code/session_012zTkyNHJ7TkuN2oXtP5x37