@bongos/core 1.19.635 → 1.19.636

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.635",
-  "core_contract": "1.19.635",
-  "source_commit": "c97f3015861c4ca09d2c5a07f78ab33284d7c26c",
+  "core_version": "1.19.636",
+  "core_contract": "1.19.636",
+  "source_commit": "7e7d5caa1a0c5ff310bdab82a7679fd56e2f71d7",
   "source_ref": "HEAD",
-  "built_at": "2026-09-10T02:33:59.187Z",
+  "built_at": "2026-09-10T03:45:41.270Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 468,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2099,
+    "functional_verbatim": 2100,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2591,
-  "tree_sha256": "c5c9267a793145efe19a63442cfbe05ee6cf03d5c6ff363084857bf151aec4cc",
+  "file_count": 2592,
+  "tree_sha256": "abf5929f41b5c8b538294d87d01632069ad0371e2e2eed440b97a9727a33d426",
   "files": [
     {
       "path": ".claude/skills/backlog-review/SKILL.md",
@@ -2777,7 +2777,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "baa05168e88c98e3fc35c1bf652bd85ef90dcfb463408c68e5132910316f8c34"
+      "sha256": "74c46d5efae11f3adc3f0cb79bec6757e0f7bb820e7f77c1f66cd6fc083a503c"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7707,12 +7707,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "f40ca54ae7693ccd7a41bb2429fa61f71b147f0aabc821535e4ca6e9055d9f49"
+      "sha256": "7e8bd5c903c8f50fa7bcc80c7e317a4ea202bf079e0e63a8beafc988718953e1"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "1d7c9b3ad4172d3702cd4baa6fd5f30d1c26bedcfdcea6e8c2532d0decb9814e"
+      "sha256": "0e2c886ce78f829a2b694c3c49af7fafff6297695da0ddb346d7c0936fe95ff8"
     },
     {
       "path": "public-docs/index.html",
@@ -8144,6 +8144,11 @@
       "mode": "0000644",
       "sha256": "a34da5bd47c0410db31344ae042bae318e6daf0e774672999f14213c3c1180c5"
     },
+    {
+      "path": "scripts/gds/fitness-checks-route-pins.js",
+      "mode": "0000644",
+      "sha256": "4bd0d9c3b39a6f8af4561925835ebf9b349170be36aef926c6af2160af0d1ab5"
+    },
     {
       "path": "scripts/gds/fitness-checks-vocabulary.js",
       "mode": "0000644",
@@ -8167,7 +8172,7 @@
     {
       "path": "scripts/gds/fitness.js",
       "mode": "0000644",
-      "sha256": "cd9f61f69ef8d017a39bed129e41a3d3944cf53bfaf6ff26eb868e46611b6dc3"
+      "sha256": "610d76cee575fa1a87f2ff7bb84f5576f3c4a8cf2e727e6c372d76ebf9a0a340"
     },
     {
       "path": "scripts/gds/gate-review.js",
@@ -9312,7 +9317,7 @@
     {
       "path": "src/bongos/route-rank-check.js",
       "mode": "0000644",
-      "sha256": "514f9bb73cc74a2574272b733e0314dfe3b372497874bd7c88b763f22ddab64e"
+      "sha256": "f57293c2d157949ccb5a74511f167902adf096037b4830b0bf667a38baf6ab58"
     },
     {
       "path": "src/bongos/routes.js",
@@ -9452,7 +9457,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "79ef2ff7f2ac145450cc27389e4da2edd8079f2887ba7240c057e0e8cb8bb198"
+      "sha256": "4c4fcf6a9833c72d6c371208d00afc60eba49cd07e5a0c9b4cd384133089340d"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10482,7 +10487,7 @@
     {
       "path": "tests/fitness.mjs",
       "mode": "0000644",
-      "sha256": "5e5b53d5a1dce6b7ffacbea7198375aac6f77259ee948c00c24eb157f62a034d"
+      "sha256": "2208a1e4d3df3ce712c4e4dbc7908d20520833375a2c07c3da5d37252dd56b7a"
     },
     {
       "path": "tests/fitness_gds_ratchet.mjs",
@@ -12202,7 +12207,7 @@
     {
       "path": "tests/route_rank_check.mjs",
       "mode": "0000644",
-      "sha256": "9fd3762c6b171ee39b0cee336de2d41547795b2cd4898b178325cfdd321cf28a"
+      "sha256": "755f2c2c1cd929f0a4449ceb1c4bd0ac719aadf64c56484e03b4bed57e6daf7c"
     },
     {
       "path": "tests/route_shadow_guard.mjs",

package/docs/module-api-changelog.md

@@ -1719,5 +1719,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.633 with no explicit bump. run 34429621784. (task 1002620)
   1.19.635 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.634 with no explicit bump. run 34429906252. (task 1002620)
+  1.19.636 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.635 with no explicit bump. run 34434517065. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.635",
+  "version": "1.19.636",
   "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-checks-route-pins.js

@@ -0,0 +1,76 @@
+// scripts/gds/fitness-checks-route-pins.js — Check 4b (task 1003192): every
+// MODULE_EXPECTED_RANKS key names a real module directory.
+//
+// Carved out of scripts/gds/fitness.js on the task-1003206 precedent (the R03
+// de-monolith plan): that file sits against the 1,500-line ratchet with two lines
+// of headroom, so a new check lands here rather than tipping it over. fitness.js
+// imports the name straight back, so the CHECKS registry and the module's public
+// surface — which the tests read heavily — are unchanged.
+//
+// WHY THE CHECK EXISTS. src/bongos/route-rank-check.js pins the expected rank of
+// each privileged module route, but pin SCOPE derives from successfully-classified
+// routes: a MODULE_EXPECTED_RANKS key matching no discovered module is dropped and
+// its pins pass VACUOUSLY, while the loader keeps mounting modules/<key>/routes/ in
+// production by the same convention the scan discovers them by. Measured on the real
+// classifier: with modules/security/ renamed, all six security pins went inert and a
+// POST /security/reports downgraded to any-builder drew zero findings — a pinned
+// privileged WRITE route silently unguarded.
+//
+// THIS IS THE SOURCE-REPO HALF of a two-layer guard. checkRouteRanks fires when a
+// module directory is PRESENT but contributed no route (a rename/move under a live
+// module); it deliberately stays silent on a wholly absent directory, because it runs
+// on every ship and an instance may legitimately omit an optional module. Here every
+// module is expected to exist, so a whole-directory rename or a typo'd key — neither
+// of which the other layer can see — hard-fails. The governance→government rename had
+// to hand-carry double-keyed pins precisely because nothing mechanical caught this.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { REPO_ROOT } = require('./fitness-lib.js');
+const { checkRouteRanks, MODULE_EXPECTED_RANKS } = require('../../src/bongos/route-rank-check');
+
+// ============================================================================
+// Check 4 — no route bypasses server-side rank checks (ADR 0016)  [reuses route-rank-check]
+// ============================================================================
+// Moved here with Check 4b (task 1003192): the two are the same subject — Check 4 asks
+// whether each route carries a gate, 4b whether the pins that assert those gates are
+// actually in scope — and keeping them together is what buys fitness.js headroom against
+// the 1,500-line ratchet instead of leaving it sitting exactly on the cap.
+function checkRankGuards() {
+  const r = checkRouteRanks();
+  // hardFail = an ungated WRITE route or a downgraded privileged route. Unclassified read routes
+  // are 'concerns' (the Hacker adjudicates intent) — surfaced as warnings, not a hard failure.
+  const violations = r.findings.filter((f) => f.severity === 'blocker').map((f) => `${f.route} (${f.file}) — ${f.summary}`);
+  const warnings = r.findings.filter((f) => f.severity !== 'blocker').map((f) => `${f.route} (${f.file}) — ${f.summary}`);
+  return { name: 'route rank guards (ADR 0016)', ok: !r.hardFail, hardFail: r.hardFail, violations, warnings, note: `${r.routeCount} routes classify to a known rank; no ungated writes, no privileged downgrades.` };
+}
+
+// ============================================================================
+// Check 4b — module rank-pin keys resolve to a real modules/<key>/ dir
+// ============================================================================
+function checkModulePinKeysResolve() {
+  const violations = [];
+  for (const key of Object.keys(MODULE_EXPECTED_RANKS)) {
+    if (!fs.existsSync(path.join(REPO_ROOT, 'modules', key))) {
+      violations.push(`MODULE_EXPECTED_RANKS.${key} names no modules/${key}/ directory — its `
+        + `${Object.keys(MODULE_EXPECTED_RANKS[key]).length} rank pin(s) are INERT and pass vacuously `
+        + '(src/bongos/route-rank-check.js). Rename the key to the module\'s current directory, or drop the entry.');
+    }
+  }
+  return {
+    name: 'module rank-pin keys resolve (task 1003192)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${Object.keys(MODULE_EXPECTED_RANKS).length} module pin blocks all name a live modules/<key>/ directory.`,
+  };
+}
+
+module.exports = {
+  checkRankGuards,
+  checkModulePinKeysResolve,
+};

package/scripts/gds/fitness.js

@@ -23,7 +23,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
-const { checkRouteRanks } = require('../../src/bongos/route-rank-check');
+const { checkRankGuards, checkModulePinKeysResolve } = require('./fitness-checks-route-pins.js'); // Checks 4 + 4b — carved out by task 1003192 (the 1,500-line ratchet)
 const genApiDocs = require('./gen-api-docs'); // R12 (#1999): reuse the route model (readsBody/validated) that drives the OpenAPI spec
 const { parseRoutineFrontmatter } = require('./run-routine'); // System 4 (ADR 0078): deterministic-routine boundary
 const { filenameViolation, stemCollisions, CORE_NS, INSTANCE_NS } = require('./migration-namespace'); // ADR 0108 §5: cross-repo migration namespacing
@@ -151,18 +151,6 @@ function checkNestedDocsPresent() {
   return { name: 'nested CLAUDE.md presence', ok: violations.length === 0, hardFail: violations.length > 0, violations, warnings: [], note: `present for: ${HIGH_TRAFFIC.join(', ')}.` };
 }
 
-// ============================================================================
-// Check 4 — no route bypasses server-side rank checks (ADR 0016)  [reuses route-rank-check]
-// ============================================================================
-function checkRankGuards() {
-  const r = checkRouteRanks();
-  // hardFail = an ungated WRITE route or a downgraded privileged route. Unclassified read routes
-  // are 'concerns' (the Hacker adjudicates intent) — surfaced as warnings, not a hard failure.
-  const violations = r.findings.filter((f) => f.severity === 'blocker').map((f) => `${f.route} (${f.file}) — ${f.summary}`);
-  const warnings = r.findings.filter((f) => f.severity !== 'blocker').map((f) => `${f.route} (${f.file}) — ${f.summary}`);
-  return { name: 'route rank guards (ADR 0016)', ok: !r.hardFail, hardFail: r.hardFail, violations, warnings, note: `${r.routeCount} routes classify to a known rank; no ungated writes, no privileged downgrades.` };
-}
-
 // ============================================================================
 // Check 5 — generated artifacts are fresh (Path C enforces Path B; ADR 0063 + ADR 0062 §8)
 // ============================================================================
@@ -1357,6 +1345,7 @@ const CHECKS = [
   checkSkillFrontmatter,
   checkNestedDocsPresent,
   checkRankGuards,
+  checkModulePinKeysResolve,
   checkGeneratedArtifactsFresh,
   checkDeterministicRoutines,
   checkCoreNeverImportsModule,
@@ -1443,6 +1432,7 @@ module.exports = {
   checkClaudeMdBudget,
   checkNestedDocsPresent,
   checkRankGuards,
+  checkModulePinKeysResolve,
   checkGeneratedArtifactsFresh,
   checkDeterministicRoutines,
   checkCoreNeverImportsModule,

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

@@ -934,8 +934,34 @@ function checkRouteRanks({ routesDir = ROUTES_DIR, modulesDir } = {}) {
     if (mm) scopedModules.add(mm[1]);
   }
   const effectivePins = { ...EXPECTED_RANKS };
+  // task 1003192: the skip above is SILENT — a key matching no discovered module is
+  // dropped with no else branch, so its pins pass vacuously while the routes they
+  // guard stay live (the loader mounts modules/<key>/routes/ by the same convention
+  // this scan discovers them by). Probed: with modules/security/ renamed, all six
+  // security pins go inert and a POST /security/reports deliberately downgraded to
+  // any-builder draws ZERO findings. The governance→government rename had to
+  // hand-carry double-keyed pins precisely because nothing mechanical catches this.
+  //
+  // Fire only when the module DIRECTORY IS PRESENT but contributed no route: that is
+  // unambiguously a rename/move UNDER a live module, never a legitimately-absent
+  // optional one. A wholly-missing directory stays silent here on purpose — an
+  // instance may ship without an optional module, and this runs on every ship — so
+  // that half is caught at the SOURCE repo by fitness.js Check 4b, where every
+  // module is expected to exist. The two layers are complementary, not redundant.
   for (const [mod, pins] of Object.entries(MODULE_EXPECTED_RANKS)) {
-    if (scopedModules.has(mod)) Object.assign(effectivePins, pins);
+    if (scopedModules.has(mod)) { Object.assign(effectivePins, pins); continue; }
+    if (!fs.existsSync(path.join(modulesDir, mod))) continue; // optional module absent — legitimate
+    findings.push({
+      severity: 'major',
+      file: `modules/${mod}/`,
+      route: `(MODULE_EXPECTED_RANKS.${mod})`,
+      method: '(pins)',
+      rank: '(inert)',
+      summary: `modules/${mod}/ exists but contributed NO route to this scan, so its `
+        + `${Object.keys(pins).length} rank pin(s) were skipped and passed vacuously. `
+        + 'The routes may still be mounted in production while nothing verifies their rank. '
+        + `Point the pins at the module's current route location, or drop the ${mod} entry if the module no longer serves routes.`,
+    });
   }
   for (const [key, expected] of Object.entries(effectivePins)) {
     const r = byKey.get(key);

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.635'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.636'; // 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/fitness.mjs

@@ -68,6 +68,17 @@ test('no route bypasses server-side rank checks (ADR 0016)', () => {
   assert.equal(r.hardFail, false, r.violations.join('\n'));
 });
 
+// task 1003192 — the source-repo half of the inert-pin guard. checkRouteRanks catches a
+// pinned module whose dir is present but yields no route; it stays silent on a wholly
+// absent dir because it runs on every ship and an instance may omit an optional module.
+// Here every module is expected to exist, so a whole-dir rename or a typo'd key — which
+// would park a block of rank pins vacuously while the routes stay mounted — must red.
+test('every MODULE_EXPECTED_RANKS key names a real module dir (task 1003192)', () => {
+  const r = fitness.checkModulePinKeysResolve();
+  assert.equal(r.hardFail, false, r.violations.join('\n'));
+  assert.equal(r.ok, true);
+});
+
 test('generated repo map is fresh (Path C enforces Path B)', () => {
   const r = fitness.checkGeneratedArtifactsFresh();
   assert.equal(r.hardFail, false, r.violations.join('\n'));

package/tests/route_rank_check.mjs

@@ -487,6 +487,56 @@ test('EXPECTED_RANKS: a MISSING pinned route trips a blocker (a protected route
   assert.equal(res.hardFail, true);
 });
 
+// ---------- task 1003192: a module pin block must never go SILENTLY inert ----------
+//
+// From the task-1002671 adversarial verification (finding 4). Pin scope derives from
+// successfully-classified routes, and the skip had no else branch: a MODULE_EXPECTED_RANKS
+// key matching no discovered module was dropped without a word, while the loader kept
+// mounting modules/<key>/routes/ by the same convention this scan discovers them by.
+// Measured before the fix, with the security module's directory renamed: all six pins went
+// inert and a POST /security/reports deliberately downgraded to any-builder drew ZERO
+// findings — a pinned privileged WRITE route silently unguarded.
+//
+// The guard is deliberately split. checkRouteRanks fires only when the directory IS
+// PRESENT but contributed no route (a rename/move under a live module); a wholly-absent
+// directory stays silent here because this runs on every ship and an instance may
+// legitimately omit an optional module. fitness.js Check 4b owns that half, at the source
+// repo where every module is expected to exist — see tests/fitness.mjs.
+
+test('a module whose dir EXISTS but yields no route surfaces an inert-pins finding [task 1003192]', () => {
+  const os = require('node:os');
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rrc-inert-'));
+  // modules/security/ is present, but its routes live under handlers/ — so the scan
+  // discovers nothing for the key and all six security pins would be skipped.
+  fs.mkdirSync(path.join(dir, 'security', 'handlers'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'security', 'handlers', 'reports.js'),
+    `router.post('/security/reports', auth.requireBuilder, h);\n`);
+  const res = rrc.checkRouteRanks({ modulesDir: dir });
+  fs.rmSync(dir, { recursive: true, force: true });
+
+  const inert = res.findings.find((f) => f.rank === '(inert)');
+  assert.ok(inert, `a present-but-routeless pinned module must surface a finding; got: ${res.findings.map((f) => f.route).join(', ')}`);
+  assert.equal(inert.severity, 'major');
+  assert.match(inert.route, /security/);
+  assert.match(inert.summary, /passed vacuously/);
+});
+
+test('an ABSENT optional module stays silent — no false alarm for an instance without it [task 1003192]', () => {
+  // The counter-test, and the reason the guard is split across two layers: this runs on
+  // every ship, so a module an instance legitimately does not ship must not red the board.
+  const os = require('node:os');
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rrc-absent-'));
+  // An empty modules dir: no pinned module directory exists at all.
+  const res = rrc.checkRouteRanks({ modulesDir: dir });
+  fs.rmSync(dir, { recursive: true, force: true });
+  assert.equal(res.findings.filter((f) => f.rank === '(inert)').length, 0,
+    'a module directory that is simply absent must not raise an inert-pins finding');
+});
+
 // ---------- LIVE: every real route classifies to a known rank ----------
 
 test('LIVE: checkRouteRanks() on src/bongos/routes/ has zero unknowns', () => {