chore(tooling): enumerate namespace-claiming wildcard mounts and require each to be classified (#4116)

A handler mounted on `<prefix>/*` claims an entire namespace, and Hono runs every
handler matching a path in registration order with the first Response winning. So
a TERMINAL wildcard — one that always answers, never yields — makes every other
route under that prefix reachable only when it happens to register first, and
plugin registration order is not a contract anyone declares or tests.

That shape has now cost four fixes, and every one was found by hand, after the
fact, by someone reading the code for an unrelated reason:

  - #2567 — anonymous-deny on raw `/data` held only while REST registered first,
    so a load-order change silently reopened anonymous data access.
  - #4018 — the standalone `/discovery` sat behind the dispatcher's, so a third
    publisher drifted unnoticed.
  - #4088 / #4092 — AuthPlugin's `/api/v1/auth/*` swallowed plugin-hono-server's
    `/auth/me/permissions`, the console's entire permission layer.
  - cloud#923 — the same shape in AuthProxyPlugin, which cloud had ALREADY hit in
    staging (its apps/*/server/index.ts record the Console 404ing on that path).

Nothing in CI noticed any of them, and nothing would notice the fifth. The driven
tests #4092 and cloud#923 shipped each pin ONE catch-all and cannot cover the next
wildcard someone mounts — a test only drives the routes that existed when it was
written. What never existed is the ENUMERATION.

This adds it, following check-route-envelope.mjs (#3843) including the part that
matters most: a site the scan finds but the ledger does not declare is an ERROR,
not a default. Three states — `yields` (verified from the AST, so an entry cannot
rot: delete the next() and it fails), `exempt` with a reason for a wildcard that
is supposed to own its namespace, `ratchet` naming the issue for one that is
terminal and should not be. No fourth state where nobody looked.

AST rather than regex because "does this call next()?" is a question about the
handler's parameter binding: a comment or string mentioning next(), or an inner
closure's own next, all fool a textual match in the direction that PASSES while
the defect ships, and the parameter is not always named `next`. Handlers passed by
identifier are resolved too — cloud#923 mounts its handler that way, and a scan
that only understood inline arrows would have called it terminal.

Found 13 namespace-claiming mounts where a manual grep had found 3, and with them
two real, previously untracked instances of the #4088 defect in
`packages/adapters/hono` (`${prefix}/auth/*`, `${prefix}/storage/*`) — ratcheted
under #4117. It also separates that file's deliberate `${prefix}/*` ownership
(ADR-0076 OQ#9) from the two that merely forgot to yield; in source they look
identical.

Verified both directions by hand: reverting #4092's fix fails with the terminal
diagnostic, and adding a new undeclared `${prefix}/reports/*` catch-all fails as
NOT DECLARED. Self-test covers 15 cases, including the three textual-match
failure modes and identifier handler resolution.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VZLsKypjrGhiLpio2uWKu

Author: claude

.changeset/wildcard-fallthrough-guard.md

@@ -0,0 +1,27 @@
+---
+---
+
+chore(tooling): enumerate namespace-claiming wildcard mounts and require each to be classified (#4116)
+
+Release-nothing: adds `scripts/check-wildcard-fallthrough.mjs` plus its CI step.
+No package code changes.
+
+A handler mounted on `<prefix>/*` claims an entire namespace, and Hono runs
+handlers matching a path in registration order with the first Response winning.
+So a TERMINAL wildcard — one that always answers and never yields — makes every
+other route under that prefix reachable only when it happens to register first.
+That shape has cost four fixes (#2567, #4018, #4088/#4092, cloud#923) and every
+one was found by hand, after the fact, by someone reading the code for an
+unrelated reason.
+
+The two driven tests #4092 and cloud#923 shipped each pin one catch-all, and are
+structurally unable to cover the next wildcard someone mounts. What never existed
+is the enumeration. This scan is it: three states (`yields`, verified from the AST
+so the entry cannot rot; `exempt` with a reason; `ratchet` naming the issue), and
+a mount the scan finds but the ledger does not declare is an error, never a
+default — the same shape as `check-route-envelope.mjs` (#3843).
+
+It found 13 namespace-claiming mounts where a manual grep had found 3, including
+two real, previously untracked instances of the #4088 defect in
+`packages/adapters/hono` (`${prefix}/auth/*` and `${prefix}/storage/*`), now
+ratcheted under #4117.

.github/workflows/lint.yml

@@ -123,6 +123,19 @@ jobs:
       - name: Error-code casing guard
         run: pnpm check:error-code-casing
 
+      # Namespace-wildcard fall-through guard (#4116). A handler mounted on
+      # `<prefix>/*` claims the whole namespace, and Hono's first-registered
+      # handler that answers wins — so a TERMINAL wildcard makes every other
+      # route under that prefix reachable only by registration luck. That shape
+      # has now cost four fixes (#2567, #4018, #4088/#4092, cloud#923) and every
+      # one was found by hand, never by CI. Per-plugin tests cannot cover the
+      # next one; what was missing is the ENUMERATION. Three states — yields
+      # (verified from the AST, so it cannot rot) / exempt-with-reason / ratchet
+      # — and an undeclared mount is an error, never a default. Runs its own
+      # --self-test first.
+      - name: Wildcard fall-through guard
+        run: pnpm check:wildcard-fallthrough
+
       # Release-notes drift guard: the platform is one version-locked train, so
       # every released @objectstack/spec major must have a curated, navigable
       # release page at content/docs/releases/v<major>.mdx. Catches the gap that

package.json

@@ -36,6 +36,7 @@
     "check:authz-resolver": "node scripts/check-single-authz-resolver.mjs",
     "check:route-envelope": "node scripts/check-route-envelope.mjs --self-test && node scripts/check-route-envelope.mjs",
     "check:error-code-casing": "node scripts/check-error-code-casing.mjs --self-test && node scripts/check-error-code-casing.mjs",
+    "check:wildcard-fallthrough": "node scripts/check-wildcard-fallthrough.mjs --self-test && node scripts/check-wildcard-fallthrough.mjs",
     "check:console-sha": "node scripts/check-console-sha.mjs",
     "check:release-notes": "node scripts/check-release-notes.mjs",
     "check:node-version": "node scripts/check-node-version.mjs"