@bongos/core 1.19.63 → 1.19.65

package/tests/module_cli.mjs

@@ -418,3 +418,129 @@ test('`bongos module submit` is documented in help / dispatches to module.js sub
   assert.ok(lines.some((l) => /module submit/.test(l)));
   assert.equal(await mod.main(['node', 'module.js', 'submit']), 2, 'no key => usage error');
 });
+
+// ---------------------------------------------------------------------------
+// Maintenance & deprecation policy (ADR 0107 §7 / ADR 0166, task 1001773)
+// ---------------------------------------------------------------------------
+
+test('evaluateUpgrade: sorts self-declared deprecations, and flags the ones the core has passed removeAfter', () => {
+  const v = mod.evaluateUpgrade({
+    core: '1.13.0',
+    rows: [
+      { key: 'healthy', coreVersion: '^1.0.0', enabled: true, satisfied: true, maintenance: { status: 'core-maintained' } },
+      { key: 'sunset', coreVersion: '^1.0.0', enabled: false, satisfied: true, maintenance: { status: 'deprecated', successor: 'newer', removeAfter: '1.12.0' } },
+      { key: 'sunset-later', coreVersion: '^1.0.0', enabled: false, satisfied: true, maintenance: { status: 'deprecated', note: 'going', removeAfter: '1.20.0' } },
+      { key: 'nobody', coreVersion: '^1.0.0', enabled: false, satisfied: true, maintenance: { status: 'orphaned', note: 'unowned' } },
+    ],
+  });
+  assert.equal(v.ok, true, 'a deprecation is not a compatibility failure — it must not block a bump');
+  assert.deepEqual(v.deprecations.map((d) => d.key), ['sunset', 'sunset-later', 'nobody']);
+  assert.deepEqual(v.expired.map((d) => d.key), ['sunset'], 'core 1.13.0 is past removeAfter 1.12.0 but not 1.20.0');
+  assert.deepEqual(v.undeclared, []);
+});
+
+test('evaluateUpgrade: a module with no maintenance block is reported as undeclared (nobody is on the hook)', () => {
+  const v = mod.evaluateUpgrade({
+    core: '1.0.0',
+    rows: [
+      { key: 'owned', coreVersion: '^1.0.0', enabled: true, satisfied: true, maintenance: { status: 'core-maintained' } },
+      { key: 'orphan-risk', coreVersion: '^1.0.0', enabled: false, satisfied: true },
+    ],
+  });
+  assert.deepEqual(v.undeclared.map((r) => r.key), ['orphan-risk']);
+  assert.equal(v.ok, true, 'an undeclared posture is a reporting gap, not a compatibility failure');
+});
+
+test('formatMaintenanceHint: names the owner, or says plainly that there is none', () => {
+  assert.match(mod.formatMaintenanceHint({ key: 'x' }), /no maintenance declared/);
+  assert.match(
+    mod.formatMaintenanceHint({ key: 'x', maintainer: 'Ada <ada@example.com>', maintenance: { status: 'maintained' } }),
+    /maintainer Ada <ada@example\.com>/,
+  );
+  assert.match(mod.formatMaintenanceHint({ key: 'x', maintenance: { status: 'maintained' } }), /unnamed!/);
+  const sunset = mod.formatMaintenanceHint({ key: 'x', maintenance: { status: 'deprecated', successor: 'y', removeAfter: '1.12.0', note: 'use y' } });
+  assert.match(sunset, /superseded by "y"/);
+  assert.match(sunset, /removable after core 1\.12\.0/);
+});
+
+test('gatherUpgrade: carries each module\'s maintenance posture onto its row', () => {
+  loader._reset();
+  const root = tmpModulesRoot();
+  mod.scaffoldModule({ key: 'econ', modulesDir: root, core: '1.0.0' });
+  const data = mod.gatherUpgrade({ modulesDir: root, core: '1.0.0', env: {}, neutral: {}, instance: {}, prefix: 'CLOUDBONGOS' });
+  const row = data.rows.find((r) => r.key === 'econ');
+  assert.equal(row.maintenance.status, 'maintained', 'the scaffolder stamps an honest default');
+  assert.ok(row.maintainer, 'the maintainer travels with the row so the hint can name them');
+  loader._reset();
+});
+
+test('cmdUpgrade: a DISABLED incompatible module is reported with its owner, not silently dropped', () => {
+  // The catalog-rot case: an accepted module ships default:false (ADR 0107 §6), so
+  // every rotted catalog entry is disabled by construction. Exit stays 0 — it breaks
+  // nothing at boot — but it must be visible and attributed.
+  const lines = [];
+  const sink = { log: (s) => lines.push(String(s)), errlog: (s) => lines.push(String(s)) };
+  const code = mod.cmdUpgrade([], {
+    ...sink,
+    gather: () => ({
+      core: '2.0.0',
+      errors: [],
+      rows: [{
+        key: 'stale-catalog-entry', coreVersion: '^1.0.0', enabled: false, satisfied: false,
+        maintainer: 'Ada <ada@example.com>', maintenance: { status: 'maintained' },
+      }],
+    }),
+  });
+  assert.equal(code, 0, 'a disabled mismatch must not block');
+  const out = lines.join('\n');
+  assert.match(out, /stale-catalog-entry/);
+  assert.match(out, /BROKEN if enabled/);
+  assert.match(out, /maintainer Ada <ada@example\.com>/, 'the owner is named so someone can be told');
+});
+
+test('cmdUpgrade: reports an expired deprecation and modules with no declared upkeep', () => {
+  const lines = [];
+  const sink = { log: (s) => lines.push(String(s)), errlog: (s) => lines.push(String(s)) };
+  const code = mod.cmdUpgrade([], {
+    ...sink,
+    gather: () => ({
+      core: '1.13.0',
+      errors: [],
+      rows: [
+        { key: 'sunset', coreVersion: '^1.0.0', enabled: false, satisfied: true, maintenance: { status: 'deprecated', successor: 'newer', removeAfter: '1.12.0' } },
+        { key: 'unowned', coreVersion: '^1.0.0', enabled: false, satisfied: true },
+      ],
+    }),
+  });
+  assert.equal(code, 0);
+  const out = lines.join('\n');
+  assert.match(out, /sunset: deprecated/);
+  assert.match(out, /PAST removeAfter 1\.12\.0/);
+  assert.match(out, /declare no `maintenance` block/);
+  assert.match(out, /unowned/);
+});
+
+test('checkModulePublishability: refuses a module that declares no maintenance posture', () => {
+  const root = tmpModulesRoot();
+  const { dir } = mod.scaffoldModule({ key: 'unowned', modulesDir: root, core: '1.0.0' });
+  const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'module.json'), 'utf8'));
+  delete manifest.maintenance;
+  fs.writeFileSync(path.join(dir, 'module.json'), JSON.stringify(manifest, null, 2));
+  const r = mod.checkModulePublishability('unowned', { modulesDir: root });
+  assert.equal(r.ok, false, 'acceptance is a commitment to upkeep — it must be stated');
+  assert.ok(r.findings.some((f) => f.kind === 'maintenance' && /core-maintained/.test(f.detail)), JSON.stringify(r.findings));
+});
+
+test('checkModulePublishability: refuses a module that is ALREADY deprecated or orphaned', () => {
+  const root = tmpModulesRoot();
+  for (const status of ['deprecated', 'orphaned']) {
+    const key = `sunset-${status}`;
+    const { dir } = mod.scaffoldModule({ key, modulesDir: root, core: '1.0.0' });
+    const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'module.json'), 'utf8'));
+    manifest.maintenance = { status, note: 'on the way out' };
+    fs.writeFileSync(path.join(dir, 'module.json'), JSON.stringify(manifest, null, 2));
+    const r = mod.checkModulePublishability(key, { modulesDir: root });
+    assert.equal(r.ok, false, `${status} must not be submittable INTO the catalog`);
+    assert.ok(r.findings.some((f) => f.kind === 'maintenance' && /way out/.test(f.detail)));
+  }
+});

package/tests/module_manifest.mjs

@@ -211,3 +211,68 @@ test('dependencies: a non-object, or a non-string range, is rejected', () => {
     assert.ok(r.errors.some((e) => e.startsWith('dependencies')), `error should mention dependencies: ${r.errors}`);
   }
 });
+
+// --- maintenance & deprecation policy (ADR 0107 §7 / ADR 0166) ---
+
+test('maintenance: omitted is fine (optional — pre-policy manifests still validate)', () => {
+  assert.equal(validateManifest(baseManifest()).valid, true);
+});
+
+test('maintenance: each of the four statuses validates when its own obligations are met', () => {
+  const cases = [
+    { maintenance: { status: 'core-maintained' } },
+    { maintainer: 'A. Builder', maintenance: { status: 'maintained' } },
+    { maintenance: { status: 'deprecated', successor: 'econ-v2', removeAfter: '1.12.0' } },
+    { maintenance: { status: 'orphaned', note: 'Author unreachable since 2026-07; enable at your own risk.' } },
+  ];
+  for (const extra of cases) {
+    const r = validateManifest({ ...baseManifest(), ...extra });
+    assert.equal(r.valid, true, `${extra.maintenance.status}: ${r.errors.join('; ')}`);
+  }
+});
+
+test('maintenance: "maintained" without a named top-level maintainer is rejected', () => {
+  const r = validateManifest({ ...baseManifest(), maintenance: { status: 'maintained' } });
+  assert.equal(r.valid, false, 'an unnamed maintainer IS the orphaning failure the policy prevents');
+  assert.ok(r.errors.some((e) => /maintained.*maintainer/.test(e)), r.errors.join('; '));
+});
+
+test('maintenance: a sunset status with no deprecation path (no successor, no note) is rejected', () => {
+  for (const status of ['deprecated', 'orphaned']) {
+    const r = validateManifest({ ...baseManifest(), maintenance: { status } });
+    assert.equal(r.valid, false, `${status} must state a path out`);
+    assert.ok(r.errors.some((e) => /deprecation path/.test(e)), r.errors.join('; '));
+  }
+});
+
+test('maintenance: an unknown status, an unknown key, or a bad version is rejected', () => {
+  const bad = [
+    { status: 'someday' },
+    { status: 'core-maintained', removeafter: '1.2.0' },
+    { status: 'core-maintained', since: 'v1.2' },
+    { status: 'deprecated', successor: 'Econ_V2' },
+    'core-maintained',
+  ];
+  for (const m of bad) {
+    const r = validateManifest({ ...baseManifest(), maintenance: m });
+    assert.equal(r.valid, false, `should reject ${JSON.stringify(m)}`);
+  }
+});
+
+test('maintenance: removeAfter only applies to a module on its way out', () => {
+  const r = validateManifest({ ...baseManifest(), maintenance: { status: 'core-maintained', removeAfter: '1.12.0' } });
+  assert.equal(r.valid, false);
+  assert.ok(r.errors.some((e) => /removeAfter only applies/.test(e)), r.errors.join('; '));
+});
+
+test('every bundled module declares a maintenance posture (the catalog has no unowned entries)', async () => {
+  const fsm = (await import('node:fs')).default;
+  const modulesDir = path.join(ROOT, 'modules');
+  const undeclared = fsm.readdirSync(modulesDir)
+    .filter((k) => fsm.existsSync(path.join(modulesDir, k, 'module.json')))
+    .filter((k) => {
+      const m = JSON.parse(fsm.readFileSync(path.join(modulesDir, k, 'module.json'), 'utf8'));
+      return !m.maintenance || !m.maintenance.status;
+    });
+  assert.deepEqual(undeclared, [], `these modules declare no maintenance.status: ${undeclared.join(', ')}`);
+});

package/tests/one_active_claim_per_session.mjs

@@ -183,6 +183,80 @@ t('names the in-flight task in the MATCHING worktree, not the first row', () =>
   assert.equal(d.inFlightTitle, 'Two');
 });
 
+// =========================================================================
+// task 1002522 — the guard and core_204's backstop index must agree EXACTLY on
+// which claims share a tree. The index keys (creator_session_id,
+// COALESCE(worktree_name, '')), so to Postgres '' IS the worktree-less group;
+// the guard compared raw values, where '' !== null. db.foldWorktreeName is the
+// single normalization both sides now use (and claimTask applies before the
+// INSERT, so stored rows are already trimmed-or-NULL).
+// =========================================================================
+const { foldWorktreeName } = require('../modules/lifecycle/db.js');
+
+t('foldWorktreeName folds null / empty / whitespace to the same NULL key', () => {
+  assert.equal(foldWorktreeName(null), null);
+  assert.equal(foldWorktreeName(undefined), null);
+  assert.equal(foldWorktreeName(''), null);
+  assert.equal(foldWorktreeName('   '), null);
+  assert.equal(foldWorktreeName('\t\n'), null);
+});
+
+t('foldWorktreeName trims but never renames a real worktree', () => {
+  assert.equal(foldWorktreeName('wt-a'), 'wt-a');
+  assert.equal(foldWorktreeName('  wt-a  '), 'wt-a');
+  // Distinct trees stay distinct — the fold must not collapse parallel work.
+  assert.notEqual(foldWorktreeName('wt-a'), foldWorktreeName('wt-a-2'));
+});
+
+t("empty-string worktree is the SAME tree as worktree-less → refused (matches the index)", () => {
+  // Before the fold this returned allow, and the INSERT then tripped
+  // uniq_active_claim_per_session_worktree — a 23505 on a task nobody had taken.
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-6',
+    worktreeName: '',
+    activeClaimsForSession: [
+      { claim_id: 50, task_id: 70, creator_session_id: 'sess-6', worktree_name: null, title: 'shared clone' },
+    ],
+  });
+  assert.equal(d.refuse, true);
+  assert.equal(d.inFlightTaskId, 70);
+});
+
+t('the mirror case: worktree-less incoming vs a stored empty-string name → refused', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-6',
+    worktreeName: null,
+    activeClaimsForSession: [
+      { claim_id: 51, task_id: 71, creator_session_id: 'sess-6', worktree_name: '   ', title: 'blank name' },
+    ],
+  });
+  assert.equal(d.refuse, true);
+  assert.equal(d.inFlightTaskId, 71);
+});
+
+t('whitespace around a real name does not fake a second tree', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-6',
+    worktreeName: ' wt-a ',
+    activeClaimsForSession: [
+      { claim_id: 52, task_id: 72, creator_session_id: 'sess-6', worktree_name: 'wt-a', title: 'A' },
+    ],
+  });
+  assert.equal(d.refuse, true);
+  assert.equal(d.inFlightTaskId, 72);
+});
+
+t('the fold does NOT re-break parallel worktrees (the bug this family fixed)', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-6',
+    worktreeName: 'wt-b',
+    activeClaimsForSession: [
+      { claim_id: 53, task_id: 73, creator_session_id: 'sess-6', worktree_name: 'wt-a', title: 'A' },
+    ],
+  });
+  assert.equal(d.refuse, false);
+});
+
 // =========================================================================
 // task 1002589 (idea 1000638) — the DB backstop's ERROR SURFACE. A claims
 // INSERT can trip TWO partial unique indexes; claimTask used to map every pg

package/tests/upgrade.mjs

@@ -935,6 +935,100 @@ t('healDocAssets: a generator absent from this core is recorded, not spawned', (
   assert.equal(spawned.length, 1, 'the absent script is never spawned');
 });
 
+// --- module maintenance & deprecation surfacing (ADR 0107 §7 / ADR 0166, task 1001773) ---
+//
+// The bug this pins: preflightModules used to return ONLY `blocking`, so a DISABLED module
+// whose coreVersion the target core no longer satisfies vanished from a real bump entirely.
+// An accepted catalog module ships default:false (ADR 0107 §6) — so that was every rotted
+// catalog entry, silently.
+
+// A modules/ dir on disk that preflightModules will really discover, driven through a stub
+// moduleLib so the verdict shape (not the loader) is what's under test.
+function moduleLibStub(verdict) {
+  return { gatherUpgrade: () => ({ rows: verdict.rows || [], errors: [], core: verdict.core }), evaluateUpgrade: () => verdict };
+}
+
+t('preflightModules: a DISABLED incompatible module is returned as a warning, not dropped', () => {
+  const dir = scratchConsumer();
+  mkdirSync(join(dir, 'modules'), { recursive: true });
+  const warned = { key: 'stale-catalog-entry', coreVersion: '^1.0.0', enabled: false, satisfied: false, maintainer: 'Ada <ada@example.com>', maintenance: { status: 'maintained' } };
+  const res = u.preflightModules({ instanceDir: dir, targetVersion: '2.0.0' }, {
+    moduleLib: moduleLibStub({ ok: true, blocking: [], warnings: [warned], deprecations: [], expired: [], core: '2.0.0' }),
+  });
+  assert.equal(res.ok, true, 'a disabled mismatch must never block the bump');
+  assert.deepEqual(res.warnings.map((w) => w.key), ['stale-catalog-entry']);
+  assert.match(res.note, /1 disabled module\(s\) do NOT/, 'the headline note admits the rot instead of claiming all-clear');
+});
+
+t('preflightModules: with everything healthy the note stays the plain all-clear', () => {
+  const dir = scratchConsumer();
+  mkdirSync(join(dir, 'modules'), { recursive: true });
+  const res = u.preflightModules({ instanceDir: dir, targetVersion: '2.0.0' }, {
+    moduleLib: moduleLibStub({ ok: true, blocking: [], warnings: [], deprecations: [], expired: [], core: '2.0.0' }),
+  });
+  assert.equal(res.note, 'all enabled modules satisfy the target');
+  assert.deepEqual(res.warnings, []);
+});
+
+t('preflightModules: no modules/ dir returns every collection empty (a vanilla consumer)', () => {
+  const dir = scratchConsumer();
+  const res = u.preflightModules({ instanceDir: dir, targetVersion: '2.0.0' });
+  assert.equal(res.ok, true);
+  for (const k of ['blocking', 'warnings', 'deprecations', 'expired']) assert.deepEqual(res[k], [], k);
+});
+
+t('reportModulePreflight: prints the rotted-but-disabled module WITH its maintainer named', () => {
+  const out = [];
+  const mods = {
+    warnings: [{ key: 'stale-catalog-entry', coreVersion: '^1.0.0', maintainer: 'Ada <ada@example.com>', maintenance: { status: 'maintained' } }],
+    deprecations: [], expired: [],
+  };
+  u.reportModulePreflight(mods, '2.0.0', { log: (s) => out.push(s), err: (s) => out.push(s) });
+  const text = out.join('\n');
+  assert.match(text, /stale-catalog-entry/);
+  assert.match(text, /silently fail to mount/);
+  assert.match(text, /maintainer Ada <ada@example\.com>/);
+});
+
+t('reportModulePreflight: calls out a deprecation the core has already passed removeAfter', () => {
+  const out = [];
+  const dep = { key: 'sunset', maintenance: { status: 'deprecated', successor: 'newer', removeAfter: '1.12.0' } };
+  u.reportModulePreflight({ warnings: [], deprecations: [dep], expired: [dep] }, '1.13.0', { log: (s) => out.push(s), err: (s) => out.push(s) });
+  const text = out.join('\n');
+  assert.match(text, /module "sunset" is deprecated/);
+  assert.match(text, /PAST its removeAfter 1\.12\.0/);
+  assert.match(text, /due for removal/);
+});
+
+t('reportModulePreflight: nothing to say prints nothing', () => {
+  const out = [];
+  const lines = u.reportModulePreflight({ warnings: [], deprecations: [], expired: [] }, '2.0.0', { log: (s) => out.push(s), err: (s) => out.push(s) });
+  assert.deepEqual(lines, []);
+  assert.deepEqual(out, []);
+});
+
+t('runUpgrade: a REFUSED bump still reports the non-blocking module findings', async () => {
+  // A refusal is exactly when someone is reading this output, so the warnings must
+  // already have been emitted by the time the blocking check returns.
+  const dir = scratchConsumer();
+  mkdirSync(join(dir, 'modules'), { recursive: true });
+  const out = [];
+  const res = await u.runUpgrade({ to: '2.0.0', instance: dir, force: true, dryRun: true }, {
+    log: (s) => out.push(String(s)),
+    err: (s) => out.push(String(s)),
+    moduleLib: moduleLibStub({
+      ok: false,
+      blocking: [{ key: 'enabled-breaker', coreVersion: '^1.0.0', enabled: true, satisfied: false }],
+      warnings: [{ key: 'stale-catalog-entry', coreVersion: '^1.0.0', maintenance: { status: 'orphaned', note: 'author unreachable' } }],
+      deprecations: [], expired: [], core: '2.0.0',
+    }),
+  });
+  assert.equal(res.ok, false, 'the enabled mismatch still refuses');
+  const text = out.join('\n');
+  assert.match(text, /stale-catalog-entry/, 'the disabled rot is reported even on a refused bump');
+  assert.match(text, /author unreachable/);
+});
+
 await Promise.all(pending);
 console.log(`\nupgrade: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);