@bongos/core 1.19.625 → 1.19.626

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.625",
-  "core_contract": "1.19.625",
-  "source_commit": "19a2b295b0d1a0755168ec39b249dc1a5f9b961e",
+  "core_version": "1.19.626",
+  "core_contract": "1.19.626",
+  "source_commit": "15d768a9fe3239e170150c8d2efb98e6de8d98da",
   "source_ref": "HEAD",
-  "built_at": "2026-09-09T08:21:23.081Z",
+  "built_at": "2026-09-09T14:24:41.469Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 464,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2094,
+    "functional_verbatim": 2096,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2582,
-  "tree_sha256": "c6d6c5f0e0b67618fd3d94d6beb816506c9d15c480cc0dc0de0768b4b27cce23",
+  "file_count": 2584,
+  "tree_sha256": "1fbadd48214869e3a766dde80f634c74c81a7ee96bf480937417526afe50a27b",
   "files": [
     {
       "path": ".claude/skills/backlog-review/SKILL.md",
@@ -1907,12 +1907,12 @@
     {
       "path": "docs/copy-inventory.md",
       "mode": "0000644",
-      "sha256": "69a114c124cf97c86e7449366d4abfc1cc193649c1abdc2b93655f45886c7bfc"
+      "sha256": "da4d2796fa7ecbfb26c308cb7d1c5074c8c7d0d76d98995549166f265c53c656"
     },
     {
       "path": "docs/copy-registry.json",
       "mode": "0000644",
-      "sha256": "bfd0e82c97405348f7d2f5bb7cacfa3143adab91f5b9ebfcd7fa8d7a804e76f7"
+      "sha256": "222db57e3effc7706591e17b7ab901b198c79a46212c16b3221d1bb2b31754e2"
     },
     {
       "path": "docs/design/apex-pass-2-direction.md",
@@ -2757,7 +2757,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "6979862e5d574d45a8cf53196775cb2f3c53e601e4f812e3bd69c3b3a9c7cc15"
+      "sha256": "19d4d61c3cd024932aeb068335ef1d9d69e37a59a0e7d653a5e6136bb4972c19"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4912,7 +4912,7 @@
     {
       "path": "modules/hall-ui/public/goal-inbox.js",
       "mode": "0000644",
-      "sha256": "524a475dd6ab05e805e8db6baf11c90e10a3e6e76d7a423ffe571cafe61c0324"
+      "sha256": "0e6aacc6e720d1865c45f71b2458f23c5bac8f1643082256f4d7e71d97078994"
     },
     {
       "path": "modules/hall-ui/public/goals-lib.js",
@@ -5507,7 +5507,7 @@
     {
       "path": "modules/ideas/routes/inbox.js",
       "mode": "0000644",
-      "sha256": "8dec7682099d131ca050487dafe259bf4c9b511103c472cd0cbce54b4b9a898f"
+      "sha256": "5e7bdb2c09e1e62aacb4b40843392e2c1ca1534a69191c00c3103a257f086c31"
     },
     {
       "path": "modules/ideas/routing.js",
@@ -7682,12 +7682,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b1bf1316b6bf58eede860ae199233be76e1beb440d2cf7f4c96171e8f6347f05"
+      "sha256": "008a893c7efba51a8e8b7feff7b0569454c3b85670369ad736c28ba25b331c75"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "1e54c8559b66bcda15cbfb24e216bb5d3421a9e0c9d07f240c2414019288fe9a"
+      "sha256": "a8f88df15fae0f2566f18b0d78985e82d8d6ab5c72ee35cdf1598130ac2e8ce3"
     },
     {
       "path": "public-docs/index.html",
@@ -8142,7 +8142,7 @@
     {
       "path": "scripts/gds/fitness.js",
       "mode": "0000644",
-      "sha256": "a93e0d79fe1d557d09711e9b9bb62ffc7687b91ee2981b71eb89176eb0fc2ce6"
+      "sha256": "cd9f61f69ef8d017a39bed129e41a3d3944cf53bfaf6ff26eb868e46611b6dc3"
     },
     {
       "path": "scripts/gds/gate-review.js",
@@ -8187,7 +8187,7 @@
     {
       "path": "scripts/gds/gen-api-docs.js",
       "mode": "0000644",
-      "sha256": "03b4263f19c0f7157160011f43a174599e5294f0b62fdaf3a6e943e9bfeec855"
+      "sha256": "f9c0d6a1fb24158109d2753c9c2bcb79060a67198a7396ed7ba85bdeadfdeaca"
     },
     {
       "path": "scripts/gds/gen-atlas.js",
@@ -8574,6 +8574,11 @@
       "mode": "0000644",
       "sha256": "084fa5c4da1e755fa0edde5ec770e5151a9f66a247bca222bc7a2366ccf61748"
     },
+    {
+      "path": "scripts/gds/route-shadow-guard.js",
+      "mode": "0000644",
+      "sha256": "be2196b6f1e8859924d5f6b50c5a0cb476938ea70d37b5f820713dd8f5fd15f7"
+    },
     {
       "path": "scripts/gds/routine-schedule.js",
       "mode": "0000644",
@@ -9282,7 +9287,7 @@
     {
       "path": "src/bongos/route-rank-check.js",
       "mode": "0000644",
-      "sha256": "96b884a69b7b709a256d220c97a972f9827d74a36a864c216a7b37db3fdf66be"
+      "sha256": "ad2d07652864d577736f6c0f83e27ff197fe2201796eb06c5577743c16119a5b"
     },
     {
       "path": "src/bongos/routes.js",
@@ -9422,7 +9427,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "7a6f5a46c866658041e6299fe46188834184f510dd496edef5cb2f7b0c414088"
+      "sha256": "13157fd8a1bf1a5d1b892a3deed40c9fc1a85c7daf5db9bf5283837e261a6081"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9542,7 +9547,7 @@
     {
       "path": "tests/api_docs.mjs",
       "mode": "0000644",
-      "sha256": "56c093b994b9539ac93fdf206efe00b0c4318e01f65f4fbe377c31981c7c5bd6"
+      "sha256": "b8725188b7385ec26d35365256cd3eab25d62eaeabfeab6a979de0a447b77b04"
     },
     {
       "path": "tests/api_error_envelope_buildcheck.mjs",
@@ -11057,7 +11062,7 @@
     {
       "path": "tests/helpers.mjs",
       "mode": "0000644",
-      "sha256": "b3f0a87c51c9e655c712db00a0a8763e2fc08e4de3c6904c6080385e7c7dad14"
+      "sha256": "6a2360675b70ff2b32ca514e2baafa2aecb10e397a2f88630928ee93b351b34b"
     },
     {
       "path": "tests/hierarchy-config.mjs",
@@ -11157,7 +11162,7 @@
     {
       "path": "tests/idea_hall_composer.mjs",
       "mode": "0000644",
-      "sha256": "dbe8f91e4f3acc566a36547ce42d30328ba9e651a622fe1f25092d49d4e3a955"
+      "sha256": "84c5bb805688c484ea83d31e371f1b25fba1daaeb380cba41a21594ddb724de1"
     },
     {
       "path": "tests/idea_ideate_full.mjs",
@@ -11182,7 +11187,7 @@
     {
       "path": "tests/idea_routing.mjs",
       "mode": "0000644",
-      "sha256": "d4d4e6ce60f1524e821e0c6c9f2844c7ba791b5502072dc00496224404afa990"
+      "sha256": "3a2c5d2e6c3231f69847e1e2aea073e78caf26228b500dbdf612b5bae354d0a2"
     },
     {
       "path": "tests/idea_spark_hall.mjs",
@@ -11197,7 +11202,7 @@
     {
       "path": "tests/idea_spark_queue.mjs",
       "mode": "0000644",
-      "sha256": "43f801610e37062c54e631904aecaa10aa2486139aba3aa9eeb820d84fd32368"
+      "sha256": "8bfc36537ffccae702e74e8763534fa535486a2eb8bbf9ee546a2c7368d1dc6b"
     },
     {
       "path": "tests/idea_task_lineage.mjs",
@@ -11772,7 +11777,7 @@
     {
       "path": "tests/profile_activity.mjs",
       "mode": "0000644",
-      "sha256": "013df2528c4998588c1d3f89a9a25f8fa1e912b8abc2d8e95c26c250869a386f"
+      "sha256": "a2c62f9c4acf6f7e683766ae29a616c9325465468a86f38c1d512f58efd124df"
     },
     {
       "path": "tests/profile_connections_ui.mjs",
@@ -11902,7 +11907,7 @@
     {
       "path": "tests/prose_edits.mjs",
       "mode": "0000644",
-      "sha256": "a613b7cfa675db5231c44319146333d173d2dfa53da092654d5bd11a141483f4"
+      "sha256": "a36acb19e59db1f9eb885ab6497a43d1c8ce0ba6198b0f5cc98f33bf08837fdf"
     },
     {
       "path": "tests/provision.mjs",
@@ -12164,6 +12169,11 @@
       "mode": "0000644",
       "sha256": "bdc58224050392ece492ae8e8f12f62a8934d86e3993e0df5b8cb0aac80602e8"
     },
+    {
+      "path": "tests/route_shadow_guard.mjs",
+      "mode": "0000644",
+      "sha256": "552479822e1349a56bf68c636a35787d44da2abacf6917339ce5ce39223b9f2d"
+    },
     {
       "path": "tests/route_validation.mjs",
       "mode": "0000644",

package/docs/copy-inventory.md

@@ -597,7 +597,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `ae84ebe1d735` | certain | Name cannot be blank. | `modules/hall-ui/public/settings.js:831` |
 | `31e91ee6ce03` | certain | Name must be {…} characters or fewer. | `modules/hall-ui/public/settings.js:836` |
 | `5e8199266a8a` | certain | Name unvouched | `modules/hall-ui/public/watch.js:350` |
-| `7def635421ea` | certain | Needs your attention | `modules/hall-ui/public/goal-inbox.js:385` |
+| `7def635421ea` | certain | Needs your attention | `modules/hall-ui/public/goal-inbox.js:396` |
 | `87f09d983f6c` | certain | New category label | `modules/hall-ui/public/project-settings.js:138` |
 | `d427d9dab01c` | certain | New claims are paused: {…} confirmed {…} can't land yet, so {…} reward is pending. Rebase and re-ship, or rele | `modules/hall-ui/public/hall-render.js:618` |
 | `7fcc2583c372` | certain | New custom rank | `modules/hall-ui/public/government.html:79` |

package/docs/copy-registry.json

@@ -6401,7 +6401,7 @@
       "surface": "builders-hall",
       "text": "Needs your attention",
       "file": "modules/hall-ui/public/goal-inbox.js",
-      "line": 385,
+      "line": 396,
       "origin": "js-markup",
       "confidence": "certain"
     },

package/docs/module-api-changelog.md

@@ -1699,5 +1699,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.623 with no explicit bump. run 34326009063. (task 1002620)
   1.19.625 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.624 with no explicit bump. run 34328603214. (task 1002620)
+  1.19.626 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.625 with no explicit bump. run 34363350286. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/hall-ui/public/goal-inbox.js

@@ -370,7 +370,18 @@
   function loadRot() {
     return getJSON(`${API}/inbox/rotting`)
       .then((data) => renderRot(data))
-      .catch(() => { /* signed out, older server, or a hiccup: never break the hall */ });
+      .catch((err) => {
+        // STILL FAIL-OPEN — a rot feed that cannot load must never break the hall,
+        // and being signed out or on an older server are both ordinary. But it now
+        // SAYS SO (task 1003747). The bare `.catch(() => {})` this replaces is how
+        // the feed stayed dead in production for releases: /inbox/rotting was being
+        // shadowed by another module's `/inbox/:id` and answering 400 bad_id, and
+        // this handler swallowed it into an empty section that looked like "nothing
+        // is rotting". A silent catch on the ONLY caller of a route is indistin-
+        // guishable from a healthy empty state — which is the whole failure.
+        console.warn('[hall] rot feed unavailable — the "Going quiet" section is empty '
+          + 'because the request failed, NOT because nothing is rotting:', err);
+      });
   }
 
   // task 2169: this widget IS the "Needs your attention" card — ONE capped

package/modules/ideas/routes/inbox.js

@@ -526,13 +526,41 @@ module.exports = function buildInboxRouter() {
     return res.json({ builder_id: builderId, ideas, total, limit, offset });
   }, { errorCode: 'idea_trail_failed' }));
 
+  // THE `(\d+)` ON THE TWO BARE-ID ROUTES BELOW IS LOAD-BEARING, NOT DECORATION
+  // (task 1003747). An idea id is always a positive integer, and constraining the
+  // param to digits is what stops these routes from swallowing a LITERAL
+  // `/inbox/<word>` contributed by ANOTHER module. It swallowed exactly that:
+  // `GET /inbox/rotting` (the rot feed, modules/lifecycle/routes/rot.js) answered
+  // 400 `bad_id` in production, because mountModuleRoutes
+  // (src/module-loader/loader.js) mounts modules in discovery order — `ideas`
+  // before `lifecycle` — so this matcher saw "rotting", failed to parse it as an
+  // id, and ended the request before the rot handler was ever reached. The whole
+  // 30-day rot cadence (ADR 0232) was dead and silent for releases.
+  //
+  // Declaring literals before `:id` (the convention modules/ideas/CLAUDE.md
+  // records) only fixes collisions INSIDE this file; it cannot reach a route
+  // another module contributes. The digit constraint can, because it makes the
+  // non-numeric path fall THROUGH to whatever is mounted later, whatever the
+  // order. `scripts/gds/route-shadow-guard.js` fails the build on any remaining
+  // pair of this shape, and gen-api-docs strips the constraint so it never
+  // reaches the published spec.
+  //
+  // Trade-off, taken deliberately: `/inbox/abc` now 404s ("no such route")
+  // instead of 400 `bad_id`. No test pinned that 400, and 404 is the more honest
+  // answer for a path that matches no route.
+  //
+  // The blank line below is deliberate: commentBlockAbove() in gen-api-docs.js
+  // walks upward from the route and stops at it, so THIS rationale stays in the
+  // source for the next reader without becoming the route's public API
+  // description.
+
   // rank: any-builder — single idea read for the "#NNN" deep-link resolver
   // (#1047). Mirrors GET /blockers/:id. The hall resolves /#/idea/N by id, but
   // the /inbox LIST returns only the open-first-50, so a closed/older idea ref
   // would dead-end at a "no such idea" card. getIdea() reads any idea by id.
   // Authed: a logged-out resolve hits the hall's softAuth "sign in" card, so no
   // idea text is exposed publicly (the linked refs are public, the bodies aren't).
-  router.get('/inbox/:id', api.requireBuilder, async (req, res) => {
+  router.get('/inbox/:id(\\d+)', api.requireBuilder, async (req, res) => {
     const id = parseId(req, res, { code: 'bad_id', positiveInt: true });
     if (id === null) return;
     try {
@@ -1025,7 +1053,13 @@ module.exports = function buildInboxRouter() {
     return res.json({ ok: true, idea: result.idea, delta: result.delta, unchanged: !result.delta });
   }, { errorCode: 'idea_body_update_failed' }));
 
-  router.patch('/inbox/:id', api.requireBuilder, api.requirePermission('idea.triage'), async (req, res) => {
+  // `(\d+)` for the same reason as the GET above — see that comment. No PATCH
+  // literal collides today; the constraint is here so the pair of bare-id routes
+  // on this path stay symmetric and a future `PATCH /inbox/<word>` cannot be
+  // quietly eaten. Kept above a blank line so it stays out of the published API
+  // description, same as the GET's rationale.
+
+  router.patch('/inbox/:id(\\d+)', api.requireBuilder, api.requirePermission('idea.triage'), async (req, res) => {
     if (validateOrRespond(req, res, {
       // Enum kept light — inbox.updateIdea returns a structured BAD_STATUS
       // error if the value falls outside the accepted set, and the supervisor

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.625",
+  "version": "1.19.626",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.625",
+      "version": "1.19.626",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.625",
+  "version": "1.19.626",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/fitness.js

@@ -1389,6 +1389,7 @@ const CHECKS = [
   require('./routine-schedule.js').checkRoutineCadencesScheduled, // Check 25 — task 1003209: a routine that declares a cadence must have a scheduler firing it AT that period (ADR 0188)
   require('./baseline-staleness.js').checkBaselineFloors, // Check 26 — task 1003210: a shrink-only baseline that never shrinks is unmanaged debt; a floor exempting one must say why
   require('./client-baseurl-guard.js').checkClientBaseUrl,
+  require('./route-shadow-guard.js').checkNoRouteShadowing, // Check 31 — task 1003747: a `:param` route must not swallow a literal route mounted after it (cross-module mount order; the rot feed shipped dead this way). Rationale in that file.
   require('./test-path-guard.js').checkTestsUseFileUrlToPath, // Check 30 — task 1002889: a test builds its repo root with fileURLToPath, never URL.pathname (a %20 or a Windows drive slash makes require() throw at load; CI's spaceless checkout can't see it)
   // Check 29 — task 1003275 / ADR 0189: a work category ORIENTS a human and steers
   // Claude; it authorises nothing. The owner said so twice, and the goal's own prose

package/scripts/gds/gen-api-docs.js

@@ -34,6 +34,12 @@ const path = require('node:path');
 
 const { resolveCoreRoot, resolveDocsRoot } = require('../../src/instance-config');
 const rrc = require('../../src/bongos/route-rank-check');
+// Destructured, not reached through `rrc.` — knip tracks a destructured CJS require but
+// not namespace member access, so `rrc.canonicalRoutePath(...)` read as an unused export
+// and tripped the dead-code ratchet (knip_issue_count 224 > baseline 223) even though the
+// call site below is real. The named import is how a new helper on this module gets
+// counted as used (task 1003747).
+const { canonicalRoutePath } = require('../../src/bongos/route-rank-check');
 const { API_PREFIX, API_VERSION, VERSIONED_API_PREFIX } = require('../../src/bongos/api-prefix');
 // Task 2050 (ADR 0118): the enriched extractor resolves named constants used in
 // validate() rules. Both requires are pure (no side effects / no DB / no express):
@@ -122,10 +128,27 @@ function commentBlockAbove(lines, i) {
   return neutralizeTaskRefs(text);
 }
 
-// :param → {param}; also return the ordered param name list.
+// An Express inline param constraint — `:id(\d+)` (task 1003747). It is a ROUTING
+// detail, never part of the URL a caller types, so it is stripped everywhere a
+// route string reaches a reader or the spec. Without this, `/inbox/:id(\d+)`
+// generated the path template `/inbox/{id}(\\d+)` (malformed — it would break the
+// generated client), renamed the operationId `get_inbox_id` → `get_inbox_id_d`
+// (a silent breaking change for every client consumer), and printed the regex in
+// the public API reference.
+// The canonicaliser itself lives in route-rank-check, next to scanDeclarations — the
+// scanner this generator already shares with the auditor — so there is ONE definition
+// rather than a copy per consumer. Declarations therefore arrive canonical already;
+// this wrapper stays because pathParams/routeForDisplay are pure exported helpers that
+// callers (and tests/api_docs.mjs) hand raw strings to directly.
+function routeForDisplay(route) {
+  return canonicalRoutePath(String(route || ''));
+}
+
+// :param → {param}; also return the ordered param name list. Inline constraints
+// are dropped first so the template stays a valid OpenAPI path.
 function pathParams(route) {
   const names = [];
-  const openapiPath = route.replace(/:([A-Za-z0-9_]+)/g, (_, n) => {
+  const openapiPath = routeForDisplay(route).replace(/:([A-Za-z0-9_]+)/g, (_, n) => {
     names.push(n);
     return `{${n}}`;
   });
@@ -732,7 +755,7 @@ function buildOperation(r, stats, schemas) {
   const op = {
     operationId: operationId(r.method, r.openapiPath),
     tags: [r.tag],
-    summary: `${r.method} ${r.route}`,
+    summary: `${r.method} ${routeForDisplay(r.route)}`,
     description: (r.description ? r.description + '\n\n' : '')
       + `**Rank:** \`${r.rank}\` — ${RANK_BLURB[r.rank] || RANK_BLURB.unknown}`
       + (r.perms && r.perms.length ? `\n\n**Permissions:** \`${r.perms.join('`, `')}\` (all required).` : ''),
@@ -908,7 +931,7 @@ function buildReferenceMd(model, spec) {
           ? (r.body.fields.length ? '`' + r.body.fields.join('`, `') + '`' : 'validated')
           : '_undocumented_')
         : '—';
-      L.push(`| ${r.method} | \`${API_PREFIX}${r.route}\` | \`${r.rank}\` | ${body} | ${shortDesc(r.description)} |`);
+      L.push(`| ${r.method} | \`${API_PREFIX}${routeForDisplay(r.route)}\` | \`${r.rank}\` | ${body} | ${shortDesc(r.description)} |`);
     }
     L.push('');
   }
@@ -1053,6 +1076,7 @@ module.exports = {
   validateOpenapi,
   commentBlockAbove,
   pathParams,
+  routeForDisplay,
   captureBalanced,
   topLevelKeys,
   topLevelEntries,

package/scripts/gds/route-shadow-guard.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// scripts/gds/route-shadow-guard.js — a `:param` route must not swallow a LITERAL
+// route mounted after it (task 1003747).
+//
+// THE BUG THIS EXISTS TO STOP. `GET /inbox/rotting` — the rot feed behind the
+// hall's "Going quiet" section (modules/lifecycle/routes/rot.js) — answered
+// `400 bad_id` in production for releases. Nothing was wrong with the handler: it
+// was never reached. `mountModuleRoutes` (src/module-loader/loader.js) mounts each
+// enabled module's route factories in DISCOVERY order, so `ideas` mounted its
+// `GET /inbox/:id` before `lifecycle` mounted `GET /inbox/rotting`; Express matched
+// the param route first, failed to parse "rotting" as an id, and ended the request.
+// The entire 30-day rot cadence (ADR 0232 — "work must not decay in silence") was
+// dead, and its only caller swallowed the error, so the section rendered empty and
+// looked healthy.
+//
+// WHY A FITNESS CHECK AND NOT A TEST. The collision is a property of the MOUNT
+// ORDER ACROSS MODULES, which no single module's tests can see — each module's
+// routes are correct in isolation, and modules/ideas/CLAUDE.md's "declare literals
+// before :id" convention only governs collisions inside one file. The defect only
+// exists in the assembled router, and it presents as a plausible 400 rather than a
+// crash, so nothing goes red. A static scan at the assembly altitude is the only
+// place this is visible before a user reports an empty page.
+//
+// WHAT COUNTS AS SHADOWING. Same HTTP method, same segment count, every segment
+// equal up to one position where the earlier route has a `:param` and the later
+// route has a literal. Same-arity is required because Express only matches a
+// pattern against a path of equal depth (no wildcards are in play here), and the
+// param must sit where the literal is or the two never compete.
+//
+// THE FIX IT POINTS AT. Constrain the param so a non-numeric segment falls
+// THROUGH — `router.get('/inbox/:id(\\d+)', …)` — which works regardless of mount
+// order. Reordering declarations is NOT a general fix: it cannot reach a route
+// another module contributes.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const NAME = 'no `:param` route shadows a literal route mounted after it (task 1003747)';
+
+// Route declarations, as written. Matches the `router.<method>('<path>'` form every
+// route factory in this repo uses.
+const ROUTE_DECL = /router\.(get|post|patch|put|delete)\(\s*['"`]([^'"`]+)['"`]/g;
+
+// A param segment already constrained by an inline Express pattern — `:id(\d+)` —
+// cannot match a non-matching literal, so it shadows nothing. Recognising this is
+// what makes the check pass once the fix is applied rather than demanding a
+// reorder it cannot verify.
+function isConstrainedParam(seg) {
+  return seg.startsWith(':') && seg.includes('(');
+}
+
+function isBareParam(seg) {
+  return seg.startsWith(':') && !seg.includes('(');
+}
+
+// The mount sequence: for each module with a module.json, its contributes.routes in
+// declared order, and within each file its route declarations in source order. This
+// mirrors mountModuleRoutes' iteration — modules in readdir order, route keys in
+// manifest order — so the sequence this returns is the order Express sees.
+function mountSequence({ modulesDir, readdir, readFile } = {}) {
+  const md = modulesDir || path.join(REPO_ROOT, 'modules');
+  const rd = readdir || ((d) => { try { return fs.readdirSync(d); } catch { return []; } });
+  const read = readFile || ((f) => { try { return fs.readFileSync(f, 'utf8'); } catch { return null; } });
+  const seq = [];
+  for (const key of rd(md)) {
+    const manRaw = read(path.join(md, key, 'module.json'));
+    if (manRaw == null) continue;
+    let man;
+    try { man = JSON.parse(manRaw); } catch { continue; }
+    for (const rk of ((man.contributes || {}).routes) || []) {
+      const rel = path.join('modules', key, 'routes', `${rk}.js`);
+      const src = read(path.join(md, key, 'routes', `${rk}.js`));
+      if (src == null) continue;
+      ROUTE_DECL.lastIndex = 0;
+      let m;
+      while ((m = ROUTE_DECL.exec(src))) {
+        seq.push({ module: key, file: rel, method: m[1], route: m[2] });
+      }
+    }
+  }
+  return seq;
+}
+
+const segments = (p) => p.split('/').filter(Boolean);
+
+// findShadowPairs(seq) — every (param route, later literal route) pair where the
+// param route wins the match. Pure + exported so tests pin the rule without a
+// filesystem.
+function findShadowPairs(seq) {
+  const pairs = [];
+  for (let i = 0; i < seq.length; i += 1) {
+    const early = seq[i];
+    const a = segments(early.route);
+    if (!a.some(isBareParam)) continue;
+    for (let j = i + 1; j < seq.length; j += 1) {
+      const later = seq[j];
+      const b = segments(later.route);
+      if (early.method !== later.method || a.length !== b.length) continue;
+      let shadows = true;
+      let viaParam = false;
+      for (let k = 0; k < a.length; k += 1) {
+        if (isBareParam(a[k])) {
+          // A param only eats a LITERAL. Two params at the same position are the
+          // same route shape, not a shadowing pair.
+          if (b[k].startsWith(':')) { shadows = false; break; }
+          viaParam = true;
+        } else if (isConstrainedParam(a[k])) {
+          shadows = false; // constrained: it cannot match an arbitrary literal
+          break;
+        } else if (a[k] !== b[k]) {
+          shadows = false;
+          break;
+        }
+      }
+      if (shadows && viaParam) pairs.push({ early, later });
+    }
+  }
+  return pairs;
+}
+
+function checkNoRouteShadowing(opts = {}) {
+  const seq = opts.sequence || mountSequence(opts);
+  if (!seq.length) {
+    return {
+      name: NAME,
+      ok: false,
+      hardFail: true,
+      violations: ['scan defect — enumerated 0 route declarations across modules/*/routes; '
+        + 'a broken enumeration, not a clean result.'],
+      warnings: [],
+      note: 'static scan of the cross-module route mount order.',
+    };
+  }
+  const pairs = findShadowPairs(seq);
+  const violations = pairs.map(({ early, later }) => (
+    `${early.method.toUpperCase()} ${early.route} (${early.file}) is mounted BEFORE `
+    + `${later.method.toUpperCase()} ${later.route} (${later.file}) and swallows it — `
+    + `a request for ${later.route} never reaches its handler. `
+    + `Constrain the param so a non-matching segment falls through `
+    + `(e.g. '${early.route.replace(/:(\w+)(?![\w(])/, ':$1(\\\\d+)')}'); reordering cannot fix a `
+    + 'cross-module pair, because mount order follows module discovery.'
+  ));
+  return {
+    name: NAME,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${seq.length} route declaration(s) scanned in mount order: no bare \`:param\` route may `
+      + 'precede a literal route of the same method and depth. The rot feed shipped dead for releases '
+      + 'this way (GET /inbox/:id ate GET /inbox/rotting across a module boundary) and presented as a '
+      + 'plausible 400, so no test went red.',
+  };
+}
+
+function main() {
+  const r = checkNoRouteShadowing();
+  for (const v of r.violations) console.error(`✗ ${v}`);
+  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
+  process.exit(r.hardFail ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  checkNoRouteShadowing,
+  findShadowPairs,
+  mountSequence,
+  isBareParam,
+  isConstrainedParam,
+  ROUTE_DECL,
+};

package/src/bongos/route-rank-check.js

@@ -630,11 +630,36 @@ const ROUTE_PATH_LINE_RE = /^\s*['"]([^'"]+)['"]\s*,/;
 // in every real case; the slack only tolerates an interleaved comment.
 const PATH_LOOKAHEAD = 5;
 
+// An Express inline param constraint — the `(\d+)` in `/inbox/:id(\d+)`. It constrains
+// MATCHING; it is not part of the path a caller types, so every consumer of "the route
+// path" must see the canonical form (task 1003747).
+//
+// WHY THIS LIVES HERE. scanDeclarations is the single scanner the auditor, the published
+// OpenAPI contract and a dozen route-order tests all read (see its comment below). When
+// `GET /inbox/:id` gained a `(\d+)` — to stop it swallowing another module's
+// `GET /inbox/rotting` — the raw string leaked into all of them at once: the OpenAPI path
+// template became the malformed `/inbox/{id}(\\d+)`, the operationId silently renamed
+// `get_inbox_id` → `get_inbox_id_d` (a breaking change for every generated-client
+// consumer), and FIVE test files that look up `/inbox/:id` by exact string stopped finding
+// it — reporting the route as "unreachable" or "not mounted" when nothing was wrong with
+// it. Canonicalising at the scanner fixes all of them in one place; doing it per-consumer
+// is how the contract and the gate list drift apart.
+//
+// The CONSTRAINT ITSELF still matters to one reader: scripts/gds/route-shadow-guard.js
+// reads raw source with its own regex, precisely because a constrained param is the thing
+// that makes a route safe to mount before a literal. That guard must keep seeing it.
+const PARAM_CONSTRAINT_RE = /:([A-Za-z0-9_]+)\([^)]*\)/g;
+
+function canonicalRoutePath(p) {
+  return p == null ? p : String(p).replace(PARAM_CONSTRAINT_RE, ':$1');
+}
+
 // The literal path a declaration at line `i` names, or null when it is not statically
-// resolvable (a template literal, a variable, a computed path).
+// resolvable (a template literal, a variable, a computed path). Inline param constraints
+// are canonicalised away — see canonicalRoutePath.
 function routePathAt(lines, i) {
   const same = ROUTE_DECL_SAME_LINE_RE.exec(lines[i]);
-  if (same) return same[2];
+  if (same) return canonicalRoutePath(same[2]);
   // Multi-line form: nothing but whitespace/comment may follow the '(' …
   const rest = lines[i].slice(lines[i].indexOf('(') + 1).trim();
   if (rest !== '' && !rest.startsWith('//')) return null;
@@ -643,7 +668,7 @@ function routePathAt(lines, i) {
     const t = lines[j].trim();
     if (t === '' || t.startsWith('//')) continue;
     const m = ROUTE_PATH_LINE_RE.exec(lines[j]);
-    return m ? m[1] : null;
+    return m ? canonicalRoutePath(m[1]) : null;
   }
   return null;
 }
@@ -939,6 +964,7 @@ module.exports = {
   classifyRank,
   classifyText,
   scanDeclarations,
+  canonicalRoutePath,
   discoverRouteFiles,
   checkRouteRanks,
   toWorkerResult,

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.625'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.626'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/api_docs.mjs

@@ -76,6 +76,34 @@ t('pathParams: :id → {id} and names captured', () => {
   assert.deepEqual(r.names, ['id']);
 });
 
+// task 1003747: an Express inline param constraint is a ROUTING detail and must
+// never reach the published contract. Before this, `/inbox/:id(\d+)` produced the
+// malformed path template `/inbox/{id}(\\d+)` and silently renamed the
+// operationId `get_inbox_id` → `get_inbox_id_d` — a breaking change for every
+// generated-client consumer, from a change that altered no URL.
+t('pathParams: an inline param constraint is stripped from the path template', () => {
+  const r = gen.pathParams('/inbox/:id(\\d+)');
+  assert.equal(r.openapiPath, '/inbox/{id}');
+  assert.deepEqual(r.names, ['id']);
+});
+
+t('pathParams: a constrained param yields the SAME template as a bare one', () => {
+  assert.equal(gen.pathParams('/inbox/:id(\\d+)').openapiPath,
+    gen.pathParams('/inbox/:id').openapiPath);
+});
+
+t('routeForDisplay: the reader sees /inbox/:id, never the regex', () => {
+  assert.equal(gen.routeForDisplay('/inbox/:id(\\d+)'), '/inbox/:id');
+  assert.equal(gen.routeForDisplay('/tasks/:id/water'), '/tasks/:id/water');
+  assert.equal(gen.routeForDisplay(''), '');
+});
+
+t('the published spec contains no leaked param constraint', () => {
+  const spec = JSON.parse(fs.readFileSync(path.join(ROOT, 'docs', 'api', 'openapi.json'), 'utf8'));
+  const leaked = Object.keys(spec.paths || {}).filter((p) => p.includes('(') || p.includes('\\'));
+  assert.deepEqual(leaked, [], `path templates must carry no regex: ${leaked.join(', ')}`);
+});
+
 t('topLevelKeys: depth-1 keys only, ignores nested min/max + inline comments', () => {
   const lit = `{
     title: { required: true, type: 'string', maxLength: 200 },

package/tests/helpers.mjs

@@ -148,6 +148,34 @@ export function lifecycleDbSource(modulesDir = path.join(ROOT, 'modules')) {
     (f) => f === 'db.js' || (f.startsWith('db-') && f.endsWith('.js')));
 }
 
+// assertCannotSwallow(assert, paths, literal, paramPath, label) — the route-ordering
+// invariant for a literal sharing a prefix with a `:param` route, e.g.
+// `/inbox/awaiting-nod` against `/inbox/:id` (task 1003747).
+//
+// WHY THIS IS NOT JUST AN indexOf. Four test files each asserted
+// `indexOf(literal) < indexOf('/inbox/:id')`, reading the LIVE router's
+// layer.route.path. That was the whole invariant while the param route was bare —
+// Express matches in registration order, so a literal declared after it arrives as
+// `:id='awaiting-nod'` and 400s on parseId: a bug whose only symptom is an empty card.
+//
+// It stopped being the whole invariant when `/inbox/:id` gained the constraint
+// `(\d+)`. A CONSTRAINED param cannot match a non-numeric segment at all, so it cannot
+// swallow the literal REGARDLESS of order — and the four tests, looking for the bare
+// string, instead reported the param route as "not mounted" and failed. Order-only was
+// always the narrower claim; the real property is that the literal is REACHABLE. This
+// asserts that directly, so both spellings pass for the right reason and neither adding
+// nor removing a constraint produces a false failure.
+export function assertCannotSwallow(assert, paths, literal, paramPath, label = paramPath) {
+  const iLit = paths.indexOf(literal);
+  assert.ok(iLit >= 0, `${literal} is not mounted at all`);
+  const bare = paths.indexOf(paramPath);
+  const constrained = paths.findIndex((p) => typeof p === 'string' && p.startsWith(`${paramPath}(`));
+  assert.ok(bare >= 0 || constrained >= 0, `${label} is not mounted at all`);
+  if (constrained >= 0) return; // constrained ⇒ cannot match a non-numeric segment; order is moot
+  assert.ok(iLit < bare,
+    `${literal} (${iLit}) must precede the unconstrained ${label} (${bare}), or ${label} swallows it`);
+}
+
 // The SHIP CLI: ship.js (facade + entry point) + the ship-*.js phase modules.
 export function shipCliSource(scriptsDir = path.join(ROOT, 'scripts', 'gds')) {
   return familySource(scriptsDir,

package/tests/idea_hall_composer.mjs

@@ -25,6 +25,7 @@ import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { assertCannotSwallow } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -162,10 +163,10 @@ await test('a draft written against another template is dropped, not half-restor
 // --- GET /inbox/template ------------------------------------------------
 
 await test('GET /inbox/template is declared BEFORE GET /inbox/:id', () => {
-  const iT = mounted.indexOf('GET /inbox/template');
-  const iId = mounted.indexOf('GET /inbox/:id');
-  assert.ok(iT >= 0 && iId >= 0);
-  assert.ok(iT < iId, `with :id first, "/inbox/template" binds id="template" and parseId 400s it (template@${iT}, :id@${iId})`);
+  // Declaration order OR a constrained param keeps this reachable — with a bare :id
+  // first, "/inbox/template" binds id="template" and parseId 400s it. See
+  // assertCannotSwallow in tests/helpers.mjs (task 1003747).
+  assertCannotSwallow(assert, mounted, 'GET /inbox/template', 'GET /inbox/:id');
 });
 
 await test('the template read returns the R141 declaration, in fieldOrder order', async () => {

package/tests/idea_routing.mjs

@@ -26,7 +26,7 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
-import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+import { makeRunner, makeSqlAwareClient, assertCannotSwallow } from './helpers.mjs';
 
 process.env.NODE_ENV = 'test';
 
@@ -989,10 +989,9 @@ await test('GET /inbox/awaiting-nod is registered BEFORE /inbox/:id, or it is un
   // a bug with no symptom except an empty card.
   const router = require('../modules/ideas/routes/inbox.js')({});
   const paths = router.stack.filter((l) => l.route).map((l) => l.route.path);
-  const iNod = paths.indexOf('/inbox/awaiting-nod');
-  const iParam = paths.indexOf('/inbox/:id');
-  assert.ok(iNod >= 0, 'the route exists');
-  assert.ok(iNod < iParam, `literal segment must precede the wildcard (got ${iNod} vs ${iParam})`);
+  // Order OR a constrained param — either makes this route reachable. See
+  // assertCannotSwallow in tests/helpers.mjs (task 1003747).
+  assertCannotSwallow(assert, paths, '/inbox/awaiting-nod', '/inbox/:id');
 });
 
 // =========================================================================

package/tests/idea_spark_queue.mjs

@@ -20,6 +20,7 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
+import { assertCannotSwallow } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const api = require('../src/module-api.js');
@@ -81,14 +82,10 @@ async function test(name, fn) {
 // --- declaration order: the bug that would 400 the whole queue -----------
 
 await test('GET /inbox/sparks is declared BEFORE GET /inbox/:id', () => {
-  const iSparks = mounted.indexOf('GET /inbox/sparks');
-  const iId = mounted.indexOf('GET /inbox/:id');
-  assert.ok(iSparks >= 0, 'the spark queue route is mounted');
-  assert.ok(iId >= 0, 'the by-id read is mounted');
-  assert.ok(
-    iSparks < iId,
-    `declaration order is load-bearing: with :id first, "/inbox/sparks" binds id="sparks" and parseId 400s the queue (sparks@${iSparks}, :id@${iId})`,
-  );
+  // Declaration order OR a constrained param keeps this reachable — with a bare :id
+  // first, "/inbox/sparks" binds id="sparks" and parseId 400s the queue. See
+  // assertCannotSwallow in tests/helpers.mjs (task 1003747).
+  assertCannotSwallow(assert, mounted, 'GET /inbox/sparks', 'GET /inbox/:id');
 });
 
 // --- the predicate: open, undeveloped sparks, newest first ---------------

package/tests/profile_activity.mjs

@@ -35,6 +35,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { assertCannotSwallow } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -79,11 +80,9 @@ const ideaRouter = ideaRoutesFactory({});
 const mountedPaths = ideaRouter.stack.filter((l) => l.route).map((l) => l.route.path);
 
 await test('GET /inbox/by-builder/:id is declared BEFORE GET /inbox/:id', () => {
-  const trail = mountedPaths.indexOf('/inbox/by-builder/:id');
-  const byId = mountedPaths.indexOf('/inbox/:id');
-  assert.ok(trail > -1, 'the trail route is mounted');
-  assert.ok(byId > -1, 'the by-id route is mounted');
-  assert.ok(trail < byId, `/inbox/by-builder/:id (${trail}) must precede /inbox/:id (${byId}) or :id swallows it`);
+  // Order OR a constrained param — either makes the trail route reachable. See
+  // assertCannotSwallow in tests/helpers.mjs (task 1003747).
+  assertCannotSwallow(assert, mountedPaths, '/inbox/by-builder/:id', '/inbox/:id');
 });
 
 // ---------------------------------------------------------------------------

package/tests/prose_edits.mjs

@@ -160,7 +160,12 @@ await test('ROUTE SHAPE: the triage-gated PATCH /inbox/:id was NOT widened to re
   assert.ok(row, 'the triage route still exists');
   assert.equal(row.rank, 'metic+archon', 'PATCH /inbox/:id must keep its triage-level gate');
   const src = readFileSync(new URL('../modules/ideas/routes/inbox.js', import.meta.url), 'utf8');
-  const start = src.indexOf("router.patch('/inbox/:id',");
+  // Tolerate an inline param constraint on the path — `'/inbox/:id(\d+)'` (task
+  // 1003747, which added one so this route stops swallowing another module's
+  // `/inbox/rotting`). Matching the bare literal made this test report the triage
+  // route as missing when only its MATCHER had been narrowed. The route key above
+  // is canonicalised for the same reason (src/bongos/route-rank-check.js).
+  const start = src.search(/router\.patch\('\/inbox\/:id(?:\([^)]*\))?',/);
   const body = src.slice(start, src.indexOf('router.', start + 20));
   // Assert on the VALIDATION SCHEMA, not on any mention of the string: that route
   // already discusses body_md in a comment (about it not being parseable as a

package/tests/route_shadow_guard.mjs

@@ -0,0 +1,215 @@
+// tests/route_shadow_guard.mjs — the guard that keeps a `:param` route from
+// swallowing a literal route mounted after it (task 1003747).
+//
+// GET /inbox/rotting answered 400 bad_id in production for releases: `ideas`
+// mounts GET /inbox/:id before `lifecycle` mounts GET /inbox/rotting, so the param
+// matched first and ended the request before the rot handler was reached. The
+// whole 30-day rot cadence was dead, and the hall's only caller swallowed the
+// error into an empty section that looked like "nothing is rotting".
+//
+// The guard is tested on SYNTHETIC mount sequences, not only the live tree: a scan
+// that passes because the tree is clean today proves nothing about what it
+// REFUSES. The live-tree case at the bottom is what proves the real fix holds.
+//
+// Run:  node tests/route_shadow_guard.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const {
+  checkNoRouteShadowing,
+  findShadowPairs,
+  mountSequence,
+  isBareParam,
+  isConstrainedParam,
+} = require('../scripts/gds/route-shadow-guard.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+const r = (module_, file, method, route) => ({ module: module_, file, method, route });
+
+// --- THE DEFECT, EXACTLY AS IT SHIPPED -------------------------------------
+
+test('catches the real pair: GET /inbox/:id mounted before GET /inbox/rotting', () => {
+  const pairs = findShadowPairs([
+    r('ideas', 'modules/ideas/routes/inbox.js', 'get', '/inbox/:id'),
+    r('lifecycle', 'modules/lifecycle/routes/rot.js', 'get', '/inbox/rotting'),
+  ]);
+  assert.equal(pairs.length, 1);
+  assert.equal(pairs[0].early.route, '/inbox/:id');
+  assert.equal(pairs[0].later.route, '/inbox/rotting');
+});
+
+test('the check hard-fails on that sequence, and names the fall-through fix', () => {
+  const out = checkNoRouteShadowing({
+    sequence: [
+      r('ideas', 'modules/ideas/routes/inbox.js', 'get', '/inbox/:id'),
+      r('lifecycle', 'modules/lifecycle/routes/rot.js', 'get', '/inbox/rotting'),
+    ],
+  });
+  assert.equal(out.ok, false);
+  assert.equal(out.hardFail, true);
+  assert.equal(out.violations.length, 1);
+  assert.match(out.violations[0], /\/inbox\/rotting/);
+  assert.match(out.violations[0], /never reaches its handler/);
+  assert.match(out.violations[0], /\\d\+/, 'points at constraining the param');
+});
+
+// --- WHAT THE FIX DOES -----------------------------------------------------
+
+test('a CONSTRAINED param shadows nothing — this is what the fix relies on', () => {
+  const pairs = findShadowPairs([
+    r('ideas', 'modules/ideas/routes/inbox.js', 'get', '/inbox/:id(\\d+)'),
+    r('lifecycle', 'modules/lifecycle/routes/rot.js', 'get', '/inbox/rotting'),
+  ]);
+  assert.deepEqual(pairs, []);
+});
+
+test('order matters: a literal mounted BEFORE the param is fine', () => {
+  const pairs = findShadowPairs([
+    r('ideas', 'modules/ideas/routes/inbox.js', 'get', '/inbox/awaiting-nod'),
+    r('ideas', 'modules/ideas/routes/inbox.js', 'get', '/inbox/:id'),
+  ]);
+  assert.deepEqual(pairs, [], 'declaring literals first is the in-file convention and stays legal');
+});
+
+// --- WHAT MUST NOT BE FLAGGED ---------------------------------------------
+
+test('different methods never compete', () => {
+  assert.deepEqual(findShadowPairs([
+    r('a', 'a.js', 'get', '/inbox/:id'),
+    r('b', 'b.js', 'patch', '/inbox/rotting'),
+  ]), []);
+});
+
+test('different depths never compete', () => {
+  assert.deepEqual(findShadowPairs([
+    r('a', 'a.js', 'get', '/inbox/:id'),
+    r('b', 'b.js', 'get', '/inbox/rotting/detail'),
+  ]), []);
+});
+
+test('two params at the same position are one shape, not a shadow', () => {
+  assert.deepEqual(findShadowPairs([
+    r('a', 'a.js', 'get', '/inbox/:id'),
+    r('b', 'b.js', 'get', '/inbox/:ideaId'),
+  ]), []);
+});
+
+test('a differing earlier literal segment means the routes never overlap', () => {
+  assert.deepEqual(findShadowPairs([
+    r('a', 'a.js', 'get', '/inbox/:id'),
+    r('b', 'b.js', 'get', '/blockers/rotting'),
+  ]), []);
+});
+
+test('the param must sit WHERE the literal is', () => {
+  assert.deepEqual(findShadowPairs([
+    r('a', 'a.js', 'get', '/tasks/:id/water'),
+    r('b', 'b.js', 'get', '/tasks/rotting/water'),
+  ]).length, 1, 'same position, so it does shadow');
+  assert.deepEqual(findShadowPairs([
+    r('a', 'a.js', 'get', '/tasks/:id/water'),
+    r('b', 'b.js', 'get', '/tasks/:id/rotting'),
+  ]), [], 'literal in a position the param does not occupy');
+});
+
+// --- SEGMENT CLASSIFIERS ---------------------------------------------------
+
+test('bare vs constrained param', () => {
+  assert.equal(isBareParam(':id'), true);
+  assert.equal(isBareParam(':id(\\d+)'), false);
+  assert.equal(isBareParam('rotting'), false);
+  assert.equal(isConstrainedParam(':id(\\d+)'), true);
+  assert.equal(isConstrainedParam(':id'), false);
+});
+
+// --- SCAN INTEGRITY --------------------------------------------------------
+
+test('an empty enumeration is a scan DEFECT, never a clean pass', () => {
+  const out = checkNoRouteShadowing({ sequence: [] });
+  assert.equal(out.ok, false);
+  assert.equal(out.hardFail, true);
+  assert.match(out.violations[0], /scan defect/);
+});
+
+// --- THE LIVE TREE ---------------------------------------------------------
+
+test('the real repo enumerates routes and has no shadowing pair', () => {
+  const seq = mountSequence();
+  assert.ok(seq.length > 100, `expected a real mount sequence, got ${seq.length}`);
+  const out = checkNoRouteShadowing();
+  assert.equal(out.hardFail, false, `live tree has shadowing pairs:\n${out.violations.join('\n')}`);
+});
+
+test('the live tree still declares the rot feed and the constrained idea read', () => {
+  const seq = mountSequence();
+  const rot = seq.find((x) => x.route === '/inbox/rotting' && x.method === 'get');
+  assert.ok(rot, 'GET /inbox/rotting must still be declared');
+  const idea = seq.find((x) => x.route.startsWith('/inbox/:id') && x.method === 'get');
+  assert.ok(idea, 'GET /inbox/:id must still be declared');
+  assert.ok(isConstrainedParam(idea.route.split('/').filter(Boolean)[1]),
+    `GET ${idea.route} must constrain its id, or it eats /inbox/rotting again`);
+});
+
+// --- THE BEHAVIOUR THE FIX DEPENDS ON -------------------------------------
+//
+// The static guard above proves the DECLARATION is constrained. This proves the
+// constraint actually routes that way in the Express version we ship — and it is
+// not a formality: Express 5 REMOVED inline param regexes, so an upgrade would
+// silently turn `:id(\d+)` back into a path that eats /inbox/rotting, with the
+// static check still passing because the declaration text is unchanged. This is
+// the test that goes red on that upgrade.
+
+async function behaviour() {
+  const express = require('express');
+  const http = require('node:http');
+  const app = express();
+
+  // Mounted in the SAME order the real loader mounts them: `ideas` (the param
+  // route) before `lifecycle` (the literal).
+  const ideas = express.Router();
+  ideas.get('/inbox/:id(\\d+)', (req, res) => res.json({ handler: 'idea', id: req.params.id }));
+  const lifecycle = express.Router();
+  lifecycle.get('/inbox/rotting', (_req, res) => res.json({ handler: 'rot' }));
+  app.use(ideas);
+  app.use(lifecycle);
+
+  const server = http.createServer(app);
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  try {
+    const rot = await fetch(`${base}/inbox/rotting`);
+    const rotBody = await rot.json();
+    test('GET /inbox/rotting reaches the ROT handler despite being mounted second', () => {
+      assert.equal(rot.status, 200);
+      assert.equal(rotBody.handler, 'rot');
+    });
+
+    const idea = await fetch(`${base}/inbox/1234`);
+    const ideaBody = await idea.json();
+    test('a numeric id still reaches the idea handler', () => {
+      assert.equal(idea.status, 200);
+      assert.equal(ideaBody.handler, 'idea');
+      assert.equal(ideaBody.id, '1234');
+    });
+
+    const junk = await fetch(`${base}/inbox/not-a-number`);
+    test('an unmatched non-numeric segment 404s instead of 400 — the accepted trade-off', () => {
+      assert.equal(junk.status, 404);
+    });
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+}
+
+await behaviour();
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);