@bongos/core 1.18.0 → 1.18.18

package/tests/instance_config.mjs

@@ -74,3 +74,68 @@ test('resolveDocsRoot: the explicit instance root when set, else coreRoot (no-op
   assert.equal(resolveDocsRoot({ env: { CLOUDBONGOS_INSTANCE_ROOT: '/srv/consumer' } }), path.resolve('/srv/consumer'), 'consumer writes into its own repo');
   assert.equal(resolveDocsRoot({ env: {} }), resolveCoreRoot(), 'single checkout: coincides with coreRoot');
 });
+
+// ---------------------------------------------------------------------------
+// resolveApiBase — the ONE session-aware CLI base resolution (task 1002427).
+//
+// Regression fixture for a bug that locked a builder out of re-authenticating.
+// Three call sites resolved the API base three different ways and none reached
+// the instance the builder was actually signed into:
+//   * paste-token.js hardcoded 'https://amazonprimea.com' (a straggler the task
+//     1002201 sweep missed), so a token minted by cloudbongos.com was verified
+//     against the founder's host and rejected 401 — a VALID token, wrong host.
+//   * reauth.js used the module-level branding default, so it printed a
+//     localhost:3000 click-path to a builder signed into cloudbongos.com.
+//   * cliClient() alone had it right (env -> session.api_base -> default).
+// The session file knew the answer the whole time. This locks the order in.
+// ---------------------------------------------------------------------------
+
+const BRAND_B = { domains: { publicOrigin: 'https://instance-b.example' } };
+
+test('resolveApiBase: the persisted session beats the branding default', () => {
+  // THE regression. A builder authenticated against instance A must keep hitting
+  // A even when this checkout's own branding names B.
+  assert.equal(
+    ic.resolveApiBase({
+      session: { api_base: 'https://instance-a.example' },
+      env: {},
+      b: BRAND_B,
+    }),
+    'https://instance-a.example'
+  );
+});
+
+test('resolveApiBase: an explicit env override beats the session', () => {
+  assert.equal(
+    ic.resolveApiBase({
+      session: { api_base: 'https://instance-a.example' },
+      env: { CLOUDBONGOS_API_BASE: 'http://localhost:3000' },
+      b: BRAND_B,
+    }),
+    'http://localhost:3000'
+  );
+});
+
+test('resolveApiBase: falls back to the branding default with no env and no session', () => {
+  assert.equal(
+    ic.resolveApiBase({ session: null, env: {}, b: BRAND_B }),
+    'https://instance-b.example'
+  );
+});
+
+test('resolveApiBase: a session without a usable api_base falls back, never returns empty', () => {
+  for (const session of [{}, { api_base: '' }, { api_base: '   ' }, { api_base: 42 }]) {
+    assert.equal(
+      ic.resolveApiBase({ session, env: {}, b: BRAND_B }),
+      'https://instance-b.example',
+      `session ${JSON.stringify(session)} must fall back to the branding default`
+    );
+  }
+});
+
+test('resolveApiBase: session:null does not read the session file from disk', () => {
+  // Passing null explicitly means "no session" — the resolver must honour that
+  // rather than falling back to a disk read, so this test stays pure/hermetic
+  // and callers that already know there is no session get a deterministic answer.
+  assert.equal(ic.resolveApiBase({ session: null, env: {}, b: BRAND_B }), 'https://instance-b.example');
+});

package/tests/instance_mismatch_guard.mjs

@@ -27,6 +27,8 @@ function test(name, fn) {
 const DEMO = { domains: { publicOrigin: 'https://demo.cloudbongos.com' } };
 const OTB = { domains: { publicOrigin: 'https://amazonprimea.com' } };
 const noEnv = {}; // no <PREFIX>_API_BASE override in scope
+const branded = () => true;  // simulate a checkout that HAS config/branding.json (a declared instance)
+const neutral = () => false; // simulate a NEUTRAL checkout (portable core — no config/branding.json)
 
 test('instanceOriginHost: extracts host, tolerates trailing slash', () => {
   assert.equal(cli.instanceOriginHost('https://amazonprimea.com'), 'amazonprimea.com');
@@ -41,24 +43,24 @@ test('instanceOriginHost: unparseable input → null (edge)', () => {
 });
 
 test('match: same-host session + branding → no mismatch (the OTB/normal case)', () => {
-  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: OTB, env: noEnv });
+  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: OTB, env: noEnv, hasInstanceConfig: branded });
   assert.equal(r.mismatch, false);
 });
 
 test('match: scheme/trailing-slash differences still match on host', () => {
-  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com/' }, brand: OTB, env: noEnv });
+  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com/' }, brand: OTB, env: noEnv, hasInstanceConfig: branded });
   assert.equal(r.mismatch, false);
 });
 
 test('mismatch: demo repo + founder amazonprimea session → REFUSE (the reported failure)', () => {
-  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: DEMO, env: noEnv });
+  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: DEMO, env: noEnv, hasInstanceConfig: branded });
   assert.equal(r.mismatch, true);
   assert.equal(r.expected, 'https://demo.cloudbongos.com');
   assert.equal(r.actual, 'https://amazonprimea.com');
 });
 
 test('mismatch: demo repo + cloudbongos.com session (sibling instance) → REFUSE', () => {
-  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://cloudbongos.com' }, brand: DEMO, env: noEnv });
+  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://cloudbongos.com' }, brand: DEMO, env: noEnv, hasInstanceConfig: branded });
   assert.equal(r.mismatch, true);
 });
 
@@ -71,8 +73,23 @@ test('env-override: an explicit *_API_BASE override wins (dev/staging) → no mi
 });
 
 test('no-branding: repo declares no publicOrigin → cannot assert a mismatch → no mismatch', () => {
-  assert.equal(cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: {}, env: noEnv }).mismatch, false);
-  assert.equal(cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: { domains: {} }, env: noEnv }).mismatch, false);
+  assert.equal(cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: {}, env: noEnv, hasInstanceConfig: branded }).mismatch, false);
+  assert.equal(cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: { domains: {} }, env: noEnv, hasInstanceConfig: branded }).mismatch, false);
+});
+
+test('NEUTRAL checkout (no config/branding.json) → trust the session, NO mismatch (task 1002399)', () => {
+  // A neutral core checkout signed into a real instance: even though the resolved
+  // brand host would differ from the session host, there is no declared instance to
+  // enforce, so the guard must NOT fire. This is exactly what lets a neutral checkout
+  // run /builder-* with no <PREFIX>_API_BASE prefix.
+  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://cloudbongos.com' }, brand: OTB, env: noEnv, hasInstanceConfig: neutral });
+  assert.equal(r.mismatch, false);
+});
+
+test('neutral guard is precedence-safe: env override still wins even when neutral', () => {
+  // env override short-circuits before the neutral check — order-independent.
+  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: DEMO, env: { GDS_API_BASE: 'http://localhost:3000' }, hasInstanceConfig: neutral });
+  assert.equal(r.mismatch, false);
 });
 
 test('no-session: nothing to borrow → no mismatch (the no-session/401 path handles it)', () => {

package/tests/instance_release_config.mjs

@@ -0,0 +1,104 @@
+// tests/instance_release_config.mjs
+//
+// serve-internal mounts /downloads/devbox/* and /downloads/bongos/* only when the
+// instance ships the matching RELEASE config (config/devbox-app.json,
+// config/bongos-cli.json). Those configs are boundary-EXCLUDED from the packaged core,
+// so they live at the INSTANCE root — which on a vendored instance (@bongos/core in
+// node_modules, ADR 0108) is a DIFFERENT directory from the core package dir
+// serve-internal.js sits in. The old core-relative `require('../../config/…')` looked
+// only in node_modules/@bongos/core/config/, so a vendored instance's Dev Box download
+// routes never mounted (task 1002371; ADR 0145 papered over it by copying the config
+// into node_modules — lost on the next npm ci). Same class as ADR 0144's vendored
+// infra/ path bug.
+//
+// The first test is THE regression: a config present ONLY at the instance root must be
+// found. It fails against the old resolution (which could not see the instance root at
+// all) and passes against the instance-root-first ladder.
+//
+// serve-internal is DB-free (the pg pool connects lazily), so the end-to-end case mounts
+// it on a throwaway express app over loopback — same pattern as tests/docs_openapi_route.mjs.
+//
+// Run:  node --test tests/instance_release_config.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+// A minimal but VALID release config — buildDevboxDownloads rejects a bad
+// releases_repo/version at boot, so the end-to-end mount below proves real parsing.
+const DEVBOX_CFG = {
+  releases_repo: 'example-owner/example-devbox',
+  version: '9.9.9',
+  assets: { 'mac-arm64': 'Example-Dev-Box-9.9.9-arm64.dmg' },
+  aliases: { mac: 'mac-arm64' },
+};
+
+// Write config/<name> under a fresh temp dir and return the dir (a stand-in root).
+function makeRoot(name, contents) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-root-'));
+  if (name) {
+    fs.mkdirSync(path.join(dir, 'config'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'config', name), contents);
+  }
+  return dir;
+}
+
+// Point the process at a temp INSTANCE root BEFORE serve-internal loads, so the default
+// (uninjected) resolution runs the vendored shape: config at the instance root, absent
+// from the core package dir. This checkout ships no config/devbox-app.json — it is
+// instance-only — so the core tier genuinely has nothing to find, exactly like a
+// freshly-vendored box.
+const INSTANCE_ROOT = makeRoot('devbox-app.json', JSON.stringify(DEVBOX_CFG));
+process.env.CLOUDBONGOS_INSTANCE_ROOT = INSTANCE_ROOT;
+const { tryLoadInstanceConfig, mountInternalSurfaces } = require('../src/bongos/serve-internal.js');
+
+test('finds a release config that exists ONLY at the instance root (the vendored bug)', () => {
+  const instance = makeRoot('devbox-app.json', '{"version":"1.0.0"}');
+  const core = makeRoot(null);
+  assert.deepEqual(tryLoadInstanceConfig('devbox-app.json', [instance, core]), { version: '1.0.0' });
+});
+
+test('the instance root wins over the core package dir when both carry a copy', () => {
+  const instance = makeRoot('devbox-app.json', '{"from":"instance"}');
+  const core = makeRoot('devbox-app.json', '{"from":"core"}');
+  assert.equal(tryLoadInstanceConfig('devbox-app.json', [instance, core]).from, 'instance');
+});
+
+test('falls back to the core package dir (single checkout + the copied-in workaround)', () => {
+  const instance = makeRoot(null);
+  const core = makeRoot('bongos-cli.json', '{"from":"core"}');
+  assert.equal(tryLoadInstanceConfig('bongos-cli.json', [instance, core]).from, 'core');
+});
+
+test('absent from every root → null, so the download surface just does not mount', () => {
+  assert.equal(tryLoadInstanceConfig('devbox-app.json', [makeRoot(null), makeRoot(null)]), null);
+  assert.equal(tryLoadInstanceConfig('devbox-app.json', []), null);
+});
+
+test('a MALFORMED config still throws — only a MISSING file is tolerated', () => {
+  const bad = makeRoot('devbox-app.json', '{ this is not valid json ');
+  assert.throws(() => tryLoadInstanceConfig('devbox-app.json', [bad]), SyntaxError);
+});
+
+test('/downloads/devbox/version mounts from an INSTANCE-root config (end to end)', async () => {
+  const express = require('express');
+  const app = express();
+  mountInternalSurfaces(app);
+  const server = await new Promise((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  try {
+    const res = await fetch(`http://127.0.0.1:${server.address().port}/downloads/devbox/version`);
+    assert.equal(res.status, 200, 'the route must mount when only the INSTANCE root has the config');
+    const body = await res.json();
+    assert.equal(body.version, DEVBOX_CFG.version);
+    assert.match(body.assets['mac-arm64'], /^https:\/\/github\.com\/example-owner\/example-devbox\//);
+  } finally {
+    await new Promise((r) => server.close(r));
+  }
+});

package/tests/linkify_refs.mjs

@@ -252,12 +252,25 @@ t('a known idea link is never unwrapped by the past-mislink pass', () => {
   assert.equal(runIds(s, ids), s);
 });
 
-t('discoverDocs finds CLAUDE.md + session logs, only .md, skips the generated ideas file', () => {
+t('discoverDocs finds CLAUDE.md, recurses docs/ subdirs (only .md), skips the generated ideas file', () => {
   const docs = discoverDocs();
   assert.ok(docs.includes('CLAUDE.md'), 'includes CLAUDE.md');
-  assert.ok(docs.some((d) => d.startsWith('docs/session-logs/')), 'includes session logs');
   assert.ok(docs.every((d) => d.endsWith('.md')), 'only markdown files');
   assert.ok(!docs.includes('generative-ideas.md'), 'excludes the generated ideas file');
+  // Recurses into docs/ subdirectories. docs/adr/*.md is the always-present nested
+  // case; assert recursion against it (task 1002234). Session logs are the canonical
+  // nested example the linkifier targets, but the neutral core carries none (they're
+  // instance-specific / not committed), so that stricter check is conditional — it
+  // still verifies them on an instance whose docs/session-logs/ is populated.
+  assert.ok(docs.some((d) => d.startsWith('docs/') && d.split('/').length >= 3),
+    'recurses into docs/ subdirectories (e.g. docs/adr/*.md)');
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const logsDir = path.resolve(process.cwd(), 'docs/session-logs');
+  const hasSessionLogMd = fs.existsSync(logsDir) && fs.readdirSync(logsDir).some((f) => f.endsWith('.md'));
+  if (hasSessionLogMd) {
+    assert.ok(docs.some((d) => d.startsWith('docs/session-logs/')), 'includes session logs when present');
+  }
 });
 
 console.log(`\nlinkify_refs: ${passed} passed, ${failed} failed`);

package/tests/migrations_forward_safe.mjs

@@ -0,0 +1,86 @@
+// tests/migrations_forward_safe.mjs
+//
+// task 1002223 / audit H10 (finding F6) — the FAIL-CLOSED forward-safety gate for core migrations.
+// `bongos upgrade` auto-rollback reverts the code pin but NOT the DB, so a core migration must be
+// forward-safe (old code still runs on the new schema) — or explicitly acknowledge the exception
+// with a `-- forward-unsafe: <reason>` pragma. This runs in the DB-free unit gate every PR: add a
+// DROP COLUMN / RENAME / ALTER TYPE without the pragma and this REDs, long before a field rollback
+// strands old code on new schema. (The migrate.sh notice is advisory; THIS is the enforcement.)
+//
+// Run:  node tests/migrations_forward_safe.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const lint = require('../scripts/gds/lint-migrations.js');
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ---- THE GATE: the committed core migrations must be forward-safe (or acknowledged) ----
+t('core migrations: zero UNACKNOWLEDGED forward-unsafe operations', () => {
+  const { violations, acknowledged, scanned } = lint.scanMigrationsDir(join(REPO_ROOT, 'migrations'));
+  assert.ok(scanned > 0, 'expected to scan some core migrations');
+  assert.equal(violations.length, 0,
+    `unacknowledged forward-unsafe migration(s): ${violations.map((v) => `${v.file} [${v.unsafe.join(',')}]`).join('; ')}\n`
+    + '        Add a top-of-file `-- forward-unsafe: <reason>` comment if the operation is intentional + safe here.');
+  // sanity: the two known historical exceptions stay acknowledged (not silently dropped)
+  assert.ok(acknowledged.some((a) => a.file.startsWith('039_')), 'expected 039 to remain an acknowledged exception');
+  assert.ok(acknowledged.some((a) => a.file.startsWith('102_')), 'expected 102 to remain an acknowledged exception');
+});
+
+// ---- the scanner classifies operations correctly ----
+t('scanMigrationSql: flags each genuinely forward-unsafe operation', () => {
+  const cases = {
+    'drop-table': 'DROP TABLE widgets;',
+    'drop-column': 'ALTER TABLE t DROP COLUMN c;',
+    'rename-column': 'ALTER TABLE t RENAME COLUMN a TO b;',
+    'rename-table': 'ALTER TABLE t RENAME TO t2;',
+    'alter-column-type': 'ALTER TABLE t ALTER COLUMN c TYPE bigint;',
+    'set-not-null': 'ALTER TABLE t ALTER COLUMN c SET NOT NULL;',
+  };
+  for (const [expected, sql] of Object.entries(cases)) {
+    const r = lint.scanMigrationSql(sql);
+    assert.ok(r.unsafe.includes(expected), `expected ${expected} for: ${sql} — got ${JSON.stringify(r.unsafe)}`);
+  }
+});
+
+t('scanMigrationSql: does NOT flag additive / recreate-in-place operations', () => {
+  const safe = [
+    'CREATE TABLE t (id int);',
+    'ALTER TABLE t ADD COLUMN c text;',
+    'CREATE INDEX idx ON t (c);',
+    'DROP INDEX IF EXISTS idx; CREATE INDEX idx ON t (c);',       // recreate-in-place
+    'DROP TRIGGER IF EXISTS trg ON t; CREATE TRIGGER trg BEFORE INSERT ON t ...;',
+    'CREATE OR REPLACE VIEW v AS SELECT 1;',
+    'DROP VIEW IF EXISTS v; CREATE VIEW v AS SELECT 1;',
+    'DROP FUNCTION IF EXISTS f(); CREATE FUNCTION f() RETURNS void ...;',
+    "INSERT INTO t (id) VALUES (1);",
+  ];
+  for (const sql of safe) {
+    const r = lint.scanMigrationSql(sql);
+    assert.equal(r.unsafe.length, 0, `false positive on safe SQL: ${sql} — got ${JSON.stringify(r.unsafe)}`);
+  }
+});
+
+t('scanMigrationSql: the acknowledgement pragma flips an unsafe op to acknowledged', () => {
+  const r = lint.scanMigrationSql('-- forward-unsafe: intentional, two-step deploy\nALTER TABLE t DROP COLUMN c;');
+  assert.ok(r.unsafe.includes('drop-column'));
+  assert.equal(r.acknowledged, true);
+  assert.match(r.ackReason, /two-step/);
+});
+
+t('scanMigrationSql: an unsafe keyword only inside a comment does NOT count', () => {
+  const r = lint.scanMigrationSql('-- this migration does NOT drop table anything\nCREATE TABLE t (id int);');
+  assert.equal(r.unsafe.length, 0, `comment text must not trip the scan — got ${JSON.stringify(r.unsafe)}`);
+});
+
+console.log(`\nmigrations_forward_safe: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/module_api.mjs

@@ -20,7 +20,7 @@ const seams = require(path.join(ROOT, 'src', 'module-seams.js'));
 // was added; no enabled module at its pinned coreVersion lost a capability.
 const PUBLISHED_SURFACE = [
   'CORE_VERSION',
-  'requireBuilder', 'requireRank', 'rankMeetsThreshold', 'requireBfgPrincipal', 'allowBoxScope',
+  'requireBuilder', 'requireRank', 'rankMeetsThreshold', 'requireBfgPrincipal', 'allowBoxScope', 'resolveSession',
   '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)

package/tests/module_contributions.mjs

@@ -146,3 +146,58 @@ test('settings-panel seam: ABSENT → empty; REGISTERED → present, sorted by o
   assert.throws(() => OTB.contributeSettingsPanel({ id: 'x' }), /requires id \+ mount/);
   delete global.window;
 });
+
+// --- hall-widget placement governance (task 2177) ----------------------------
+// Home grew unbounded once; contributeHallWidget now refuses the registrations
+// that let it. Rejections are console.error + null (NOT a throw) so one bad
+// third-party widget can't blank the hall — so these assert the RETURN VALUE and
+// that the widget never reached the registry.
+
+test('hall-widget registry: placement rules reject bad registrations, accept good ones', () => {
+  global.window = {};
+  // The settings-panel test above already required dom-utils.js, and the IIFE
+  // assigns window.OTB exactly once at load — so re-requiring a cached module
+  // would leave window.OTB undefined. Evict it to get a fresh registry.
+  const domUtils = path.join(ROOT, 'modules', 'hall-ui', 'public', 'dom-utils.js');
+  delete require.cache[require.resolve(domUtils)];
+  require(domUtils);
+  const OTB = global.window.OTB;
+
+  const errors = [];
+  const realError = console.error;
+  console.error = (msg) => errors.push(String(msg));
+  const reg = (o) => OTB.contributeHallWidget({ label: 'L', mount() {}, ...o });
+
+  try {
+    // the structural contract still THROWS (first-party programmer error)
+    assert.throws(() => reg({ label: 'no id' }), /requires id \+ label \+ mount/);
+
+    // unknown zone / unknown view — a typo used to mount the widget on Home
+    // silently, which read as "my widget vanished"
+    assert.equal(reg({ id: 'a', view: 'home', zone: 'home-sidebar' }), null);
+    assert.match(errors.at(-1), /unknown zone "home-sidebar"/);
+    assert.equal(reg({ id: 'b', view: 'dashboard', zone: 'home-main', summary: true }), null);
+    assert.match(errors.at(-1), /unknown view "dashboard"/);
+
+    // a Home widget must NAME its zone — there is no home-main fallback any more
+    assert.equal(reg({ id: 'c' }), null);
+    assert.match(errors.at(-1), /must declare a zone/);
+
+    // a non-core home-main widget must be summary or collapsed
+    assert.equal(reg({ id: 'd', view: 'home', zone: 'home-main' }), null);
+    assert.match(errors.at(-1), /summary:true .* or collapsedByDefault:true/);
+
+    // …and the escapes from that rule work
+    assert.ok(reg({ id: 'e', view: 'home', zone: 'home-main', summary: true }));
+    assert.ok(reg({ id: 'f', view: 'home', zone: 'home-main', collapsedByDefault: true }));
+    assert.ok(reg({ id: 'g', view: 'home', zone: 'home-main', core: true }));
+    // a non-Home view needs no zone (Standing widgets carry `group` instead)
+    assert.ok(reg({ id: 'h', view: 'standing', group: 'work' }));
+
+    // only the accepted four reached the registry
+    assert.deepEqual(OTB.hallWidgetIds(), ['e', 'f', 'g', 'h']);
+  } finally {
+    console.error = realError;
+    delete global.window;
+  }
+});

package/tests/module_loader.mjs

@@ -168,13 +168,18 @@ test('the live tree discovers the extracted modules cleanly (BV1.R43/R48/R47/R49
   // onboarding (R81) + sessions (R82) + autonomy (R83 — conductor/architect/gate
   // + the routine-timers poller) are the tranche-2 core-domain carves (ADR 0093),
   // then status-ui (R84) + hall-ui (R85) the two web-surface carves; and
-  // provisioning (ADR 0111 / task 1942) — a net-new feature module (instance hosting).
-  // All are discovered; none has validation errors or coreVersion mismatches.
-  // Membership stays byte-identical via src/modules.js (each leaves MODULE_REGISTRY
-  // and reappears here as discovered). Order is the readdir sort.
+  // provisioning (ADR 0111 / task 1942) — a net-new feature module (instance hosting);
+  // platform-identity (ADR 0141) the hub IdP; and governance (ADR 0151 / BV1.R94) the
+  // configurable roles/permissions module. All are discovered; none has validation
+  // errors or coreVersion mismatches. Order is the readdir sort.
+  //
+  // NB this is the CORE package tree: game / art-pipeline / character-anim / demo are
+  // instance/content-excluded from the published core (ADR 0098) so they are not
+  // present here — the discovered set is the 17 always-shipped core-domain + feature
+  // modules below.
   loader._reset();
   const snap = loader.loaderSnapshot();
-  assert.deepEqual(snap.loaded, ['art-pipeline', 'autonomy', 'builder-settings', 'character-anim', 'demo', 'dev-box', 'discord', 'economy', 'game', 'grading', 'hall-ui', 'ideas', 'lifecycle', 'memory', 'onboarding', 'provisioning', 'security', 'sessions', 'status-ui']);
+  assert.deepEqual(snap.loaded, ['autonomy', 'builder-settings', 'dev-box', 'discord', 'economy', 'governance', 'grading', 'hall-ui', 'ideas', 'lifecycle', 'memory', 'onboarding', 'platform-identity', 'provisioning', 'security', 'sessions', 'status-ui']);
   assert.deepEqual(snap.errors, []);
   assert.deepEqual(snap.skipped, []);
   loader._reset();

package/tests/module_scope_active_claims.mjs

@@ -0,0 +1,94 @@
+// tests/module_scope_active_claims.mjs
+//
+// Unit guard for db.moduleScopeForActiveClaims (goal 1000051 / R92, ADR 0148 §2) —
+// the lifecycle-port resolver the dev-box source-access path (R93/R94) reads to
+// derive a builder's TASK-scoped sparse-checkout: the union of module KEYS across
+// the builder's active claims' goals (claims → tasks → goals.scope_modules).
+//
+// DB-free, same posture as goal_achievement.mjs: the function honours the #538
+// deps.pool injection seam (ONLY when NODE_ENV==='test'), so a SQL-aware fake
+// client drives it with no live Postgres. We assert the query SHAPE (joins
+// claims→tasks→goals, unnests scope_modules, filters ACTIVE claims), the bound
+// params, the rows→keys mapping, and the numeric-input guard. The actual
+// set-union/dedup is Postgres's DISTINCT (exercised end-to-end once box-access is
+// wired — R95); here we prove the port method's contract.
+//
+// Run:  node tests/module_scope_active_claims.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+
+const require = createRequire(import.meta.url);
+const { moduleScopeForActiveClaims } = require('../modules/lifecycle/db.js');
+
+const { test, summary } = makeRunner();
+
+function fakePool(handler) {
+  const c = makeSqlAwareClient(handler);
+  return { query: (sql, params) => c._client.query(sql, params), connect: c.connect, queries: c._client.queries };
+}
+const norm = (s) => String(s).replace(/\s+/g, ' ').trim();
+const find = (queries, re) => queries.find((q) => re.test(norm(q.sql)));
+
+// The one read this function issues: claims → tasks → goals, unnest scope_modules,
+// active claims only. The fake returns whatever module-key rows we hand it (the
+// DISTINCT/ORDER BY is Postgres's job — here we just prove the plumbing).
+function scopeHandler(rows) {
+  return (s) => {
+    if (/FROM claims c/.test(s) && /JOIN goals g/.test(s) && /unnest\(g\.scope_modules\)/.test(s)) {
+      return { rows };
+    }
+    return null;
+  };
+}
+
+// =========================================================================
+// Happy path — active claims put N goals' scope_modules in scope
+// =========================================================================
+await test('returns the module keys the active claims scope, in DB order', async () => {
+  const pool = fakePool(scopeHandler([{ module_key: 'dev-box' }, { module_key: 'kernel' }, { module_key: 'lifecycle' }]));
+  const keys = await moduleScopeForActiveClaims(3, { pool });
+  assert.deepEqual(keys, ['dev-box', 'kernel', 'lifecycle'], 'maps rows → module_key list');
+
+  const q = find(pool.queries, /FROM claims c JOIN tasks t .* JOIN goals g/);
+  assert.ok(q, 'issues the claims→tasks→goals scope read');
+  assert.match(norm(q.sql), /c\.builder_id = \$1 AND c\.released_at IS NULL/, 'active claims only, keyed on builder');
+  assert.match(norm(q.sql), /unnest\(g\.scope_modules\)/, 'unnests the goal scope_modules array');
+  assert.match(norm(q.sql), /SELECT DISTINCT/, 'DISTINCT dedupes the union across claims');
+  assert.deepEqual(q.params, [3], 'binds the builder id');
+});
+
+// =========================================================================
+// No active claim (or no scoped goal) → base-only signal ([])
+// =========================================================================
+await test('no active claim / no scoped goal → empty array (box falls back to BASE-only)', async () => {
+  const pool = fakePool(scopeHandler([]));
+  const keys = await moduleScopeForActiveClaims(3, { pool });
+  assert.deepEqual(keys, [], 'zero rows → []');
+});
+
+// =========================================================================
+// Input guard — a non-numeric builder id never reaches SQL
+// =========================================================================
+await test('non-numeric builderId throws before any query', async () => {
+  const pool = fakePool(scopeHandler([{ module_key: 'dev-box' }]));
+  await assert.rejects(() => moduleScopeForActiveClaims('not-a-number', { pool }), /must be numeric/);
+  await assert.rejects(() => moduleScopeForActiveClaims(NaN, { pool }), /must be numeric/);
+  assert.equal(pool.queries.length, 0, 'guard trips before the pool is touched');
+});
+
+// =========================================================================
+// The #538 deps.pool test seam is actually wired (we ARE in NODE_ENV==='test')
+// =========================================================================
+await test('honours the deps.pool test seam', async () => {
+  let touched = false;
+  const pool = fakePool((s) => { touched = true; return /unnest/.test(s) ? { rows: [{ module_key: 'game' }] } : null; });
+  const keys = await moduleScopeForActiveClaims(7, { pool });
+  assert.ok(touched, 'the injected pool was used');
+  assert.deepEqual(keys, ['game']);
+});
+
+summary();

package/tests/needs_rebase.mjs

@@ -0,0 +1,92 @@
+// tests/needs_rebase.mjs — ADR 0120 part 2 (real DB).
+//
+// Exercises db.flagTaskNeedsRebase + the flag-clearing on ship against a live
+// Postgres (DATABASE_URL). The fake-client harness can't cover the actual
+// WHERE-clause guards (status='confirmed' AND needs_rebase=false) or the
+// migration-093 columns, so this is a real-DB integration test. It SELF-SKIPS
+// (exit 0) when no DB is reachable, so it is safe on a bare worktree; it is also
+// listed in run-unit-tests.js's INTEGRATION set so the default DB-free lane
+// never runs it.
+//
+// Run:  DATABASE_URL=... node tests/needs_rebase.mjs
+
+import { createRequire } from 'node:module';
+import { strict as assert } from 'node:assert';
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+
+// Reachability probe — skip cleanly if there's no local Postgres.
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`needs_rebase.mjs SKIPPED — no reachable Postgres (${e.code || e.message}). Set DATABASE_URL to run.`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const seams = require('../src/module-seams.js');
+if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../modules/economy/reward.js'));
+const db = require('../modules/lifecycle/db.js');
+
+const VER = 'ZZZ-NR', WORKER = 90000101, TASK = 90000101;
+const q = (sql, params) => pool.query(sql, params).then((r) => r.rows);
+const taskRow = async () => (await q(`SELECT status, needs_rebase, needs_rebase_reason, needs_rebase_at FROM tasks WHERE id=$1`, [TASK]))[0];
+
+async function cleanup() {
+  await q(`DELETE FROM builder_achievements WHERE builder_id=$1`, [WORKER]).catch(() => {});
+  await q(`DELETE FROM credit_log WHERE builder_id=$1 OR task_id=$2`, [WORKER, TASK]).catch(() => {});
+  await q(`DELETE FROM claims WHERE task_id=$1`, [TASK]).catch(() => {});
+  await q(`DELETE FROM tasks WHERE id=$1`, [TASK]).catch(() => {});
+  await q(`DELETE FROM builders WHERE id=$1`, [WORKER]).catch(() => {});
+  await q(`DELETE FROM versions WHERE id=$1`, [VER]).catch(() => {});
+}
+
+let pass = 0;
+const ok = (cond, msg) => { assert.ok(cond, msg); console.log(`  ok  ${msg}`); pass++; };
+
+try {
+  await cleanup();
+  await q(`INSERT INTO versions (id,name,status,track) VALUES ($1,'nr','planning','internal') ON CONFLICT (id) DO NOTHING`, [VER]);
+  await q(`INSERT INTO builders (id,github_id,github_login,display_name,rank) VALUES ($1,'nr-w','nr-worker','NR Worker','thetes')`, [WORKER]);
+  await q(`INSERT INTO tasks (id,version_id,title,status,credits_reward,kind,shipped_by) VALUES ($1,$2,'nr fixture','confirmed',10,'feature',$3)`, [TASK, VER, WORKER]);
+  await q(`INSERT INTO claims (task_id,builder_id,claimed_at) VALUES ($1,$2,now())`, [TASK, WORKER]);
+
+  // 1) flag a CONFIRMED task → flagged, reason + at set, returns true.
+  const first = await db.flagTaskNeedsRebase(String(TASK), 'strand:no_branch_no_tip');
+  ok(first === true, 'flagTaskNeedsRebase returns true when it newly flags a confirmed task');
+  let t = await taskRow();
+  ok(t.needs_rebase === true, 'tasks.needs_rebase is true after flagging');
+  ok(t.needs_rebase_reason === 'strand:no_branch_no_tip', 'reason recorded');
+  ok(t.needs_rebase_at != null, 'needs_rebase_at timestamp set');
+
+  // 2) idempotent — a second flag is a no-op (returns false, at unchanged).
+  const atWas = t.needs_rebase_at;
+  const second = await db.flagTaskNeedsRebase(String(TASK), 'strand:different');
+  ok(second === false, 'a re-flag of an already-flagged task returns false (idempotent)');
+  t = await taskRow();
+  ok(t.needs_rebase_reason === 'strand:no_branch_no_tip', 'reason NOT overwritten on re-flag');
+  ok(String(t.needs_rebase_at.getTime?.() ?? t.needs_rebase_at) === String(atWas.getTime?.() ?? atWas), 'needs_rebase_at unchanged on re-flag');
+
+  // 3) shipping the task CLEARS the flag (the land completed).
+  await db.shipTask({ taskId: String(TASK), builderId: String(WORKER) });
+  t = await taskRow();
+  ok(t.status === 'shipped', 'task shipped');
+  ok(t.needs_rebase === false, 'needs_rebase cleared on ship');
+  ok(t.needs_rebase_reason === null && t.needs_rebase_at === null, 'reason + at cleared on ship');
+
+  // 4) a NON-confirmed task cannot be flagged (guard: WHERE status='confirmed').
+  const onShipped = await db.flagTaskNeedsRebase(String(TASK), 'should-not-apply');
+  ok(onShipped === false, 'flagTaskNeedsRebase is a no-op on a non-confirmed (shipped) task');
+  t = await taskRow();
+  ok(t.needs_rebase === false, 'a shipped task stays unflagged');
+
+  console.log(`\nneeds_rebase (ADR 0120 part 2): ${pass} passed, 0 failed`);
+} catch (e) {
+  console.error('needs_rebase.mjs FAILED:', e.message);
+  process.exitCode = 1;
+} finally {
+  await cleanup();
+  await pool.end();
+}