@bongos/core 1.19.648 → 1.19.649

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.648",
-  "core_contract": "1.19.648",
-  "source_commit": "0606a231569b44bdc2521fcee567031ea8ea6f08",
+  "core_version": "1.19.649",
+  "core_contract": "1.19.649",
+  "source_commit": "10ae5631783d03386a93457958ac7846e3ad4b83",
   "source_ref": "HEAD",
-  "built_at": "2026-09-10T19:06:50.891Z",
+  "built_at": "2026-09-10T19:54:28.577Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 470,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2603,
-  "tree_sha256": "3260c3c3da2ae8a6b6630824444ada3145268a70b9194585231bb3391392db80",
+  "tree_sha256": "05f4d97454a0e6f6d8eadf6c13d88c68d8619b32269b20409e5a79505dad4596",
   "files": [
     {
       "path": ".claude/skills/backlog-review/SKILL.md",
@@ -2772,7 +2772,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "f646af7c4521017e44e5dfef0b160c18907bfa0f07b5986603593485a34f2742"
+      "sha256": "454e5258c7dccd1013445f290acf0cfbd0cf396c9cb5bbcf8a08b911770bfa07"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7727,12 +7727,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "83135ce62c34647b4bc57872526cb9f550a9fef2148c585839d57c600763961b"
+      "sha256": "356482b30a64a35a5ae0a670d0b26e0b10dcdd71ae106e8b22fb8f5843282c05"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "a9a2455f79599041389b23a18607666ce74eba9be0199d21fbc62553824463f6"
+      "sha256": "30e3bed231acb41d36332cae243423aee74a09604e87c966908543fefde74b65"
     },
     {
       "path": "public-docs/index.html",
@@ -9487,7 +9487,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "dadc321fdd8e6a6f856bb9260c555284b9859361c556d47b14b25df45db900b0"
+      "sha256": "eaa8edfbeec057365723ebfc9d148061b96be50cc37a1ad51b7d050f6e2906c4"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9497,7 +9497,7 @@
     {
       "path": "src/module-loader/loader.js",
       "mode": "0000644",
-      "sha256": "7c03edea5abee5cce4dfb2f22626e15ee2257ba44f6024e0bf74ff35e8ed0f42"
+      "sha256": "5e417760b49f19d48af3dbd72a90edb53b6a9710ce54ca33052f4fbe86cb9229"
     },
     {
       "path": "src/module-loader/manifest-schema.js",
@@ -9517,7 +9517,7 @@
     {
       "path": "src/module-seams.js",
       "mode": "0000644",
-      "sha256": "60cdc1e4ffb22a843a1581909e742b9672fca776bfe5716e72aab77c63df6099"
+      "sha256": "34378efdff13b7e44e38f248026aa927073e0c0c15db670cabaea7aa939c4959"
     },
     {
       "path": "src/modules.js",
@@ -11632,7 +11632,7 @@
     {
       "path": "tests/module_loader.mjs",
       "mode": "0000644",
-      "sha256": "24aed55c34771eb1bdaec9a51b1e818549298455d50a9ade96db3cc1f06c034b"
+      "sha256": "5d09d5ccedf777c55509dc98365b46c443848c854158ace66fa17c99ba538737"
     },
     {
       "path": "tests/module_manifest.mjs",
@@ -11827,7 +11827,7 @@
     {
       "path": "tests/platform_boot.mjs",
       "mode": "0000644",
-      "sha256": "fb28eed2a6933805d2af7dc0f8d8e966f921c6556683e1f22b440c2f4a32760d"
+      "sha256": "02a3d4540ddecfe530022df0c6cab4f48258b78efd44224c097622e45b8cc0d5"
     },
     {
       "path": "tests/platform_visibility_gate.mjs",

package/docs/module-api-changelog.md

@@ -1745,5 +1745,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.646 with no explicit bump. run 34515733973. (task 1002620)
   1.19.648 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.647 with no explicit bump. run 34518387614. (task 1002620)
+  1.19.649 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.648 with no explicit bump. run 34523111338. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.648",
+  "version": "1.19.649",
   "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/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // 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.648'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.649'; // 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/src/module-loader/loader.js

@@ -20,6 +20,10 @@ const path = require('node:path');
 const { validateManifest } = require('./manifest-schema');
 const { satisfies } = require('./semver');
 const { resolveCoreRoot, resolveInstanceRoot } = require('../instance-config');
+// Required DIRECTLY, never through src/module-api.js: the doorway pulls in auth
+// and would re-form the eval-time cycle coreVersion() exists to avoid.
+// src/module-seams.js is pure (it requires nothing), so this is cycle-safe.
+const { verifyPortsSatisfied } = require('../module-seams');
 
 // Collapse roots that resolve to the SAME absolute path, preserving order.
 // Normalizes via path.resolve so a cwd that arrives with a trailing '.'/'//'
@@ -129,6 +133,39 @@ function discoveredRegistry(opts) {
   return out;
 }
 
+// The ENABLED slice of the discovered set, in discovery order. The one place the
+// `isEnabled` gate is spelled out, so verification and mounting can never disagree
+// about which modules are in play.
+function enabledModules({ isEnabled } = {}, opts) {
+  return discovered(opts).loaded.filter(({ key }) => typeof isEnabled !== 'function' || isEnabled(key));
+}
+
+// BOOT-TIME seam verification (BV1.R41), run over the ENABLED manifests before a
+// single module router is mounted. THROWS on an unsatisfiable set — a module that
+// consumes a port no enabled module provides, or a port claimed by two of them.
+//
+// Why it throws rather than warns: without it the failure surfaces as resolve()'s
+// runtime throw the first time the seam is used — an arbitrarily long time after
+// boot, on a request path, in a process that reported healthy. ADR 0150's "fail
+// loud, never boot half-wired" is the same argument: refuse at boot, name the
+// module and the port, and let the operator fix the module set.
+//
+// Only the ENABLED set is checked, deliberately. A disabled module's `consumes` is
+// not a wiring error — it is a module that isn't there.
+function verifyEnabledPorts(enabled) {
+  const { ok, errors } = verifyPortsSatisfied(enabled.map(({ key, manifest }) => ({
+    key,
+    provides: manifest.provides || [],
+    consumes: manifest.consumes || [],
+  })));
+  if (ok) return;
+  throw new Error([
+    '[module-loader] unsatisfiable module wiring — refusing to boot half-wired:',
+    ...errors.map((e) => `  - ${e}`),
+    'Fix the enabled module set (config/modules.json, or a <PREFIX>_MODULE_<KEY> env override) so every consumed port has exactly one provider.',
+  ].join('\n'));
+}
+
 // Mount each discovered + ENABLED module's route factories onto `router`. A
 // module declares contributes.routes:["box"] → factory at modules/<key>/routes/box.js
 // exporting a function returning an express Router. Auth model: audit is composed
@@ -136,10 +173,18 @@ function discoveredRegistry(opts) {
 // its required rank via api.requireBuilder / api.requireRank (public read routes
 // need no gate). The BV1.R44 fitness check enforces that every write route is
 // rank-gated. Returns the count mounted. No-op when nothing is discovered/enabled.
+//
+// Verifies the seam wiring FIRST (verifyEnabledPorts, above). This is the boot hook
+// the check belongs on because it is the one hook every server that mounts modules
+// runs — the live API, platform-server, and the test harness alike — so the
+// verification cannot be skipped by adding an entrypoint, the way a separately
+// called check could be. It runs before the first `require` of a module's route
+// factory, so a half-wired instance never gets as far as loading module code.
 function mountModuleRoutes(router, { isEnabled } = {}, opts) {
+  const enabled = enabledModules({ isEnabled }, opts);
+  verifyEnabledPorts(enabled);
   let mounted = 0;
-  for (const { key, dir, manifest } of discovered(opts).loaded) {
-    if (typeof isEnabled === 'function' && !isEnabled(key)) continue;
+  for (const { dir, manifest } of enabled) {
     const routeKeys = (manifest.contributes && manifest.contributes.routes) || [];
     for (const rk of routeKeys) {
       const factory = require(path.join(dir, 'routes', `${rk}.js`));

package/src/module-seams.js

@@ -75,10 +75,14 @@ function listPorts() {
 
 // BOOT-TIME (manifest-level) verification, distinct from resolve()'s RUNTIME
 // throw: given the ENABLED modules' manifests, confirm every consumed port is
-// provided by some enabled module, and no port has two providers. The loader
-// (BV1.R41) runs this before mounting so a required capability with no provider
-// is caught at boot with a clear message — not as a surprise throw the first time
-// the seam is used. Pure (no registry mutation), so it is safe to run anytime.
+// provided by some enabled module, and no port has two providers. The loader's
+// mountModuleRoutes (BV1.R41) runs this via verifyEnabledPorts before mounting any
+// module router, and THROWS on a non-ok result, so a required capability with no
+// provider is caught at boot with a clear message — not as a surprise throw the
+// first time the seam is used. This function itself only REPORTS: it is pure (no
+// registry mutation, no throw), so it is safe to run anytime, and the loader owns
+// the decision to refuse the boot. Wired + regression-pinned by task 1003820,
+// which found it defined, exported, tested, and called by nothing.
 // manifests: [{ key, provides: [...], consumes: [...] }] → { ok, errors: [...] }.
 function verifyPortsSatisfied(manifests = []) {
   const provided = new Map(); // port -> [providerKey,...]

package/tests/module_loader.mjs

@@ -155,6 +155,71 @@ test('mountModuleRoutes: mounts an enabled module router, skips a disabled one',
   loader._reset();
 });
 
+// ---------------------------------------------------------------------------
+// task 1003820 — the mount hook must VERIFY the seam wiring before it mounts.
+//
+// verifyPortsSatisfied was defined, exported through the doorway, and unit-tested
+// in isolation, but no production code called it: a module consuming a port no
+// enabled module provided booted clean and threw later, on a request path, out of
+// resolve(). These pin the CALL, not the function — see also the spawn-boot half
+// in tests/platform_boot.mjs, which is what actually turns red if the call site is
+// deleted (learning 1000154).
+// ---------------------------------------------------------------------------
+
+test('task 1003820: mountModuleRoutes refuses an enabled module consuming an unprovided port', () => {
+  loader._reset();
+  const factory = "module.exports = () => function moduleRoute(req, res, next) { next(); };";
+  const root = fixtureRoot({
+    consumer: {
+      manifest: validManifest('consumer', { consumes: ['reward'], contributes: { routes: ['main'] } }),
+      files: { 'routes/main.js': factory },
+    },
+  });
+  const used = [];
+  const fakeRouter = { use: (fn) => used.push(fn) };
+  assert.throws(
+    () => loader.mountModuleRoutes(fakeRouter, { isEnabled: () => true }, { roots: [root], core: '1.0.0' }),
+    (e) => /unsatisfiable module wiring/.test(e.message)
+      && /"consumer" consumes port "reward"/.test(e.message),
+    'the refusal names the module and the port it cannot satisfy'
+  );
+  assert.equal(used.length, 0, 'it refuses BEFORE requiring any module route factory');
+  loader._reset();
+});
+
+test('task 1003820: a DISABLED module’s unsatisfied consumes is not a wiring error', () => {
+  loader._reset();
+  const factory = "module.exports = () => function moduleRoute(req, res, next) { next(); };";
+  const root = fixtureRoot({
+    consumer: { manifest: validManifest('consumer', { consumes: ['reward'] }) },
+    plain: {
+      manifest: validManifest('plain', { contributes: { routes: ['main'] } }),
+      files: { 'routes/main.js': factory },
+    },
+  });
+  const used = [];
+  const fakeRouter = { use: (fn) => used.push(fn) };
+  // Only the ENABLED set is verified: a module that is off is a module that is
+  // not there, so its consumes names nothing that has to be provided.
+  const mounted = loader.mountModuleRoutes(fakeRouter, { isEnabled: (k) => k === 'plain' }, { roots: [root], core: '1.0.0' });
+  assert.equal(mounted, 1);
+  loader._reset();
+});
+
+test('task 1003820: mountModuleRoutes refuses two enabled providers of one port', () => {
+  loader._reset();
+  const root = fixtureRoot({
+    a: { manifest: validManifest('a', { provides: ['reward'] }) },
+    b: { manifest: validManifest('b', { provides: ['reward'] }) },
+  });
+  assert.throws(
+    () => loader.mountModuleRoutes({ use: () => {} }, { isEnabled: () => true }, { roots: [root], core: '1.0.0' }),
+    (e) => /provided by more than one enabled module/.test(e.message),
+    'the single-provider invariant is enforced at boot, not at first resolve()'
+  );
+  loader._reset();
+});
+
 test('the live tree discovers the extracted modules cleanly (BV1.R43/R48/R47/R49/R72)', () => {
   // dev-box graduated first (modules/dev-box/, BV1.R43), art-pipeline next
   // (BV1.R48 / task 1417), discord next (BV1.R47 / task 1416), game next
@@ -352,6 +417,9 @@ test('the demo proof module mounts + serves through the loader (BV1.R52 / task 1
 
   const used = [];
   const fakeRouter = { use: (fn) => used.push(fn) };
+  // Since task 1003820 this also proves the SHIPPED enabled set is satisfiable:
+  // mountModuleRoutes verifies the seam wiring first and throws on a half-wired
+  // set, so a manifest change that strands a consumed port reds this test.
   const mounted = loader.mountModuleRoutes(fakeRouter, { isEnabled: isModuleEnabled });
   assert.ok(mounted >= 1, 'at least the demo router mounted');
 

package/tests/platform_boot.mjs

@@ -284,3 +284,56 @@ test('task 1002419: a real `node src/platform-server.js` boot announces the reco
     child.kill('SIGKILL');
   }
 });
+
+// ---------------------------------------------------------------------------
+// task 1003820 — a half-wired module set must REFUSE the boot.
+//
+// The mutation-proof half of the wiring guard. tests/module_loader.mjs calls
+// mountModuleRoutes directly, so it stays green if the verifyEnabledPorts call
+// site is deleted; this spawns the real entrypoint the way docker-entrypoint.sh
+// does and asserts the process dies with the wiring error, so removing the call
+// turns it red (learning 1000154 — the same shape as task 1002419 above).
+//
+// The unsatisfiable set is built from REAL modules via a documented env knob, not
+// a fixture: economy provides the `reward` port and ideas consumes it, both
+// default:true, so turning economy off strands ideas. DB-free — the refusal
+// happens while the router is being built, long before anything opens a socket.
+// ---------------------------------------------------------------------------
+
+test('task 1003820: platform-server refuses to boot when an enabled module consumes an unprovided port', async () => {
+  const port = await freePort();
+  const child = spawn(process.execPath, [path.join(REPO_ROOT, 'src', 'platform-server.js')], {
+    cwd: REPO_ROOT,
+    env: {
+      ...process.env,
+      PORT: String(port),
+      HOST: '127.0.0.1',
+      // economy provides "reward"; ideas consumes it and stays on.
+      CLOUDBONGOS_MODULE_ECONOMY: '0',
+    },
+  });
+
+  let out = '';
+  child.stdout.on('data', (d) => { out += d; });
+  child.stderr.on('data', (d) => { out += d; });
+
+  // SIGKILL in a finally: if the guard regresses, the child boots CLEANLY and never
+  // exits, so without this the suite would hang on a live server instead of failing.
+  try {
+    const code = await new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error(`platform-server stayed up; it must refuse a half-wired boot. Log:${out}`)),
+        20_000
+      );
+      child.on('error', (e) => { clearTimeout(timer); reject(e); });
+      child.on('exit', (c) => { clearTimeout(timer); resolve(c); });
+    });
+
+    assert.notEqual(code, 0, `the boot must FAIL, not come up half-wired (exit ${code}). Log:${out}`);
+    assert.match(out, /unsatisfiable module wiring/, 'the refusal says what is wrong');
+    assert.match(out, /"ideas" consumes port "reward"/, 'it names the module and the port');
+    assert.doesNotMatch(out, /listening/, 'it never reaches the listen announcement');
+  } finally {
+    child.kill('SIGKILL');
+  }
+});