@bongos/core 1.17.0

package/tests/module-scope-map.mjs

@@ -0,0 +1,88 @@
+// tests/module-scope-map.mjs — the goal scope wall's source (BV1.R54 / task 1508, ADR 0086 §4/§7).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const scope = require(path.join(ROOT, 'src', 'bongos', 'module-scope-map.js'));
+const { PROTECTED_GLOBS } = require(path.join(ROOT, 'src', 'bongos', 'permission-path-check.js'));
+
+test('roster covers the decided ~16 modules + kernel, each with non-empty globs', () => {
+  const keys = scope.moduleKeys();
+  // the decided roster from docs/design/modular-architecture/02-module-map.md §6 + kernel
+  for (const k of ['kernel', 'lifecycle', 'economy', 'grading', 'memory', 'onboarding',
+    'ideas', 'builder-settings', 'sessions', 'autonomy', 'security', 'hall-ui',
+    'status-ui', 'game', 'art-pipeline', 'discord', 'dev-box']) {
+    assert.ok(keys.includes(k), `roster missing module "${k}"`);
+    const e = scope.scopeForModule(k);
+    assert.ok(e && Array.isArray(e.globs) && e.globs.length > 0, `module "${k}" has no globs`);
+    assert.equal(typeof e.protected, 'boolean', `module "${k}".protected must be a boolean`);
+  }
+});
+
+test('a PROTECTED module: kernel intersects the trust core → protected:true', () => {
+  assert.equal(scope.isProtectedModule('kernel'), true);
+  assert.equal(scope.scopeForModule('kernel').protected, true);
+  // lifecycle (ship pipeline + migrations) is protected too
+  assert.equal(scope.isProtectedModule('lifecycle'), true);
+});
+
+test('a NON-protected module: status-ui is a pure surface (modules/status-ui/) → protected:false', () => {
+  assert.equal(scope.isProtectedModule('status-ui'), false);
+  assert.equal(scope.scopeForModule('status-ui').protected, false);
+  // hall-ui (modules/hall-ui/, carved in BV1.R85) is likewise outside the protected core
+  assert.equal(scope.isProtectedModule('hall-ui'), false);
+});
+
+test('`protected` is DERIVED from the imported PROTECTED_GLOBS, never hand-set', () => {
+  // Re-running the derivation over each module's own globs must reproduce the
+  // stored flag — proving it is computed from PROTECTED_GLOBS, not a literal that
+  // could drift (the ADR 0086 §7 / SEC #863 contract).
+  for (const k of scope.moduleKeys()) {
+    const e = scope.scopeForModule(k);
+    assert.equal(e.protected, scope.isProtected(e.globs), `module "${k}".protected is not a faithful derivation`);
+  }
+  // and the roster genuinely contains BOTH kinds (not all-true / all-false)
+  const prot = scope.protectedModules();
+  assert.ok(prot.length > 0, 'expected at least one protected module');
+  assert.ok(prot.length < scope.moduleKeys().length, 'expected at least one non-protected module');
+});
+
+test('isProtected actually consults PROTECTED_GLOBS (overlap, prefix-aware both ways)', () => {
+  assert.ok(PROTECTED_GLOBS.includes('migrations/'), 'fixture assumption: migrations/ is protected');
+  assert.equal(scope.isProtected(['migrations/']), true, 'a protected glob must compute protected');
+  assert.equal(scope.isProtected(['src/bongos/routes/tasks.js']), true, 'a file under a protected subtree must compute protected');
+  assert.equal(scope.isProtected(['modules/status-ui/']), false, 'a non-core surface must compute non-protected');
+  assert.equal(scope.isProtected([]), false, 'empty scope is not protected');
+});
+
+test('globsForModules flattens a scope set; unknown keys contribute nothing', () => {
+  const g = scope.globsForModules(['ideas']);
+  assert.ok(g.includes('modules/ideas/'), 'ideas owns its module directory (carved BV1.R78)');
+  assert.deepEqual(scope.globsForModules(['bogus']), [], 'unknown key contributes no globs');
+  assert.deepEqual(scope.globsForModules([]), []);
+});
+
+test('scopeIncludesProtected: true if ANY module in the set is protected', () => {
+  assert.equal(scope.scopeIncludesProtected(['status-ui', 'art-pipeline']), false);
+  assert.equal(scope.scopeIncludesProtected(['status-ui', 'lifecycle']), true);
+  assert.equal(scope.scopeIncludesProtected([]), false);
+  // an unknown key is not "protected" here — the route validates membership/known-keys separately
+  assert.equal(scope.scopeIncludesProtected(['bogus']), false);
+});
+
+test('unknown module keys resolve to null, not a thrown error or a false flag', () => {
+  assert.equal(scope.isProtectedModule('bogus'), null);
+  assert.equal(scope.scopeForModule('bogus'), null);
+  assert.equal(scope.isModuleKey('bogus'), false);
+  assert.equal(scope.isModuleKey('kernel'), true);
+});
+
+test('the exported roster is frozen (immutable scope wall)', () => {
+  assert.ok(Object.isFrozen(scope.MODULE_SCOPE_MAP));
+  assert.ok(Object.isFrozen(scope.scopeForModule('kernel')));
+  assert.ok(Object.isFrozen(scope.scopeForModule('kernel').globs));
+});

package/tests/module_api.mjs

@@ -0,0 +1,110 @@
+// tests/module_api.mjs — the published doorway surface + seam registry
+// (BV1.R37 / task 1406, ADR 0083). Asserts the module-api.js public surface is
+// stable (modules depend on it) and the seam registry behaves correctly.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const api = require(path.join(ROOT, 'src', 'module-api.js'));
+const seams = require(path.join(ROOT, 'src', 'module-seams.js'));
+
+// The published surface — adding a key is a MINOR bump (extend this list);
+// removing/renaming a key is normally a MAJOR bump (a breaking change to every
+// module). Exception (BV1.R68 / ADR 0091 §3): relocating a DOMAIN query whose
+// sole in-repo consumer moves in lockstep is treated as MINOR — e.g.
+// `setBuilderBoxBlocked` left for modules/dev-box/db.js at 1.5.0, when `withTx`
+// was added; no enabled module at its pinned coreVersion lost a capability.
+const PUBLISHED_SURFACE = [
+  'CORE_VERSION',
+  'requireBuilder', 'requireRank', 'rankMeetsThreshold', 'requireBfgPrincipal', 'allowBoxScope',
+  'pool', 'getPool', 'instanceDbName', 'withTx', 'getBuilderById',
+  'secretBox', // Gemini-key storage relocated to modules/art-pipeline + its 'art.getBuilderGeminiKeyRow' port (ADR 0102)
+  'routeRankCheck', 'permissionPathCheck', // BV1.R73: kernel trust classifiers (1.6.0)
+  'repoInfo', 'moduleScopeMap', 'pathMatch', // BV1.R86: kernel repo-identity + scope-wall + touches-overlap for the carved lifecycle (1.12.0)
+  'goalScopeCheck', // BV1.R60: kernel scope wall for the goal-authored-task create gate (1.13.0; ADR 0086 §3)
+  'insertAuditLog', 'LIVE_RANK_LADDER', // createTask + VOTABLE_TASK_STATUSES + tallyPeerVotes RETIRED at 1.12.0 (BV1.R86 → lifecycle port); captureIdea retired at 1.8.0 (BV1.R78 → ideas.capture port)
+  'llmCache', // BV1.R73: shared LLM-cost cache (1.6.0; tracked domain leak)
+  'llmPricing', // BV1.R77: shared token→USD pricing (1.7.0; tracked domain leak — economy carve)
+  'branding', 'clientBranding', 'userAgent', 'resolveEnv', 'readConfigFileSync', 'configHome', 'configPath', // userAgent added 1.12.0 (BV1.R86; github-push UA)
+  'enabledDisciplines', // BV1.R81: instance offered-disciplines (1.9.0; onboarding restock backstop)
+  'registerProvider', 'hasProvider', 'resolve', 'resolveOptional', 'listPorts', 'verifyPortsSatisfied',
+  'on', 'emit', 'emitAsync', 'listEvents', 'seamSnapshot',
+  'contribute', 'contributions', 'collectContributions', 'listContributionPoints',
+  'buildInfo', 'validateOrRespond', 'LIMITS', 'parseId', 'asyncHandler', 'corsPublicGet', // parseId added 1.8.0 (BV1.R78); asyncHandler + corsPublicGet added 1.12.0 (BV1.R86; lifecycle routes)
+  'parsePagination', 'pageMeta', 'PAGINATION', // R14 (#2001, 1.17.0): shared pagination contract for module list routes (ADR 0119)
+  'logger',
+];
+
+test('module-api exposes exactly the published surface (stability contract)', () => {
+  const actual = Object.keys(api).sort();
+  const expected = [...PUBLISHED_SURFACE].sort();
+  assert.deepEqual(actual, expected,
+    `doorway surface drifted. added: [${actual.filter((k) => !expected.includes(k))}] removed: [${expected.filter((k) => !actual.includes(k))}]`);
+});
+
+test('CORE_VERSION is a semver string', () => {
+  assert.match(api.CORE_VERSION, /^\d+\.\d+\.\d+$/);
+});
+
+test('auth gates are re-exported as functions', () => {
+  for (const k of ['requireBuilder', 'requireRank', 'rankMeetsThreshold', 'requireBfgPrincipal']) {
+    assert.equal(typeof api[k], 'function', `${k} should be a function`);
+  }
+});
+
+test('pool accessor is present and getPool() returns the same pool', () => {
+  assert.ok(api.pool, 'pool present');
+  assert.equal(api.getPool(), api.pool);
+  assert.equal(typeof api.instanceDbName, 'function');
+});
+
+test('logger() returns a namespaced info/warn/error logger', () => {
+  const log = api.logger('demo');
+  assert.equal(typeof log.info, 'function');
+  assert.equal(typeof log.warn, 'function');
+  assert.equal(typeof log.error, 'function');
+});
+
+// --- seam registry behavior (ports + events) ---
+
+test('seam ports: register → resolve round-trips; duplicate throws; missing throws', () => {
+  seams._reset();
+  const provider = () => 42;
+  api.registerProvider('demo.reward', provider);
+  assert.equal(api.hasProvider('demo.reward'), true);
+  assert.equal(api.resolve('demo.reward'), provider);
+  assert.equal(api.resolve('demo.reward')(), 42);
+  assert.throws(() => api.registerProvider('demo.reward', () => 0), /already has a provider/);
+  assert.throws(() => api.resolve('nope.port'), /no provider registered/);
+  assert.equal(api.resolveOptional('nope.port', 'fb'), 'fb');
+  assert.deepEqual(api.listPorts(), ['demo.reward']);
+  seams._reset();
+});
+
+test('seam events: emit fans out to all listeners and isolates a throwing one', () => {
+  seams._reset();
+  const seen = [];
+  api.on('task.shipped', (p) => seen.push(`a:${p}`));
+  api.on('task.shipped', () => { throw new Error('boom'); }); // must not break the others
+  api.on('task.shipped', (p) => seen.push(`c:${p}`));
+  const invoked = api.emit('task.shipped', 7);
+  assert.equal(invoked, 3, 'all 3 listeners invoked despite one throwing');
+  assert.deepEqual(seen, ['a:7', 'c:7']);
+  assert.equal(api.emit('nobody.listening', 1), 0, 'emit with no listeners is a no-op returning 0');
+  seams._reset();
+});
+
+test('seam on() returns an unsubscribe that removes the listener', () => {
+  seams._reset();
+  let n = 0;
+  const off = api.on('ping', () => { n += 1; });
+  api.emit('ping');
+  off();
+  api.emit('ping');
+  assert.equal(n, 1, 'listener fired once, then unsubscribed');
+  seams._reset();
+});

package/tests/module_cli.mjs

@@ -0,0 +1,292 @@
+// tests/module_cli.mjs — the `bongos module new <key>` scaffolder + `bongos upgrade`
+// coreVersion pre-check (BV1.R50 / task 1419, ADR 0083). Hermetic: every fs test
+// scaffolds into a temp dir; the upgrade logic is driven with injected config so
+// no real config/modules.json or running server is touched. DB-free → picked up
+// by scripts/gds/run-unit-tests.js (the `unit` gate).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const mod = require(path.join(ROOT, 'scripts', 'gds', 'module.js'));
+const loader = require(path.join(ROOT, 'src', 'module-loader', 'loader.js'));
+const { validateManifest } = require(path.join(ROOT, 'src', 'module-loader', 'manifest-schema.js'));
+const bongos = (await import(new URL('../bin/bongos.js', import.meta.url))).default;
+
+const tmpModulesRoot = () => fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-modnew-'));
+
+// ---------------------------------------------------------------------------
+// bongos module new <key> — the scaffolder
+// ---------------------------------------------------------------------------
+
+test('scaffoldModule: writes a valid, loader-discoverable module with no core edit', () => {
+  loader._reset();
+  const root = tmpModulesRoot();
+  const { dir, manifest } = mod.scaffoldModule({ key: 'econ', modulesDir: root, core: '1.0.0' });
+
+  // every promised artifact exists
+  for (const f of ['module.json', 'routes/econ.js', 'CLAUDE.md', 'migrations/.gitkeep', 'ui/.gitkeep']) {
+    assert.ok(fs.existsSync(path.join(dir, f)), `missing scaffolded file: ${f}`);
+  }
+  // the manifest is valid AND matches what was returned
+  const onDisk = JSON.parse(fs.readFileSync(path.join(dir, 'module.json'), 'utf8'));
+  assert.deepEqual(onDisk, manifest);
+  assert.ok(validateManifest(onDisk).valid, 'scaffolded manifest must validate');
+  assert.equal(onDisk.key, 'econ');
+  assert.equal(onDisk.default, false);
+  assert.equal(onDisk.coreVersion, '^1.0.0');
+  // attribution fields (ADR 0107 §2) are stamped from the start
+  for (const field of ['author', 'origin', 'license', 'maintainer']) {
+    assert.ok(typeof onDisk[field] === 'string' && onDisk[field].length > 0, `${field} should be a non-empty string`);
+  }
+  assert.equal(onDisk.license, 'AGPL-3.0');
+
+  // the loader discovers it from the temp root (the done-when)
+  const { loaded, skipped, errors } = loader.discoverModules({ roots: [root], core: '1.0.0' });
+  assert.deepEqual(errors, []);
+  assert.deepEqual(skipped, []);
+  assert.equal(loaded.length, 1);
+  assert.equal(loaded[0].key, 'econ');
+
+  // the sample route is real (factory pattern) and reaches core only via the doorway
+  const route = fs.readFileSync(path.join(dir, 'routes', 'econ.js'), 'utf8');
+  assert.match(route, /express\.Router\(\)/);
+  assert.match(route, /require\('\.\.\/\.\.\/\.\.\/src\/module-api'\)/);
+  assert.ok(!/require\('\.\.\/\.\.\/\.\.\/src\/(?!module-api)/.test(route), 'sample route must not deep-import core');
+  loader._reset();
+});
+
+test('scaffoldModule: a kebab-case key produces matching dir, route file, and title', () => {
+  const root = tmpModulesRoot();
+  const { dir, manifest } = mod.scaffoldModule({ key: 'dev-box', modulesDir: root, core: '1.0.0' });
+  assert.equal(manifest.title, 'Dev Box');
+  assert.deepEqual(manifest.contributes.routes, ['dev-box']);
+  assert.ok(fs.existsSync(path.join(dir, 'routes', 'dev-box.js')));
+  assert.match(fs.readFileSync(path.join(dir, 'routes', 'dev-box.js'), 'utf8'), /devBoxRoutes/);
+});
+
+test('scaffoldModule: rejects an invalid key', () => {
+  const root = tmpModulesRoot();
+  assert.throws(() => mod.scaffoldModule({ key: 'Bad_Key', modulesDir: root }), /invalid module key/);
+  assert.throws(() => mod.scaffoldModule({ key: '1leading', modulesDir: root }), /invalid module key/);
+});
+
+test('scaffoldModule: refuses to overwrite an existing module unless --force', () => {
+  const root = tmpModulesRoot();
+  mod.scaffoldModule({ key: 'econ', modulesDir: root, core: '1.0.0' });
+  assert.throws(() => mod.scaffoldModule({ key: 'econ', modulesDir: root, core: '1.0.0' }), /already exists/);
+  // --force succeeds
+  assert.doesNotThrow(() => mod.scaffoldModule({ key: 'econ', modulesDir: root, core: '1.0.0', force: true }));
+});
+
+test('buildManifest: caret-pins the current core and declares one sample route', () => {
+  const m = mod.buildManifest('shop', { core: '1.2.0' });
+  assert.equal(m.coreVersion, '^1.2.0');
+  assert.equal(m.key, 'shop');
+  assert.equal(m.default, false);
+  assert.deepEqual(m.contributes.routes, ['shop']);
+  assert.ok(validateManifest(m).valid);
+  assert.equal(m.license, 'AGPL-3.0');
+});
+
+// ---------------------------------------------------------------------------
+// bongos upgrade — coreVersion pre-check
+// ---------------------------------------------------------------------------
+
+test('evaluateUpgrade: all enabled modules satisfied → ok', () => {
+  const v = mod.evaluateUpgrade({
+    core: '1.0.0',
+    rows: [
+      { key: 'a', coreVersion: '^1.0.0', enabled: true, satisfied: true },
+      { key: 'b', coreVersion: '^1.0.0', enabled: false, satisfied: true },
+    ],
+  });
+  assert.equal(v.ok, true);
+  assert.equal(v.blocking.length, 0);
+});
+
+test('evaluateUpgrade: an ENABLED mismatch refuses; a DISABLED mismatch only warns', () => {
+  const v = mod.evaluateUpgrade({
+    core: '1.0.0',
+    rows: [
+      { key: 'future', coreVersion: '^2.0.0', enabled: true, satisfied: false },
+      { key: 'old-wip', coreVersion: '^2.0.0', enabled: false, satisfied: false },
+    ],
+  });
+  assert.equal(v.ok, false, 'an enabled mismatch must block (fail-closed)');
+  assert.deepEqual(v.blocking.map((b) => b.key), ['future']);
+  assert.deepEqual(v.warnings.map((w) => w.key), ['old-wip']);
+});
+
+test('gatherUpgrade: REFUSES an enabled module whose coreVersion the core does not satisfy', () => {
+  loader._reset();
+  const root = tmpModulesRoot();
+  // scaffold a module that targets a FUTURE core (^2.0.0), then enable it.
+  mod.scaffoldModule({ key: 'future', modulesDir: root, core: '2.0.0' });
+  const data = mod.gatherUpgrade({
+    modulesDir: root, core: '1.0.0', env: {},
+    neutral: {}, instance: { modules: { future: true } }, prefix: 'CLOUDBONGOS',
+  });
+  const v = mod.evaluateUpgrade(data);
+  assert.equal(v.ok, false);
+  assert.deepEqual(v.blocking.map((b) => b.key), ['future']);
+  loader._reset();
+});
+
+test('gatherUpgrade: a satisfied enabled module passes; the same module disabled never blocks', () => {
+  loader._reset();
+  const root = tmpModulesRoot();
+  mod.scaffoldModule({ key: 'econ', modulesDir: root, core: '1.0.0' });
+
+  const enabled = mod.gatherUpgrade({ modulesDir: root, core: '1.0.0', env: {}, neutral: {}, instance: { modules: { econ: true } }, prefix: 'CLOUDBONGOS' });
+  assert.equal(mod.evaluateUpgrade(enabled).ok, true);
+  assert.equal(enabled.rows.find((r) => r.key === 'econ').enabled, true);
+
+  // scaffold a SECOND, future-core module but leave it disabled → still ok.
+  mod.scaffoldModule({ key: 'future', modulesDir: root, core: '2.0.0' });
+  const mixed = mod.gatherUpgrade({ modulesDir: root, core: '1.0.0', env: {}, neutral: {}, instance: { modules: { econ: true, future: false } }, prefix: 'CLOUDBONGOS' });
+  const v = mixed && mod.evaluateUpgrade(mixed);
+  assert.equal(v.ok, true, 'a disabled future-core module must not block the upgrade');
+  assert.equal(v.warnings.some((w) => w.key === 'future'), true, 'but it is surfaced as a warning');
+  loader._reset();
+});
+
+test('cmdUpgrade: exit 0 with no modules, exit 1 when an enabled module is incompatible', () => {
+  const lines = [];
+  const sink = { log: (s) => lines.push(String(s)), errlog: (s) => lines.push(String(s)) };
+
+  const empty = mod.cmdUpgrade([], { ...sink, gather: () => ({ rows: [], errors: [], core: '1.0.0' }) });
+  assert.equal(empty, 0);
+
+  const bad = mod.cmdUpgrade([], {
+    ...sink,
+    gather: () => ({ core: '1.0.0', errors: [], rows: [{ key: 'future', coreVersion: '^2.0.0', enabled: true, satisfied: false }] }),
+  });
+  assert.equal(bad, 1);
+  assert.ok(lines.some((l) => /REFUSING/.test(l)), 'refusal is reported');
+});
+
+// ---------------------------------------------------------------------------
+// bongos module check <key> — ADR 0107 §4 upstreaming pre-check + DCO sign-off
+// ---------------------------------------------------------------------------
+
+test('checkModulePublishability: a clean, platform-shaped (scaffolded) module passes', () => {
+  const root = tmpModulesRoot();
+  mod.scaffoldModule({ key: 'widget', modulesDir: root, core: '1.0.0' });
+  const r = mod.checkModulePublishability('widget', { modulesDir: root });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.findings, []);
+  assert.deepEqual(r.denied, []);
+});
+
+test('checkModulePublishability: fails with a clear reason when the manifest is not AGPL-3.0', () => {
+  const root = tmpModulesRoot();
+  const { dir } = mod.scaffoldModule({ key: 'proprietary', modulesDir: root, core: '1.0.0' });
+  const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'module.json'), 'utf8'));
+  manifest.license = 'Proprietary';
+  fs.writeFileSync(path.join(dir, 'module.json'), JSON.stringify(manifest, null, 2));
+  const r = mod.checkModulePublishability('proprietary', { modulesDir: root });
+  assert.equal(r.ok, false);
+  assert.ok(r.findings.some((f) => f.kind === 'license' && /AGPL-3\.0/.test(f.detail)));
+});
+
+test('checkModulePublishability: fails a module containing denied content (game content / copyrighted reference material) with a clear reason', () => {
+  const root = tmpModulesRoot();
+  // "game" and "art-pipeline" are the platform's own real, hard-copyright content
+  // modules (ripped map references / pixel art) — exercising the check against
+  // them under a temp modulesDir proves the DENYLIST reuse without needing any
+  // new content-sniffing heuristics.
+  const dir = path.join(root, 'game');
+  fs.mkdirSync(path.join(dir, 'public', 'assets'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'module.json'), JSON.stringify({
+    key: 'game', title: 'Game', description: 'x', coreVersion: '^1.0.0', license: 'AGPL-3.0', contributes: {},
+  }, null, 2));
+  fs.writeFileSync(path.join(dir, 'public', 'assets', 'reference-map.png'), 'not-a-real-png');
+  const r = mod.checkModulePublishability('game', { modulesDir: root });
+  assert.equal(r.ok, false);
+  const contentFinding = r.findings.find((f) => f.kind === 'content');
+  assert.ok(contentFinding, 'expected a content finding');
+  assert.match(contentFinding.detail, /game content|pixel art|copyrighted reference/);
+  assert.ok(r.denied.includes('modules/game/public/assets/reference-map.png'));
+});
+
+test('checkModulePublishability: throws for a module key that does not exist', () => {
+  const root = tmpModulesRoot();
+  assert.throws(() => mod.checkModulePublishability('nope', { modulesDir: root }), /does not exist/);
+});
+
+test('recordSignOff: writes a DCO-style affirmation only for the caller to invoke on a pass', () => {
+  const root = tmpModulesRoot();
+  const { dir } = mod.scaffoldModule({ key: 'widget', modulesDir: root, core: '1.0.0' });
+  const record = mod.recordSignOff('widget', 'Ada Lovelace <ada@example.com>', { modulesDir: root });
+  const onDisk = JSON.parse(fs.readFileSync(path.join(dir, '.upstream-signoff.json'), 'utf8'));
+  assert.equal(onDisk.module, 'widget');
+  assert.equal(onDisk.signOff.signedBy, 'Ada Lovelace <ada@example.com>');
+  assert.match(onDisk.statement, /AGPL-3\.0/);
+  assert.match(onDisk.statement, /not a copyright-assignment CLA/);
+  assert.ok(record.path.includes('.upstream-signoff.json'));
+});
+
+test('cmdCheck: exit 0 + prints pass on a clean module; records sign-off only when --sign-off is given', () => {
+  const lines = [];
+  const sink = { log: (s) => lines.push(String(s)), errlog: (s) => lines.push(String(s)) };
+  let signedCall = null;
+  const check = () => ({ key: 'widget', ok: true, findings: [], files: [], denied: [] });
+  const sign = (key, by) => { signedCall = { key, by }; return { path: `modules/${key}/.upstream-signoff.json`, signOff: { signedBy: by, date: 'now' } }; };
+
+  const noSign = mod.cmdCheck(['widget'], { ...sink, check, sign });
+  assert.equal(noSign, 0);
+  assert.equal(signedCall, null, 'no --sign-off given => no sign-off recorded');
+  assert.ok(lines.some((l) => /No --sign-off given/.test(l)));
+
+  const withSign = mod.cmdCheck(['widget', '--sign-off', 'Ada Lovelace <ada@example.com>'], { ...sink, check, sign });
+  assert.equal(withSign, 0);
+  assert.deepEqual(signedCall, { key: 'widget', by: 'Ada Lovelace <ada@example.com>' });
+});
+
+test('cmdCheck: exit 1 + refuses (no sign-off) when the pre-check fails', () => {
+  const lines = [];
+  const sink = { log: (s) => lines.push(String(s)), errlog: (s) => lines.push(String(s)) };
+  let signed = false;
+  const check = () => ({ key: 'game', ok: false, findings: [{ kind: 'content', detail: 'contains denied content' }], files: [], denied: ['modules/game/x.png'] });
+  const sign = () => { signed = true; };
+
+  const code = mod.cmdCheck(['game', '--sign-off', 'Someone <s@example.com>'], { ...sink, check, sign });
+  assert.equal(code, 1);
+  assert.equal(signed, false, 'a failing pre-check must never record a sign-off');
+  assert.ok(lines.some((l) => /REFUSING/.test(l)));
+});
+
+test('cmdCheck: usage error (exit 2) when no key is given', () => {
+  const lines = [];
+  const code = mod.cmdCheck([], { log: (s) => lines.push(s), errlog: (s) => lines.push(s) });
+  assert.equal(code, 2);
+});
+
+// ---------------------------------------------------------------------------
+// dispatch wiring (bin/bongos.js)
+// ---------------------------------------------------------------------------
+
+test('the `module` verb dispatches to module.js, `upgrade` to upgrade.js', () => {
+  assert.equal(bongos.VERBS.module.script, 'module.js');
+  // `upgrade` was split into its own scripts/gds/upgrade.js (no longer forwarded
+  // as `module.js upgrade` with prefixArgs).
+  assert.equal(bongos.VERBS.upgrade.script, 'upgrade.js');
+  // help lists both
+  const h = bongos.helpText();
+  assert.ok(h.includes('module'));
+  assert.ok(h.includes('upgrade'));
+});
+
+test('`bongos module check` is documented in help / dispatches to module.js check subcommand', () => {
+  const lines = [];
+  mod.printHelp((s) => lines.push(s));
+  assert.ok(lines.some((l) => /module check/.test(l)));
+  // module.js itself dispatches the "check" subcommand (bongos.js forwards args[1:] verbatim to module.js)
+  assert.equal(mod.main(['node', 'module.js', 'check']), 2, 'no key => usage error');
+});

package/tests/module_contributions.mjs

@@ -0,0 +1,148 @@
+// tests/module_contributions.mjs — the module→core contribution seam (BV1.R42 /
+// task 1411, ADR 0083). The third seam primitive: many-contributor accumulating
+// extension points, distinct from ports (one provider) and events (fire-and-
+// forget). Covers a REGISTERED and an ABSENT contribution on BOTH runtimes — the
+// server seam (src/module-seams.js, consumed by GET /me) and its browser twin
+// (window.OTB.contributeSettingsPanel in modules/hall-ui/public/dom-utils.js,
+// consumed by settings.js — the hall surface carved to the hall-ui module in
+// BV1.R85).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const seams = require(path.join(ROOT, 'src', 'module-seams.js'));
+
+// ---- server seam: contribute / contributions -------------------------------
+
+test('contributions: ABSENT point returns an empty array (no guard needed)', () => {
+  seams._reset();
+  assert.deepEqual(seams.contributions('profile.fields'), []);
+  assert.deepEqual(seams.contributions('nobody.here'), []);
+});
+
+test('contributions: a REGISTERED contribution shows up, in registration order', () => {
+  seams._reset();
+  const a = () => ({ a: 1 });
+  const b = () => ({ b: 2 });
+  seams.contribute('profile.fields', a);
+  seams.contribute('profile.fields', b);
+  assert.deepEqual(seams.contributions('profile.fields'), [a, b]);
+  // returns a COPY — mutating it can't corrupt the registry
+  seams.contributions('profile.fields').push(() => ({}));
+  assert.equal(seams.contributions('profile.fields').length, 2);
+  seams._reset();
+});
+
+test('contribute: rejects a bad point or a null contribution', () => {
+  seams._reset();
+  assert.throws(() => seams.contribute('', () => {}), /non-empty string/);
+  assert.throws(() => seams.contribute('p', null), /must not be null/);
+  assert.throws(() => seams.contribute('p', undefined), /must not be null/);
+  seams._reset();
+});
+
+// ---- server seam: collectContributions (what GET /me runs) ------------------
+
+test('collectContributions: ABSENT → empty; REGISTERED → each invoked with ctx', async () => {
+  seams._reset();
+  // absent
+  assert.deepEqual(await seams.collectContributions('profile.fields', { builderId: 7 }), []);
+  // registered — both function-contributors get the ctx and return their slice
+  const seen = [];
+  seams.contribute('profile.fields', (ctx) => { seen.push(ctx.builderId); return { box: { x: 1 } }; });
+  seams.contribute('profile.fields', async (ctx) => { seen.push(ctx.builderId); return { discord: { linked: true } }; });
+  const out = await seams.collectContributions('profile.fields', { builderId: 7 });
+  assert.deepEqual(out, [{ box: { x: 1 } }, { discord: { linked: true } }]);
+  assert.deepEqual(seen, [7, 7]);
+  seams._reset();
+});
+
+test('collectContributions: skips nullish results and ISOLATES a thrower', async () => {
+  seams._reset();
+  seams.contribute('profile.fields', () => ({ a: 1 }));
+  seams.contribute('profile.fields', () => null);          // skipped
+  seams.contribute('profile.fields', () => undefined);     // skipped
+  seams.contribute('profile.fields', () => { throw new Error('boom'); }); // isolated
+  seams.contribute('profile.fields', () => ({ b: 2 }));
+  const out = await seams.collectContributions('profile.fields', {});
+  assert.deepEqual(out, [{ a: 1 }, { b: 2 }]);
+  seams._reset();
+});
+
+test('collectContributions: a non-function contribution is returned as-is', async () => {
+  seams._reset();
+  seams.contribute('static.point', { ready: true });
+  assert.deepEqual(await seams.collectContributions('static.point', {}), [{ ready: true }]);
+  seams._reset();
+});
+
+// ---- server seam: mergeContributions (add-only, core wins) ------------------
+
+test('mergeContributions: adds new keys, refuses to overwrite a core key', () => {
+  const base = { builder: { id: 1 }, discord: { linked: false } };
+  const { base: merged, collisions } = seams.mergeContributions(base, [
+    { box: { connected: true } },         // new key → added
+    { discord: { linked: true } },        // collides with a core key → ignored
+    null,                                 // ignored
+    { art: { keySet: false } },           // new key → added
+  ]);
+  assert.equal(merged, base); // mutates + returns the same object
+  assert.deepEqual(merged.box, { connected: true });
+  assert.deepEqual(merged.art, { keySet: false });
+  assert.deepEqual(merged.discord, { linked: false }); // core value preserved
+  assert.deepEqual(collisions, ['discord']);
+});
+
+test('mergeContributions: empty/absent slices leave the base byte-identical', () => {
+  const base = { builder: { id: 1 } };
+  const snapshot = JSON.stringify(base);
+  assert.deepEqual(seams.mergeContributions(base, []).collisions, []);
+  assert.deepEqual(seams.mergeContributions(base, undefined).collisions, []);
+  assert.equal(JSON.stringify(base), snapshot); // unchanged — the no-module case
+});
+
+// ---- introspection ---------------------------------------------------------
+
+test('listContributionPoints + snapshot reflect wired contributions', () => {
+  seams._reset();
+  seams.contribute('profile.fields', () => ({}));
+  seams.contribute('profile.fields', () => ({}));
+  seams.contribute('settings.things', () => ({}));
+  assert.deepEqual(seams.listContributionPoints(), ['profile.fields', 'settings.things']);
+  const snap = seams.snapshot();
+  assert.deepEqual(snap.contributions, [
+    { point: 'profile.fields', contributors: 2 },
+    { point: 'settings.things', contributors: 1 },
+  ]);
+  // contributions are independent of ports/events in the snapshot
+  assert.deepEqual(snap.ports, []);
+  assert.deepEqual(snap.events, []);
+  seams._reset();
+});
+
+// ---- browser twin: window.OTB.contributeSettingsPanel ----------------------
+// dom-utils.js is a browser IIFE (no eval-time DOM access — it only assigns
+// window.OTB at the end and reads `document` lazily inside call-time handlers),
+// so stubbing global.window is enough to exercise the panel registry in Node.
+
+test('settings-panel seam: ABSENT → empty; REGISTERED → present, sorted by order', () => {
+  global.window = {};
+  require(path.join(ROOT, 'modules', 'hall-ui', 'public', 'dom-utils.js'));
+  const OTB = global.window.OTB;
+  assert.equal(typeof OTB.contributeSettingsPanel, 'function');
+  // absent
+  assert.deepEqual(OTB.settingsPanels(), []);
+  // registered — registration order is by `order`, not insertion order
+  OTB.contributeSettingsPanel({ id: 'discord', title: 'Connections', order: 30, mount() {} });
+  OTB.contributeSettingsPanel({ id: 'dev-box', title: 'Dev box', order: 10, mount() {} });
+  const ids = OTB.settingsPanels().map((p) => p.id);
+  assert.deepEqual(ids, ['dev-box', 'discord']);
+  // a panel without id or mount() is rejected loudly
+  assert.throws(() => OTB.contributeSettingsPanel({ title: 'no id' }), /requires id \+ mount/);
+  assert.throws(() => OTB.contributeSettingsPanel({ id: 'x' }), /requires id \+ mount/);
+  delete global.window;
+});