@bongos/core 1.19.625 → 1.19.627

package/modules/lifecycle/db-tasks.js

@@ -23,6 +23,31 @@ const { deriveRequiredRank, highestRank } = require('./db-rank-authz.js');
 // -------------------------------------------------------------------------
 
 
+// goalScopeProtected — does this task's owning goal reach protected territory
+// (the permission / ship-grade / deploy / migration core)? The touches-free half
+// of the create-time rank floor (task 1003663, ADR 0270).
+//
+// It reads the goal's `scope_modules` wall through the SAME published primitive
+// modules/ideas/inbox.js already uses for routed filings (task 1003066, BV1.R05)
+// and that the pre-push hook, the grader and main-audit read — so this floor
+// cannot drift from the roster they enforce.
+//
+// Runs on the CALLER'S client when there is one, so it sees the same
+// transaction snapshot as the INSERT it feeds — a goal rescoped mid-transaction
+// cannot land between the check and the row. FAILS CLOSED-ish by omission: an
+// absent goal or a non-array wall yields false, which is the honest answer
+// ("no protected scope declared"), and the other three arms of deriveRequiredRank
+// still apply.
+async function goalScopeProtected(goalId, client) {
+  if (goalId == null) return false;
+  const { rows } = await (client || pool).query(
+    'SELECT scope_modules FROM goals WHERE id = $1',
+    [goalId]
+  );
+  const scope = rows.length ? rows[0].scope_modules : null;
+  return Array.isArray(scope) && api.moduleScopeMap.scopeIncludesProtected(scope);
+}
+
 // The version statuses that can still receive new work. 'shipped' and 'frozen' are
 // closed: a version whose scope is sealed cannot be told about a bug found afterwards.
 // Mirrors the CHECK constraint on versions.status (migrations/003_pms.sql).
@@ -124,15 +149,6 @@ async function createTask({
   // to name a goal instead.
   allowCatchAll = false,
 }, deps = {}) { // deps.client enlists this INSERT in the CALLER'S transaction (task 1003065, BV1.R01); the argument for it is at modules/ideas/inbox.js routeIdeaToGoal
-  // task 1498 / ADR 0085: every task carries a deliberate rank floor. Derive it
-  // from touches + sensitivity, then let an explicit requiresRank override only
-  // UPWARD (highestRank) — a requested rank below the derived floor is clamped
-  // up to the floor (fail-closed; the floor mirrors the trust-boundary paths a
-  // sub-Metic builder cannot push to anyway).
-  const requiresRankEffective = highestRank(
-    deriveRequiredRank(touches, securitySensitive),
-    requiresRank ?? 'xenos'
-  );
   // task 1677 / ADR 0096 (2026-06-28): creation is now the PRIMARY reward-assignment
   // point — every task is born with a fair drachmae value, not just at promote/claim.
   // When the caller supplies NO positive credits_reward (null/undefined/0), auto-assign
@@ -181,6 +197,26 @@ async function createTask({
     }
     goalIdEffective = await generalGoalIdForVersion(versionId);
   }
+  // task 1498 / ADR 0084: every task carries a deliberate rank floor. Derive it,
+  // then let an explicit requiresRank override only UPWARD (highestRank) — a
+  // requested rank below the derived floor is clamped up to the floor
+  // (fail-closed; the floor mirrors the trust-boundary paths a sub-Metic builder
+  // cannot push to anyway).
+  //
+  // task 1003663 / ADR 0270: derived HERE, at the lowest create layer and AFTER
+  // goalIdEffective resolves, rather than in each route — the same argument the
+  // reward auto-assignment above makes. Every create vector (POST /tasks,
+  // POST /goals/:id/tasks, idea-promotion, capture, newcomer-restock, copy-desk,
+  // kickoff-seed, seed scripts) inherits the floor, and a vector added next year
+  // cannot forget it. Patching the two authoring routes instead is how
+  // POST /tasks and POST /goals/:id/tasks came to disagree in the first place.
+  const requiresRankEffective = highestRank(
+    deriveRequiredRank(touches, securitySensitive, {
+      needsMigration,
+      scopeProtected: await goalScopeProtected(goalIdEffective, deps.client),
+    }),
+    requiresRank ?? 'xenos'
+  );
   const { rows } = await (deps.client || pool).query(
     `INSERT INTO tasks (version_id, title, description, status, touches,
                         est_minutes, est_cost_usd, manual_degree, priority,
@@ -366,7 +402,7 @@ async function updateTaskNewcomerFriendly(id, newcomerFriendly) { return updateT
 // (the === true coercion below preserves the boolean-only contract).
 
 async function updateTaskSecuritySensitive(id, securitySensitive) {
-  // task 1498 / ADR 0085: flagging a task security_sensitive RAISES its rank
+  // task 1498 / ADR 0084: flagging a task security_sensitive RAISES its rank
   // floor (a now-sensitive task must require Metic+). Recompute and ratchet
   // requires_rank UP in the same atomic UPDATE so the two columns can't diverge;
   // never lower it (an existing 'metic'/'archon' may be a protected-touch floor
@@ -386,7 +422,7 @@ async function updateTaskSecuritySensitive(id, securitySensitive) {
   return rows[0] ?? null;
 }
 
-// task 1498 / ADR 0085: set a task's rank floor explicitly (the Archon override).
+// task 1498 / ADR 0084: set a task's rank floor explicitly (the Archon override).
 // The DERIVED floor (touches + security_sensitive) is a HARD minimum — a request
 // below it is clamped UP via highestRank, so an override can only RAISE the bar,
 // never open a sensitive task to a lower rank. `requiresRank` is one live rank
@@ -396,7 +432,15 @@ async function updateTaskSecuritySensitive(id, securitySensitive) {
 async function updateTaskRequiresRank(id, requiresRank) {
   const task = await getTask(id);
   if (!task) return null;
-  const floor = deriveRequiredRank(task.touches, task.security_sensitive);
+  // task 1003663 / ADR 0270: the override re-derives with the SAME four inputs as
+  // creation. Without needsMigration/scopeProtected here, an Archon setting a
+  // migration task to 'xenos' would succeed — the floor would compute 'xenos'
+  // from an empty touches[] and clamp nothing, silently undoing the create-time
+  // protection. An override may still only RAISE.
+  const floor = deriveRequiredRank(task.touches, task.security_sensitive, {
+    needsMigration: task.needs_migration === true,
+    scopeProtected: await goalScopeProtected(task.goal_id, null),
+  });
   const effective = highestRank(floor, requiresRank ?? 'xenos');
   const { rows } = await pool.query(
     `UPDATE tasks SET requires_rank = $1, updated_at = now() WHERE id = $2 RETURNING *`,
@@ -508,7 +552,32 @@ async function updateTaskAutomationTag(id, automationTag) { return updateTaskCol
 // task 1002648: correct the create-time migration heuristic's verdict — a false
 // flag makes claiming reserve a migration number that goes unused (task 1002614
 // burned 213 that way). Boolean only; the route validates.
-async function updateTaskNeedsMigration(id, needsMigration) { return updateTaskColumn(id, 'needs_migration', needsMigration === true); }
+//
+// task 1003663 / ADR 0270: needs_migration is now a rank-floor INPUT, so this
+// stopped being a bare column write and became the exact sibling of
+// updateTaskSecuritySensitive above — same CASE, same ratchet, same reasoning.
+// The correction this setter exists for runs BOTH ways: task 1002648 names the
+// true→false direction, but false→true is the one that matters here, and without
+// the ratchet a Metic could PATCH needs_migration onto an existing xenos task and
+// leave the floor at xenos — reopening on the PATCH path exactly the gap ADR 0270
+// closes on the create path. RAISES ONLY: flipping the flag back off never drops
+// the gate, because an existing 'metic'/'archon' may be a protected-scope floor or
+// a deliberate override. An Archon lowers it explicitly via updateTaskRequiresRank,
+// which re-derives from all four inputs.
+async function updateTaskNeedsMigration(id, needsMigration) {
+  const mig = needsMigration === true;
+  const { rows } = await pool.query(
+    `UPDATE tasks
+        SET needs_migration = $1,
+            requires_rank = CASE WHEN $1 AND requires_rank IN ('xenos', 'thetes')
+                                 THEN 'metic' ELSE requires_rank END,
+            updated_at = now()
+      WHERE id = $2
+      RETURNING *`,
+    [mig, id]
+  );
+  return rows[0] ?? null;
+}
 
 // BV1.R53 (task 1422): assign (or clear) the module_key that declares which
 // module this task's work belongs to. Drives module-disjointness at claim time

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.625",
+  "version": "1.19.627",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.625",
+      "version": "1.19.627",
       "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.627",
   "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.627'; // 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 ---------------