@bongos/core 1.17.0

package/tests/module_route_rank.mjs

@@ -0,0 +1,147 @@
+// tests/module_route_rank.mjs — BV1.R44 / task 1413 (ADR 0083): the route-rank
+// invariant (src/bongos/route-rank-check.js) now ALSO covers module routes
+// (modules/<key>/routes/*.js), and recognizes the module doorway gate prefix
+// (api.requireRank, not just core's auth.requireRank). Hermetic: module routes
+// are written into a temp dir passed as modulesDir; the live (clean) core routes
+// are reused so the only findings come from the fixture. DB-free → 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 rrc = require(path.join(ROOT, 'src', 'bongos', 'route-rank-check.js'));
+
+// Write modules/<key>/routes/<file> under a fresh temp modules root; return the root.
+function modulesWith(key, file, body) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rrc-mods-'));
+  const rdir = path.join(root, key, 'routes');
+  fs.mkdirSync(rdir, { recursive: true });
+  fs.writeFileSync(path.join(rdir, file), body);
+  return root;
+}
+
+const ungatedRoute = [
+  'module.exports = () => {',
+  "  router.post('/shop/charge', h);", // NO gate → unknown → blocker (write method)
+  '  return router;',
+  '};',
+].join('\n');
+
+const gatedRoute = [
+  "const api = require('../../../src/module-api');",
+  'module.exports = () => {',
+  "  router.post('/shop/charge', api.requireRank('metic', 'archon'), h);", // doorway gate
+  '  return router;',
+  '};',
+].join('\n');
+
+// ---- the doorway (api.) prefix is recognized exactly like core's auth. ----
+test('classifyRank: api.requireRank (module doorway) classifies like auth.requireRank', () => {
+  assert.equal(rrc.classifyText("router.post('/x', api.requireRank('archon'), h);")[0].rank, 'archon');
+  assert.equal(rrc.classifyText("router.post('/x', api.requireRank('metic', 'archon'), h);")[0].rank, 'metic+archon');
+  assert.equal(rrc.classifyText("router.get('/x', api.requireBuilder, h);")[0].rank, 'any-builder');
+  assert.equal(rrc.classifyText("router.post('/x', api.requireBfgPrincipal, h);")[0].rank, 'bfg-principal');
+  // core's auth. prefix still works (no regression)
+  assert.equal(rrc.classifyText("router.post('/x', auth.requireRank('archon'), h);")[0].rank, 'archon');
+});
+
+// ---- discovery spans core + module route files ----
+test('discoverRouteFiles: finds modules/<key>/routes/*.js with a modules/ rel label, alongside core', () => {
+  const mods = modulesWith('shop', 'bag.js', ungatedRoute);
+  const found = rrc.discoverRouteFiles({ modulesDir: mods });
+  assert.ok(found.some((f) => f.rel === 'modules/shop/routes/bag.js'), 'the module route file must be discovered');
+  assert.ok(found.some((f) => f.rel.startsWith('src/bongos/routes/')), 'core route files are still discovered');
+  fs.rmSync(mods, { recursive: true, force: true });
+});
+
+// ---- the done-when: an ungated module WRITE route reds the build ----
+test('checkRouteRanks: an ungated module write route is a blocker (red build)', () => {
+  const mods = modulesWith('shop', 'bag.js', ungatedRoute);
+  const res = rrc.checkRouteRanks({ modulesDir: mods }); // live (clean) core routes + temp module
+  const f = res.findings.find((x) => x.route === 'POST /shop/charge');
+  assert.ok(f, 'an ungated module write route must surface a finding');
+  assert.equal(f.severity, 'blocker');
+  assert.equal(f.file, 'modules/shop/routes/bag.js');
+  assert.equal(res.hardFail, true);
+  fs.rmSync(mods, { recursive: true, force: true });
+});
+
+// ---- the positive side: a doorway-gated module write route is NOT flagged ----
+test('checkRouteRanks: a module write route gated via api.requireRank passes (no false positive)', () => {
+  const mods = modulesWith('shop', 'bag.js', gatedRoute);
+  const res = rrc.checkRouteRanks({ modulesDir: mods });
+  assert.ok(!res.findings.some((x) => x.route === 'POST /shop/charge'), 'a doorway-gated module write route must NOT be flagged');
+  assert.equal(res.hardFail, false, 'clean core + a properly gated module route = no hard fail');
+  fs.rmSync(mods, { recursive: true, force: true });
+});
+
+// ---- byte-identical: with no modules/ dir, the result is the core-only set ----
+test('checkRouteRanks: an absent modules/ dir leaves the core result clean (byte-identical pre-move tree)', () => {
+  const ghost = path.join(os.tmpdir(), 'rrc-no-such-modules-xyz-1413');
+  const res = rrc.checkRouteRanks({ modulesDir: ghost });
+  assert.ok(res.routeCount > 0, 'core routes still discovered');
+  assert.equal(res.findings.length, 0, 'no modules → only the (clean) core routes → zero findings');
+  assert.equal(res.hardFail, false);
+});
+
+// ---- the grade-time trigger fires on a module route change ----
+test('ROUTE_FILE_RE matches a module route path (a module route change triggers the rank pre-pass)', () => {
+  assert.match('modules/dev-box/routes/box.js', rrc.ROUTE_FILE_RE);
+  assert.match('src/bongos/routes/tasks.js', rrc.ROUTE_FILE_RE); // core still matches
+  assert.ok(!rrc.ROUTE_FILE_RE.test('modules/dev-box/module.json'), 'a non-route module file does not trigger the pre-pass');
+});
+
+// ---- a rank DRIFT on a pinned MODULE route reds the build (BV1.R61) ----
+// route_rank_check.mjs proves this for CORE pins (EXPECTED_RANKS). This proves it for
+// MODULE pins (MODULE_EXPECTED_RANKS): the goal routes live in the lifecycle module,
+// so their drift-protection only bites when that module is in scope. We synthesize a
+// lifecycle module whose routes are ALL correctly gated EXCEPT the bounded-authoring
+// keystone, silently hardened from 'any-builder' to archon — a drift the base
+// "must classify" loop waves through (archon is a KNOWN rank), so ONLY the pin catches
+// it. The executable form of "route-rank drift on a goal route is a red build".
+test('checkRouteRanks: a rank drift on a pinned goal route (lifecycle module) is a blocker', () => {
+  const pins = rrc.MODULE_EXPECTED_RANKS.lifecycle;
+  assert.ok(pins && pins['POST /goals/:id/tasks'] === 'any-builder', 'the keystone must be pinned any-builder');
+
+  const emitLines = ["const api = require('../../../src/module-api');", 'module.exports = () => {'];
+  const emit = (key, rank) => {
+    const [method, route] = key.split(' ');
+    const m = method.toLowerCase();
+    if (key === 'POST /goals/:id/tasks') {
+      // DRIFT: pinned 'any-builder', silently hardened to archon (would lock
+      // sub-Metics out of the maneuverability grant — a regression the base invariant
+      // misses because archon is still a KNOWN rank).
+      emitLines.push(`  router.${m}('${route}', api.requireRank('archon'), h);`);
+    } else if (rank === 'archon') {
+      emitLines.push(`  router.${m}('${route}', api.requireRank('archon'), h);`);
+    } else if (rank === 'metic+archon') {
+      emitLines.push(`  router.${m}('${route}', api.requireRank('metic', 'archon'), h);`);
+    } else { // any-builder
+      emitLines.push(`  router.${m}('${route}', api.requireBuilder, h);`);
+    }
+    emitLines.push('  });', '', '', '', '', '', ''); // gap: keeps the 20-line lookahead off a neighbour's gate
+  };
+  // Emit every lifecycle pin at its EXPECTED rank, keystone LAST (downgraded) so
+  // nothing with requireRank('archon') sits inside its lookahead window.
+  for (const [key, rank] of Object.entries(pins)) if (key !== 'POST /goals/:id/tasks') emit(key, rank);
+  emit('POST /goals/:id/tasks', pins['POST /goals/:id/tasks']);
+  emitLines.push('  return router;', '};');
+
+  const mods = modulesWith('lifecycle', 'goals.js', emitLines.join('\n'));
+  const res = rrc.checkRouteRanks({ modulesDir: mods });
+  fs.rmSync(mods, { recursive: true, force: true });
+
+  const drift = res.findings.find((f) => f.route === 'POST /goals/:id/tasks');
+  assert.ok(drift, 'a drifted pinned goal route must surface a finding');
+  assert.equal(drift.rank, 'archon', 'the drifted route classifies as the WRONG (archon) rank');
+  assert.equal(drift.severity, 'blocker', 'a rank drift on the enforcement keystone is a hard fail');
+  assert.equal(res.hardFail, true, 'the build must go red');
+  // No missing-pin noise: every OTHER lifecycle pin was emitted at its expected rank,
+  // so the keystone drift is isolated (a '(missing)' finding would mean the emit is stale).
+  assert.ok(!res.findings.some((f) => f.rank === '(missing)'), 'all pins present; this is a drift, not a vanish');
+});

package/tests/module_seams.mjs

@@ -0,0 +1,68 @@
+// tests/module_seams.mjs — seam registry hardening (BV1.R39 / task 1408, ADR 0083):
+// boot-time port verification + async event fan-out. (The core register/resolve/
+// emit/on round-trips are covered in tests/module_api.mjs, shipped with the doorway.)
+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'));
+
+test('verifyPortsSatisfied: ok when every consumed port is provided', () => {
+  const manifests = [
+    { key: 'economy', provides: ['reward'], consumes: [] },
+    { key: 'grading', provides: ['grade'], consumes: [] },
+    { key: 'lifecycle', provides: [], consumes: ['reward', 'grade'] },
+  ];
+  const r = seams.verifyPortsSatisfied(manifests);
+  assert.equal(r.ok, true, r.errors.join('; '));
+});
+
+test('verifyPortsSatisfied: flags a consumed port with no provider', () => {
+  const r = seams.verifyPortsSatisfied([
+    { key: 'lifecycle', provides: [], consumes: ['reward'] },
+  ]);
+  assert.equal(r.ok, false);
+  assert.match(r.errors[0], /consumes port "reward" but no enabled module provides it/);
+});
+
+test('verifyPortsSatisfied: flags a port with two providers', () => {
+  const r = seams.verifyPortsSatisfied([
+    { key: 'a', provides: ['reward'], consumes: [] },
+    { key: 'b', provides: ['reward'], consumes: [] },
+  ]);
+  assert.equal(r.ok, false);
+  assert.match(r.errors.join('\n'), /provided by more than one enabled module/);
+});
+
+test('verifyPortsSatisfied: empty / no-port manifests are ok', () => {
+  assert.equal(seams.verifyPortsSatisfied([]).ok, true);
+  assert.equal(seams.verifyPortsSatisfied([{ key: 'x', provides: [], consumes: [] }]).ok, true);
+});
+
+test('emitAsync: awaits async listeners and isolates a rejecting one', async () => {
+  seams._reset();
+  const order = [];
+  seams.on('shipped', async (p) => { await Promise.resolve(); order.push(`a:${p}`); });
+  seams.on('shipped', async () => { throw new Error('async boom'); }); // isolated
+  seams.on('shipped', async (p) => { await Promise.resolve(); order.push(`c:${p}`); });
+  const invoked = await seams.emitAsync('shipped', 9);
+  assert.equal(invoked, 3);
+  assert.deepEqual(order, ['a:9', 'c:9']);
+  assert.equal(await seams.emitAsync('nobody', 1), 0);
+  seams._reset();
+});
+
+test('snapshot reflects wired ports + event listeners', () => {
+  seams._reset();
+  seams.registerProvider('reward', () => 1);
+  seams.on('shipped', () => {});
+  seams.on('shipped', () => {});
+  const snap = seams.snapshot();
+  assert.deepEqual(snap.ports, ['reward']);
+  assert.deepEqual(snap.events, [{ event: 'shipped', listeners: 2 }]);
+  seams._reset();
+});

package/tests/modules.mjs

@@ -0,0 +1,156 @@
+// tests/modules.mjs — the feature-module selection resolver (task 1193 / V4.R54, ADR 0062 §4).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import modulesMod from '../src/modules.js';
+
+const {
+  resolveModules, isModuleEnabled, enabledModules, enabledDisciplines, clientModules,
+  KNOWN_MODULES, MODULE_REGISTRY, loadModules,
+} = modulesMod;
+
+const VANILLA = {}; // no config at all
+const OTB = { modules: { game: true, 'art-pipeline': true, discord: true, 'dev-box': true } };
+// The post-extraction registry: built-ins (game, art-pipeline, discord) + every
+// discovered module. dev-box now lives in modules/dev-box/ (BV1.R43), so it is a
+// DISCOVERED key, not a built-in MODULE_REGISTRY one. The pure resolver tests
+// below pass this effective registry so 'dev-box' is a known key — exactly what
+// loadModules() does in production. Membership across the move is preserved here.
+const EFFECTIVE = modulesMod.effectiveRegistry();
+
+test('vanilla (no config) resolves every module OFF — fail-to-vanilla, never fail-to-OTB', () => {
+  const m = resolveModules({});
+  for (const k of KNOWN_MODULES) assert.equal(m[k], false, `${k} should default off`);
+  assert.deepEqual(enabledModules(m), []);
+});
+
+test('every registry module has an explicit default of false', () => {
+  for (const k of KNOWN_MODULES) assert.equal(MODULE_REGISTRY[k].default, false);
+});
+
+test('instance config turns modules on', () => {
+  const m = resolveModules({ neutral: VANILLA, instance: OTB, registry: EFFECTIVE });
+  assert.equal(m.game, true);
+  assert.equal(m['dev-box'], true);
+  assert.equal(isModuleEnabled('discord', m), true);
+  // memory (BV1.R72), grading (BV1.R73), economy (BV1.R77), ideas (BV1.R78),
+  // security (BV1.R79), builder-settings (BV1.R80), onboarding (BV1.R81),
+  // sessions (BV1.R82), autonomy (BV1.R83), status-ui (BV1.R84), and hall-ui
+  // (BV1.R85) are CORE-domain modules (ADR 0091/0093): unlike the opt-in feature
+  // modules, their manifests are `default: true`, so they resolve ON even though
+  // the OTB instance config doesn't list them (the build system's memory + quality
+  // gate + builder economy + idea inbox + red-team intake + prefs + onboarding +
+  // session corpus + the MAS autonomy machinery + the status dashboard + the
+  // builders' hall ship to every instance — see each module.json).
+  assert.deepEqual(enabledModules(m).sort(), ['art-pipeline', 'autonomy', 'builder-settings', 'dev-box', 'discord', 'economy', 'game', 'grading', 'hall-ui', 'ideas', 'lifecycle', 'memory', 'onboarding', 'security', 'sessions', 'status-ui']);
+});
+
+test('instance config overrides the neutral starter per-flag (deep merge of the modules map)', () => {
+  const neutral = { modules: { game: false, discord: false, 'dev-box': false, 'art-pipeline': false } };
+  const instance = { modules: { discord: true } }; // only flip one
+  const m = resolveModules({ neutral, instance, registry: EFFECTIVE });
+  assert.equal(m.discord, true);
+  assert.equal(m.game, false); // neutral value survives
+});
+
+test('env override beats instance config (precedence), with prefix + snake-casing', () => {
+  const m = resolveModules({ instance: OTB, env: { OTB_MODULE_DEV_BOX: '0' }, envPrefix: 'OTB', registry: EFFECTIVE });
+  assert.equal(m['dev-box'], false); // env off beat instance on
+  assert.equal(m.game, true);        // others untouched
+});
+
+// env-override parsing is exercised against an explicit registry: the built-in
+// MODULE_REGISTRY is now empty (every module — incl. game, BV1.R49 — lives on disk
+// and is injected via the effective registry), so resolveModules only honors an
+// env override for a key the passed registry KNOWS. Supply one with `game`.
+const GAME_REG = { game: { default: false } };
+
+test('env override accepts on/off/true/false/1/0 spellings', () => {
+  for (const v of ['on', 'true', '1', 'yes', 'enabled']) {
+    assert.equal(resolveModules({ env: { CLOUDBONGOS_MODULE_GAME: v }, registry: GAME_REG }).game, true, `${v} -> true`);
+  }
+  for (const v of ['off', 'false', '0', 'no', 'disabled']) {
+    assert.equal(resolveModules({ env: { CLOUDBONGOS_MODULE_GAME: v }, registry: GAME_REG }).game, false, `${v} -> false`);
+  }
+});
+
+test('a garbage env value is rejected loudly (not silently coerced)', () => {
+  assert.throws(() => resolveModules({ env: { CLOUDBONGOS_MODULE_GAME: 'maybe' }, registry: GAME_REG }), /not a boolean/);
+});
+
+test('an unknown module key in config is rejected when ENABLED (typo guard)', () => {
+  assert.throws(() => resolveModules({ instance: { modules: { gaem: true } } }), /unknown module "gaem"/);
+});
+
+// task 1824 — a stripped CORE has no game/art-pipeline/discord/dev-box, but the
+// config/modules.neutral.json that SHIPS with it names them (so the same file is valid
+// in the full repo). The loader must TOLERATE an unknown module when it is DISABLED, or
+// a vanilla self-host crashes on `unknown module "game"`.
+test('an unknown module key that is DISABLED is tolerated (a config may name a not-yet-installed module)', () => {
+  const reg = { memory: { default: true }, grading: { default: true } }; // core-only registry (no feature modules)
+  // The exact vanilla-core scenario: neutral names four absent feature modules, all off.
+  const neutral = { modules: { game: false, 'art-pipeline': false, discord: false, 'dev-box': false } };
+  let m;
+  assert.doesNotThrow(() => { m = resolveModules({ neutral, registry: reg }); });
+  assert.deepEqual(m, { memory: true, grading: true }); // core modules resolve; absent-disabled dropped
+});
+
+test('a DISABLED-but-absent module still throws if someone tries to ENABLE it', () => {
+  const reg = { memory: { default: true } };
+  assert.throws(
+    () => resolveModules({ instance: { modules: { game: true } }, registry: reg }),
+    /cannot enable unknown module "game"/,
+  );
+});
+
+test('isModuleEnabled throws on an unknown module name (programmer error)', () => {
+  assert.throws(() => isModuleEnabled('nope', resolveModules({})), /unknown module/);
+});
+
+test('disciplines: vanilla offers engineer + ideator (core); art-pipeline adds artist (R59)', () => {
+  // Ideation is methodology core (idea_inbox / capture / triage ship to every
+  // instance), so it is offered with no modules on; only 'artist' is module-gated.
+  // art-pipeline is now a DISCOVERED module (BV1.R48), so pass EFFECTIVE registry.
+  assert.deepEqual(enabledDisciplines(resolveModules({})), ['engineer', 'ideator']);
+  const m = resolveModules({ instance: { modules: { 'art-pipeline': true } }, registry: EFFECTIVE });
+  assert.deepEqual(enabledDisciplines(m), ['engineer', 'ideator', 'artist']);
+});
+
+test('clientModules is a safe boolean projection covering every known module + disciplines', () => {
+  const c = clientModules(resolveModules({ instance: OTB, registry: EFFECTIVE }));
+  for (const k of KNOWN_MODULES) assert.equal(typeof c.enabled[k], 'boolean');
+  assert.ok(Array.isArray(c.disciplines));
+  assert.ok(c.disciplines.includes('engineer'));
+});
+
+test('the resolved set is frozen (callers cannot mutate the singleton)', () => {
+  const m = resolveModules({ instance: OTB, registry: EFFECTIVE });
+  assert.throws(() => { m.game = false; }, TypeError);
+});
+
+test('the committed config files resolve: OTB enables all four, on disk', () => {
+  // loadModules reads config/modules.json over config/modules.neutral.json.
+  // No GDS_BRANDING_FILE → still the default OTB instance pack (regression guard
+  // for the GDS_MODULES_FILE selector below).
+  const m = loadModules({ env: {} });
+  assert.equal(m.game, true);
+  assert.equal(m['art-pipeline'], true);
+  assert.equal(m.discord, true);
+  assert.equal(m['dev-box'], true);
+});
+
+test('GDS_MODULES_FILE selects the instance modules pack on disk (mirrors GDS_BRANDING_FILE)', () => {
+  // Point explicitly at the neutral pack; it must win over the committed
+  // config/modules.json (which enables all four).
+  const m = loadModules({ env: { GDS_MODULES_FILE: 'config/modules.neutral.json' } });
+  for (const k of KNOWN_MODULES) assert.equal(m[k], false, `${k} should be off when GDS_MODULES_FILE → neutral`);
+});
+
+test('a branded sibling (GDS_BRANDING_FILE set, no GDS_MODULES_FILE) defaults to NEUTRAL, not OTB-all-on', () => {
+  // Regression for the cloudbongos.com bug (CB-V1 task 1, C8 proof): the vanilla
+  // Customer-0 process sets GDS_BRANDING_FILE but, lacking a modules selector,
+  // silently inherited OTB's config/modules.json → advertised all four modules ON.
+  // A non-default brand must fall through to the neutral (all-off) module set.
+  const m = loadModules({ env: { GDS_BRANDING_FILE: 'config/branding.cloudbongos.json' } });
+  for (const k of KNOWN_MODULES) assert.equal(m[k], false, `${k} must be off for a branded sibling`);
+  assert.deepEqual(enabledDisciplines(m), ['engineer', 'ideator']);
+});

package/tests/modules_route.mjs

@@ -0,0 +1,38 @@
+// tests/modules_route.mjs — the hall "Modules" tab backend (ADR 0107 §9,
+// task 1776). listModules() is fs-only (the loader's disk scan + branding
+// read, no DB), so it's safe to exercise directly against the real repo tree —
+// the same shape tests/modules.mjs and tests/atlas.mjs already rely on.
+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 { listModules } = require(path.join(ROOT, 'src', 'bongos', 'routes', 'modules.js'));
+
+test('listModules: every on-disk module is present, sorted, and well-formed', () => {
+  const rows = listModules();
+  assert.ok(rows.length >= 18, `expected every on-disk module (got ${rows.length})`);
+  for (const m of rows) {
+    assert.equal(typeof m.key, 'string');
+    assert.ok(['own', 'core'].includes(m.provenance), `${m.key}: provenance is own|core`);
+    assert.equal(typeof m.enabled, 'boolean');
+  }
+  const keys = rows.map((m) => m.key);
+  assert.deepEqual(keys, [...keys].sort(), 'listModules is sorted by key');
+});
+
+test('listModules: today, every module is own-built (ADR 0107 audit — no module names a foreign origin yet)', () => {
+  const rows = listModules();
+  for (const m of rows) assert.equal(m.provenance, 'own', `${m.key} unexpectedly classifies core-loaded`);
+});
+
+test('listModules: game module is on-disk, enabled in the OTB instance config, and carries no origin', () => {
+  const rows = listModules();
+  const game = rows.find((m) => m.key === 'game');
+  assert.ok(game, 'game module discovered');
+  assert.equal(game.enabled, true);
+  assert.equal(game.origin, null);
+});

package/tests/newcomer_floor.mjs

@@ -0,0 +1,17 @@
+// tests/newcomer_floor.mjs
+//
+// CI shim (task 1158): run-unit-tests.js only scans tests/*.mjs, so the
+// newcomer-floor replenisher's pure-helper suite (deficit math, monotonic
+// per-instance seq, template->copy scope-clamp, real templates.json integrity)
+// would never run in the gate. This requires the co-located suite so it does.
+//
+// DB-free: the helpers are pure and loadTemplates() reads only the committed
+// newcomer-floor.templates.json — no network, no Postgres. Belongs in the unit
+// gate (NOT the integration set).
+//
+// Run:  node tests/newcomer_floor.mjs
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+// Executing the co-located test runs every assertion; it process.exit(1)s on the
+// first failure and prints a success line otherwise — exactly the gate contract.
+require('../scripts/gds/newcomer-floor.test.js');

package/tests/newcomer_restock.mjs

@@ -0,0 +1,80 @@
+// tests/newcomer_restock.mjs
+//
+// Pure-helper + skip-path tests for the on-claim newcomer-chore restock
+// (src/bongos/newcomer-restock.js, task 1168). DB-free: requiring the module loads
+// db.js (its pg pool is lazy — no connection on import), and every assertion
+// below exercises either a pure helper or the restockForClaim SKIP path, which
+// returns before any query. The DB-touching restock is verified functionally
+// post-deploy, not here.
+//
+// Run:  node tests/newcomer_restock.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const r = require('../modules/onboarding/newcomer-restock.js');
+
+let passed = 0;
+function t(name, fn) {
+  try { fn(); passed += 1; console.log(`  PASS  ${name}`); }
+  catch (e) { console.log(`  FAIL  ${name}\n        ${e.message}`); process.exit(1); }
+}
+
+// ---- parseSeq ----
+t('parseSeq: matches discipline+template, rejects others', () => {
+  assert.equal(r.parseSeq('tmpl:engineer:docs-hygiene-pass:5', 'engineer', 'docs-hygiene-pass'), 5);
+  assert.equal(r.parseSeq('tmpl:engineer:docs-hygiene-pass:5', 'artist', 'docs-hygiene-pass'), null);
+  assert.equal(r.parseSeq('tmpl:engineer:other:5', 'engineer', 'docs-hygiene-pass'), null);
+  assert.equal(r.parseSeq('manual:engineer:x', 'engineer', 'docs-hygiene-pass'), null);
+  assert.equal(r.parseSeq('tmpl:engineer:docs-hygiene-pass:nope', 'engineer', 'docs-hygiene-pass'), null);
+});
+
+// ---- buildDescription ----
+t('buildDescription: folds done-when + "always one waiting" footer', () => {
+  const d = r.buildDescription({ description: 'Body.', done_when: ['x', 'y'] });
+  assert.ok(d.includes('Body.'));
+  assert.ok(d.includes('**Done when:**') && d.includes('- x') && d.includes('- y'));
+  assert.ok(d.includes('there is always one waiting'), 'restock footer present');
+});
+
+// ---- templateIdFromRef ----
+t('templateIdFromRef: extracts the template_id, honouring the discipline', () => {
+  assert.equal(r.templateIdFromRef('tmpl:engineer:unit-test-pass:3', 'engineer'), 'unit-test-pass');
+  assert.equal(r.templateIdFromRef('tmpl:engineer:unit-test-pass:3', 'artist'), null, 'discipline mismatch');
+  assert.equal(r.templateIdFromRef('manual:engineer:x', 'engineer'), null, 'non-chore ref');
+  assert.equal(r.templateIdFromRef('tmpl:engineer:unit-test-pass', 'engineer'), null, 'too few parts');
+});
+
+// ---- loadTemplates: real templates.json (per-discipline LIST since task 1488) ----
+t('loadTemplates: real file is a per-discipline list of valid chores', () => {
+  const tmpl = r.loadTemplates();
+  for (const disc of ['engineer', 'artist', 'ideator']) {
+    assert.ok(Array.isArray(tmpl[disc]) && tmpl[disc].length >= 1, `${disc} is a non-empty list`);
+    for (const c of tmpl[disc]) {
+      assert.ok(c.template_id && c.version_id && c.title, `${disc}/${c.template_id || '?'} has id/version/title`);
+    }
+  }
+  const engIds = tmpl.engineer.map((c) => c.template_id);
+  assert.ok(engIds.includes('unit-test-pass') && engIds.includes('docs-hygiene-pass'),
+    `engineer offers the unit-test chore + the docs sweep (got ${engIds.join(', ')})`);
+});
+
+// ---- loadFloors: real config, floor >= 2 so one is always left on claim ----
+t('loadFloors: real config keeps floor >= 2 per discipline (a spare on every claim)', () => {
+  const f = r.loadFloors();
+  for (const disc of ['engineer', 'artist', 'ideator']) {
+    assert.ok(f[disc] >= 2, `${disc} floor ${f[disc]} must be >= 2 so one remains the instant one is claimed`);
+  }
+});
+
+// ---- restockForClaim: skip path is DB-free (awaited) ----
+// (returns an array of per-template results; the skip path is a 1-element array.)
+assert.deepEqual(await r.restockForClaim(null), [{ skipped: true }]);
+assert.deepEqual(await r.restockForClaim({ source: 'auto-newcomer-floor-ai', discipline: 'engineer' }), [{ skipped: true }]);
+assert.deepEqual(await r.restockForClaim({ source: 'newcomer-floor-manual', discipline: 'artist' }), [{ skipped: true }]);
+assert.deepEqual(await r.restockForClaim({ source: 'newcomer-template', discipline: 'bogus' }), [{ skipped: true }]);
+passed += 1;
+console.log('  PASS  restockForClaim: non-chore tasks skipped without touching the DB');
+
+console.log(`\n✓ all ${passed} newcomer-restock tests passed`);