@bongos/core 1.19.648 → 1.19.650

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');
+  }
+});