@bongos/core 1.19.589 → 1.19.591

package/tests/goal_archive_disposition.mjs

@@ -24,6 +24,8 @@ process.env.NODE_ENV = 'test';
 const require = createRequire(import.meta.url);
 const { openTasksInGoal } = require('../modules/lifecycle/db.js');
 const { TERMINAL_STATUSES } = require('../modules/lifecycle/task-status.js');
+const { planGoalArchiveDispositions } = require('../modules/lifecycle/routes/goal-route-authz.js');
+const { archiveGoalWithDispositions } = require('../modules/lifecycle/db.js');
 
 const src = (rel) => readFileSync(new URL('../' + rel, import.meta.url), 'utf8');
 
@@ -86,15 +88,24 @@ test('an empty goal reports nothing held — the single-call path stays open', a
 // ---- the route --------------------------------------------------------------
 
 test('archive refuses with a NAMED 409 when the goal holds open work', () => {
-  assert.match(ARCHIVE, /const held = await db\.openTasksInGoal\(id\);/,
+  // R14 (task 1003601) moved this refusal OUT of the route and into the pure
+  // planner, so it is asserted on behaviour now rather than on route source —
+  // a strictly better pin, and the reason these two tests changed shape.
+  assert.match(ARCHIVE, /const held = await db\.openTasksInGoal\(id/,
     'the archive route must consult the work before discarding it');
-  assert.match(ARCHIVE, /res\.fail\('goal_holds_open_tasks', \{[\s\S]*?status: 409/,
-    'a named code an agent can branch on, not a bare 409');
+  const r = planGoalArchiveDispositions({
+    goalId: 7, openTasks: [{ id: '1', title: 't', status: 'ready' }], dispositions: null, reason: 'x',
+  });
+  assert.equal(r.ok, false);
+  assert.equal(r.status, 409);
+  assert.equal(r.body.error, 'goal_holds_open_tasks', 'a named code an agent can branch on, not a bare 409');
 });
 
 test('the refusal RETURNS the tasks, so the caller can decide without a second fetch', () => {
-  assert.match(ARCHIVE, /details: \{ total: held\.total, shown: held\.tasks\.length, tasks: held\.tasks \}/,
-    'an agent that has to go fetch the list will guess instead');
+  const held = [{ id: '1', title: 'one', status: 'ready' }, { id: '2', title: 'two', status: 'active' }];
+  const r = planGoalArchiveDispositions({ goalId: 7, openTasks: held, dispositions: null, reason: 'x' });
+  assert.deepEqual(r.body.details.tasks, held, 'an agent that has to go fetch the list will guess instead');
+  assert.equal(r.body.details.total, 2);
 });
 
 test('the check runs AFTER identity/authorization and BEFORE the status write', () => {
@@ -111,9 +122,14 @@ test('the check runs AFTER identity/authorization and BEFORE the status write',
 test('archiving a goal that holds nothing is still ONE call', () => {
   // The guard must not turn the ordinary case into a two-step. There is exactly
   // one setGoalStatus in this handler and no second round trip in front of it.
-  assert.equal((ARCHIVE.match(/db\.setGoalStatus/g) || []).length, 1);
+  assert.equal((ARCHIVE.match(/db\.setGoalStatus/g) || []).length, 1,
+    'the empty-goal path still writes through the plain setter, not the transaction');
   assert.equal(/disposition_required|preview=/.test(ARCHIVE), false,
     'no extra confirm parameter on the empty-goal path');
+  // And the planner agrees: nothing held means an empty plan, never a refusal.
+  const r = planGoalArchiveDispositions({ goalId: 7, openTasks: [], dispositions: null, reason: '' });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.plan, []);
 });
 
 // ---- the two doors agree ----------------------------------------------------
@@ -142,3 +158,188 @@ test('every non-terminal status is one the archive gate would catch', () => {
   assert.deepEqual([...TERMINAL_STATUSES].sort(), ['abandoned', 'shipped'],
     'and the terminal set is exactly the two deliberate endings');
 });
+
+// ---- R14: the disposition is APPLIED (task 1003601) --------------------------
+//
+// The second half of the two-step. R10 built the refusal; this is the answer to
+// it. The property under test throughout is TOTALITY: a map that does not cover
+// every open task is refused outright rather than applied as far as it goes,
+// because a half-applied disposition leaves the goal un-archivable AND some of
+// its work already abandoned, with no way for the caller to tell which happened.
+
+const TASKS = (...st) => st.map((s, i) => ({ id: String(i + 1), title: `t${i + 1}`, status: s }));
+const plan = (over = {}) => planGoalArchiveDispositions({
+  goalId: 7, openTasks: TASKS('ready', 'active'), reason: 'cut in the ten-areas review', ...over,
+});
+
+test('a partial map is refused — nothing is discarded by omission', () => {
+  const r = plan({ dispositions: { 1: { verb: 'abandon' } } });   // task 2 undecided
+  assert.equal(r.ok, false);
+  assert.equal(r.status, 400);
+  assert.equal(r.body.error, 'disposition_incomplete');
+  assert.equal(r.body.details.undecided, 1);
+  assert.deepEqual(r.body.details.tasks.map((t) => t.id), ['2'],
+    'the refusal names WHICH task is undecided, not merely how many');
+});
+
+test('a complete map plans one step per task, in the order the tasks came in', () => {
+  const r = plan({ dispositions: { 1: { verb: 'abandon' }, 2: { verb: 'move', goal_id: 42 } } });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.plan, [
+    { taskId: 1, verb: 'abandon', toGoalId: null },
+    { taskId: 2, verb: 'move', toGoalId: 42 },
+  ]);
+});
+
+test('an abandon with no reason is refused — that is the silent discard D3 forbids', () => {
+  for (const reason of ['', '   ', null, undefined]) {
+    const r = plan({ dispositions: { 1: { verb: 'abandon' }, 2: { verb: 'abandon' } }, reason });
+    assert.equal(r.ok, false, `reason ${JSON.stringify(reason)} must not pass`);
+    assert.equal(r.body.error, 'archive_reason_required');
+  }
+});
+
+test('only abandon and move are verbs; anything else is a named 400', () => {
+  for (const verb of ['delete', 'ABANDON', 'skip', '', null, 42]) {
+    const r = plan({ dispositions: { 1: { verb }, 2: { verb: 'abandon' } } });
+    assert.equal(r.ok, false, `verb ${JSON.stringify(verb)} must not pass`);
+    assert.equal(r.body.error, 'bad_disposition');
+  }
+});
+
+test('a move must name where it moves to', () => {
+  for (const goal_id of [undefined, null, 0, -1, 'forty-two', 1.5]) {
+    const r = plan({ dispositions: { 1: { verb: 'move', goal_id }, 2: { verb: 'abandon' } } });
+    assert.equal(r.ok, false, `goal_id ${JSON.stringify(goal_id)} must not pass`);
+    assert.equal(r.body.error, 'bad_disposition');
+  }
+});
+
+test('a task cannot be moved INTO the goal being archived', () => {
+  // The disposition that looks like a decision and is not: the task would be
+  // archived along with the goal a moment later — the silent discard renamed.
+  const r = plan({ dispositions: { 1: { verb: 'move', goal_id: 7 }, 2: { verb: 'abandon' } } });
+  assert.equal(r.ok, false);
+  assert.equal(r.body.error, 'bad_disposition');
+  assert.match(r.body.message, /into the goal being archived/);
+});
+
+test('a disposition for a task that is not open is simply unused, never an error', () => {
+  // The caller may hold a stale list; extra keys are harmless because the plan is
+  // built from the OPEN TASKS, not from the map.
+  const r = plan({ dispositions: { 1: { verb: 'abandon' }, 2: { verb: 'abandon' }, 999: { verb: 'move' } } });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.plan.map((p) => p.taskId), [1, 2]);
+});
+
+// ---- R14: the write is one transaction --------------------------------------
+
+function txPool(handler) {
+  const c = makeSqlAwareClient(handler);
+  return { connect: c.connect, query: (sql, params) => c._client.query(sql, params), queries: c._client.queries };
+}
+const flat = (q) => String(q.sql).replace(/\s+/g, ' ').trim();
+
+test('the whole disposition + archive runs inside ONE transaction', async () => {
+  const pool = txPool((sql) => {
+    const q = String(sql).replace(/\s+/g, ' ');
+    if (/^SELECT .* FROM goals WHERE id = \$1 FOR UPDATE/.test(q.trim())) return { rows: [{ id: 7, status: 'open' }] };
+    if (/FROM tasks WHERE id = \$1 AND goal_id = \$2 FOR UPDATE/.test(q)) return { rows: [{ id: 1, title: 't1', status: 'ready' }] };
+    if (/FROM claims WHERE task_id/.test(q)) return { rows: [] };
+    if (/count\(\*\)::int AS n FROM tasks/.test(q)) return { rows: [{ n: 0 }] };
+    if (/UPDATE goals SET status = 'archived'/.test(q)) return { rows: [{ id: 7, status: 'archived' }] };
+    return { rows: [] };
+  });
+  const out = await archiveGoalWithDispositions(
+    { goalId: 7, plan: [{ taskId: 1, verb: 'abandon', toGoalId: null }], reason: 'cut' },
+    { pool }
+  );
+  assert.equal(out.goal.status, 'archived');
+  const sqls = pool.queries.map(flat);
+  assert.equal(sqls.filter((q) => q === 'BEGIN').length, 1, 'exactly one BEGIN');
+  assert.equal(sqls.filter((q) => q === 'COMMIT').length, 1, 'exactly one COMMIT');
+  assert.ok(sqls.indexOf('BEGIN') < sqls.findIndex((q) => /UPDATE tasks SET status = 'abandoned'/.test(q)),
+    'the task writes are inside the transaction');
+  assert.ok(sqls.findIndex((q) => /UPDATE goals SET status = 'archived'/.test(q)) < sqls.indexOf('COMMIT'),
+    'so is the archive');
+});
+
+test('the goal row is locked BEFORE the plan is applied', async () => {
+  // Without FOR UPDATE on the goal, a concurrent POST /goals/:id/tasks can slip a
+  // new task in between the plan validating and the archive landing.
+  const pool = txPool((sql) => {
+    const q = String(sql).replace(/\s+/g, ' ');
+    if (/FROM goals WHERE id = \$1 FOR UPDATE/.test(q)) return { rows: [{ id: 7, status: 'open' }] };
+    if (/FROM tasks WHERE id = \$1 AND goal_id = \$2 FOR UPDATE/.test(q)) return { rows: [{ id: 1, title: 't', status: 'ready' }] };
+    if (/FROM claims/.test(q)) return { rows: [] };
+    if (/count\(\*\)::int AS n/.test(q)) return { rows: [{ n: 0 }] };
+    if (/UPDATE goals/.test(q)) return { rows: [{ id: 7, status: 'archived' }] };
+    return { rows: [] };
+  });
+  await archiveGoalWithDispositions({ goalId: 7, plan: [{ taskId: 1, verb: 'abandon', toGoalId: null }], reason: 'r' }, { pool });
+  const sqls = pool.queries.map(flat);
+  const lock = sqls.findIndex((q) => /FROM goals WHERE id = \$1 FOR UPDATE/.test(q));
+  const firstWrite = sqls.findIndex((q) => /^UPDATE tasks/.test(q));
+  assert.ok(lock !== -1 && firstWrite !== -1 && lock < firstWrite, 'lock the goal, then apply');
+});
+
+test('an actively-claimed task stops the archive and rolls it back', async () => {
+  const pool = txPool((sql) => {
+    const q = String(sql).replace(/\s+/g, ' ');
+    if (/FROM goals WHERE id = \$1 FOR UPDATE/.test(q)) return { rows: [{ id: 7, status: 'open' }] };
+    if (/FROM tasks WHERE id = \$1 AND goal_id = \$2 FOR UPDATE/.test(q)) return { rows: [{ id: 1, title: 'busy', status: 'active' }] };
+    if (/FROM claims WHERE task_id/.test(q)) return { rows: [{ id: 99 }] };   // someone is on it
+    return { rows: [] };
+  });
+  await assert.rejects(
+    archiveGoalWithDispositions({ goalId: 7, plan: [{ taskId: 1, verb: 'abandon', toGoalId: null }], reason: 'r' }, { pool }),
+    (e) => e.code === 'TASK_HAS_ACTIVE_CLAIM'
+  );
+  const sqls = pool.queries.map(flat);
+  assert.ok(sqls.includes('ROLLBACK'), 'nothing is left applied');
+  assert.equal(sqls.some((q) => /UPDATE goals SET status = 'archived'/.test(q)), false, 'and the goal is not archived');
+});
+
+test('the invariant is re-checked against committed state, not against the plan', async () => {
+  // The one check a bug in the planner cannot fool: if anything is still
+  // non-terminal after the writes, the archive rolls back rather than recreating
+  // exactly the condition goal 1000086 exists to make impossible.
+  const pool = txPool((sql) => {
+    const q = String(sql).replace(/\s+/g, ' ');
+    if (/FROM goals WHERE id = \$1 FOR UPDATE/.test(q)) return { rows: [{ id: 7, status: 'open' }] };
+    if (/FROM tasks WHERE id = \$1 AND goal_id = \$2 FOR UPDATE/.test(q)) return { rows: [{ id: 1, title: 't', status: 'ready' }] };
+    if (/FROM claims/.test(q)) return { rows: [] };
+    if (/count\(\*\)::int AS n FROM tasks/.test(q)) return { rows: [{ n: 3 }] };   // three snuck in
+    return { rows: [] };
+  });
+  await assert.rejects(
+    archiveGoalWithDispositions({ goalId: 7, plan: [{ taskId: 1, verb: 'abandon', toGoalId: null }], reason: 'r' }, { pool }),
+    (e) => e.code === 'DISPOSITION_INCOMPLETE_AFTER_APPLY' && e.remaining === 3
+  );
+  assert.ok(pool.queries.map(flat).includes('ROLLBACK'));
+});
+
+test('the re-check asks the SAME question the refusal asked', () => {
+  // Same terminal set, same smoke exclusion — or the transaction rolls back work
+  // the gate in front of it had already accepted.
+  const dbGoals = src('modules/lifecycle/db-goals.js');
+  const body = dbGoals.slice(dbGoals.indexOf('async function archiveGoalWithDispositions'));
+  assert.match(body, /\$\{nonTerminalSql\(\)\}/);
+  assert.match(body, /SMOKE_NOT_LIKE\.replace/);
+});
+
+test('an abandon stamps the archive reason, the way POST /tasks/:id/abandon does', () => {
+  const dbGoals = src('modules/lifecycle/db-goals.js');
+  const body = dbGoals.slice(dbGoals.indexOf('async function archiveGoalWithDispositions'));
+  assert.match(body, /`Abandoned: \$\{reason\}`/,
+    'the same stamp abandonTask writes, so the ledger reads identically whichever door was used');
+});
+
+test('a move into a closed goal is refused, via the ONE definition of "not open"', () => {
+  // The route resolves move targets and applies goalNotOpenRefusal (BV1.R05)
+  // rather than re-typing the status list — two spellings of "open" is how the
+  // three task-create vectors drifted apart in the first place.
+  assert.match(ARCHIVE, /goalNotOpenRefusal\(dest\)/);
+  assert.equal(/dest\.status === 'open'|dest\.status !== 'open'/.test(ARCHIVE), false,
+    'the route must not re-implement the open test');
+});

package/tests/goal_archive_route_e2e.mjs

@@ -0,0 +1,135 @@
+// tests/goal_archive_route_e2e.mjs — the archive two-step over real HTTP
+// (BV1.R14, task 1003601, goal 1000086, ADR 0250 D3).
+//
+// WHY A SECOND FILE. goal_archive_disposition.mjs pins the two halves in
+// isolation — the pure planner's truth table, and the writer's transaction shape
+// against a fake pool. Neither exercises the WIRING: that the route reads the
+// body it declares, calls the planner with the right arguments, renders its
+// verdict verbatim, resolves move targets BEFORE writing, and hands the writer a
+// plan. Every one of those is a place a correct planner and a correct writer can
+// still add up to a broken endpoint, and each was a real risk on this change
+// (the route previously read no body at all).
+//
+// So this drives the REAL router over a real socket, with the db layer stubbed at
+// the module boundary the way task_visual_route_gate.mjs does — the router under
+// test is the shipped one, not a re-assembly of it.
+//
+// THE CASE WORTH THE FILE ON ITS OWN is #6: a typo'd `disposition` (singular).
+// Without the ADR 0118 schema the handler reads `req.body.dispositions` as
+// undefined and takes the REFUSAL branch — so a caller who wrote a complete map
+// under a misspelled key is told the goal holds open work, which is true,
+// unhelpful, and indistinguishable from having sent nothing. That is the failure
+// shape that teaches an agent to retry with a different map instead of fixing the
+// key.
+//
+// Run:  node tests/goal_archive_route_e2e.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+process.env.NODE_ENV = 'test';
+
+const express = require('express');
+const api = require('../src/module-api.js');
+const db = require('../modules/lifecycle/db.js');
+
+api.requireBuilder = (req, _res, next) => { req.builder = { id: '3', rank: 'archon' }; next(); };
+api.requirePermission = () => (req, _res, next) => next();
+
+let GOALS = {
+  7:  { id: 7, status: 'open', title: 'cut me', version_id: 'BONGOS-V1' },
+  42: { id: 42, status: 'open', title: 'survivor', version_id: 'BONGOS-V1' },
+  99: { id: 99, status: 'archived', title: 'closed', version_id: 'BONGOS-V1' },
+};
+let OPEN = [{ id: '1', title: 'one', status: 'ready' }, { id: '2', title: 'two', status: 'active' }];
+let applied = null;
+db.getGoal = async (id) => GOALS[Number(id)] ?? null;
+db.isGoalMember = async () => true;
+db.openTasksInGoal = async () => ({ total: OPEN.length, tasks: OPEN });
+db.setGoalStatus = async ({ goalId }) => ({ ...GOALS[goalId], status: 'archived' });
+db.archiveGoalWithDispositions = async ({ goalId, plan, reason }) => {
+  applied = { goalId, plan, reason };
+  return { goal: { ...GOALS[goalId], status: 'archived' }, applied: plan.map(p => ({ task_id: String(p.taskId), verb: p.verb, result: p.verb === 'abandon' ? 'abandoned' : 'moved' })) };
+};
+
+const app = express();
+app.use(express.json());
+app.use((req, res, next) => {
+  res.fail = (code, statusOrOpts, details) => {
+    const o = typeof statusOrOpts === 'number' ? { status: statusOrOpts } : (statusOrOpts || {});
+    return res.status(o.status || 400).json({ error: code, message: o.message, details: o.details ?? details });
+  };
+  next();
+});
+app.use('/api/gds', require('../modules/lifecycle/routes/goals.js')());
+const server = app.listen(0);
+await new Promise(r => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/gds`;
+const post = async (p, body) => {
+  const r = await fetch(base + p, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body ?? {}) });
+  return { status: r.status, body: await r.json().catch(() => null) };
+};
+
+let n = 0; const ok = (m) => { n++; console.log('  ✓', m); };
+
+// 1. bare archive of a goal holding work → the R10 refusal, WITH the tasks
+let r = await post('/goals/7/archive');
+assert.equal(r.status, 409); assert.equal(r.body.error, 'goal_holds_open_tasks');
+assert.equal(r.body.details.tasks.length, 2);
+ok('bare archive refuses 409 goal_holds_open_tasks and returns both tasks');
+
+// 2. a partial map → refused, names the undecided task
+r = await post('/goals/7/archive', { reason: 'cut', dispositions: { 1: { verb: 'abandon' } } });
+assert.equal(r.status, 400); assert.equal(r.body.error, 'disposition_incomplete');
+assert.deepEqual(r.body.details.tasks.map(t => t.id), ['2']);
+ok('partial map refuses 400 disposition_incomplete, naming task 2');
+
+// 3. complete map with no reason → refused
+r = await post('/goals/7/archive', { dispositions: { 1: { verb: 'abandon' }, 2: { verb: 'abandon' } } });
+assert.equal(r.status, 400); assert.equal(r.body.error, 'archive_reason_required');
+ok('an abandon with no reason refuses 400 archive_reason_required');
+
+// 4. move into a CLOSED goal → refused before any write
+applied = null;
+r = await post('/goals/7/archive', { reason: 'cut', dispositions: { 1: { verb: 'move', goal_id: 99 }, 2: { verb: 'abandon' } } });
+assert.equal(r.status, 409); assert.equal(r.body.error, 'bad_disposition');
+assert.equal(applied, null, 'nothing was written');
+ok('move into an archived goal refuses 409 bad_disposition, writing nothing');
+
+// 5. move into the goal being archived → refused
+r = await post('/goals/7/archive', { reason: 'cut', dispositions: { 1: { verb: 'move', goal_id: 7 }, 2: { verb: 'abandon' } } });
+assert.equal(r.status, 400); assert.equal(r.body.error, 'bad_disposition');
+ok('move into the goal being archived refuses 400 bad_disposition');
+
+// 6. unknown body field → rejected by the ADR 0118 schema
+r = await post('/goals/7/archive', { reason: 'cut', disposition: { 1: { verb: 'abandon' } } });
+assert.equal(r.status, 400);
+assert.equal(r.body.error?.code ?? r.body.error, 'validation_failed');
+ok('a typo\'d `disposition` (singular) is rejected as validation_failed, not read as "none given"');
+
+// 7. THE HAPPY PATH — complete map, one abandon + one move
+applied = null;
+r = await post('/goals/7/archive', { reason: 'cut in the ten-areas review', dispositions: { 1: { verb: 'abandon' }, 2: { verb: 'move', goal_id: 42 } } });
+assert.equal(r.status, 200, JSON.stringify(r.body));
+assert.equal(r.body.goal.status, 'archived');
+assert.deepEqual(r.body.applied, [
+  { task_id: '1', verb: 'abandon', result: 'abandoned' },
+  { task_id: '2', verb: 'move', result: 'moved' },
+]);
+assert.deepEqual(applied.plan, [
+  { taskId: 1, verb: 'abandon', toGoalId: null },
+  { taskId: 2, verb: 'move', toGoalId: 42 },
+]);
+assert.equal(applied.reason, 'cut in the ten-areas review');
+ok('a complete map archives the goal and reports what happened to each task');
+
+// 8. a goal holding nothing is still ONE call, no reason needed
+OPEN = [];
+r = await post('/goals/7/archive');
+assert.equal(r.status, 200); assert.equal(r.body.goal.status, 'archived');
+assert.deepEqual(r.body.applied, []);
+ok('a goal holding nothing archives in one call with no reason');
+
+assert.equal(n, 8, 'every check must run — an early return would pass silently');
+console.log(`\n${n}/8 end-to-end checks passed against the real router.`);
+server.close();

package/tests/rename_history_restraint.mjs

@@ -0,0 +1,236 @@
+// tests/rename_history_restraint.mjs — the RESTRAINT half of the GDS→Bongos
+// rename (task 1003697, criterion C5 of goal 1000073: "history is intact and
+// the alias still answers").
+//
+// WHY THE NEGATIVE CASES ARE THE LOAD-BEARING ONES. Its sibling
+// tests/fitness_gds_ratchet.mjs makes the same argument and it applies twice as
+// hard here: a restraint check that only asserts today's tree is clean would
+// pass identically if every checker returned "ok" unconditionally. So each of
+// the four properties gets a synthetic FORBIDDEN change and an assertion that
+// the checker FAILS it. The positive case is the cheap half.
+//
+// The checkers are pure and take their inputs explicitly, so every case names
+// its own paths and counts. Nothing here writes to the repo — the unit lane
+// runs test files in parallel, and an earlier version of the ratchet test
+// proved what happens when a suite edits a tree another suite is scanning.
+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 check = require(path.join(ROOT, 'scripts', 'gds', 'rename-history-check.js'));
+const scan = require(path.join(ROOT, 'scripts', 'gds', 'gds-literal-scan.js'));
+
+const LITERAL = ['G', 'D', 'S'].join(''); // built, not written, so the fixtures below carry no vocabulary of their own
+
+// ---------- 1. frozen filenames: a renamed applied migration RE-RUNS ----------
+
+test('a migration that kept its name passes', () => {
+  const pinned = ['migrations/019_rename_pms_v3_to_gds_v3.sql'];
+  const r = check.checkFrozenFilenames({ present: pinned, pinned });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.missing, []);
+});
+
+test('a RENAMED migration fails and is named — schema_migrations keys on the stem', () => {
+  const pinned = [
+    'migrations/019_rename_pms_v3_to_gds_v3.sql',
+    'modules/economy/migrations/economy_001_fix_gds_shipper_description.sql',
+  ];
+  // exactly what a scripts/gds/ → scripts/bongos/ codemod would do to these two
+  const present = [
+    'migrations/019_rename_pms_v3_to_bongos_v3.sql',
+    'modules/economy/migrations/economy_001_fix_bongos_shipper_description.sql',
+  ];
+  const r = check.checkFrozenFilenames({ present, pinned });
+  assert.equal(r.ok, false, 'a renamed migration MUST fail — it reads as unapplied and re-runs');
+  assert.deepEqual(r.missing, pinned);
+});
+
+test('a DELETED migration fails the same way as a renamed one', () => {
+  const r = check.checkFrozenFilenames({ present: [], pinned: ['migrations/001_init.sql'] });
+  assert.equal(r.ok, false);
+  assert.deepEqual(r.missing, ['migrations/001_init.sql']);
+});
+
+test('a NEW migration alongside the pinned ones is fine — the list is a floor', () => {
+  const r = check.checkFrozenFilenames({
+    present: ['migrations/001_init.sql', 'migrations/999_new.sql'],
+    pinned: ['migrations/001_init.sql'],
+  });
+  assert.equal(r.ok, true);
+});
+
+// ---------- 2. frozen literal floors: a rewritten ADR erases the evidence ----------
+
+test('an unchanged record passes, and MORE occurrences pass — the floor only stops erasure', () => {
+  const floors = { 'docs/adr/0064-rename.md': 12 };
+  assert.equal(check.checkFrozenLiteralFloors({ counts: { 'docs/adr/0064-rename.md': 12 }, floors }).ok, true);
+  assert.equal(check.checkFrozenLiteralFloors({ counts: { 'docs/adr/0064-rename.md': 30 }, floors }).ok, true);
+});
+
+test('an ADR REWRITTEN to today’s vocabulary fails, with the before/after', () => {
+  const r = check.checkFrozenLiteralFloors({
+    counts: { 'docs/adr/0064-rename.md': 3 },
+    floors: { 'docs/adr/0064-rename.md': 12 },
+  });
+  assert.equal(r.ok, false, 'rewriting the record MUST fail — it destroys the evidence the words changed');
+  assert.deepEqual(r.dropped, [{ path: 'docs/adr/0064-rename.md', was: 12, now: 3 }]);
+});
+
+test('a DELETED record counts as zero — deleting fails as loudly as rewriting', () => {
+  const r = check.checkFrozenLiteralFloors({
+    counts: {},
+    floors: { 'docs/session-logs/2026-09-06-something.md': 4 },
+  });
+  assert.equal(r.ok, false);
+  assert.deepEqual(r.dropped, [{ path: 'docs/session-logs/2026-09-06-something.md', was: 4, now: 0 }]);
+});
+
+test('every dropped file is reported, not just the first', () => {
+  const r = check.checkFrozenLiteralFloors({
+    counts: { 'docs/adr/a.md': 0, 'docs/adr/b.md': 1 },
+    floors: { 'docs/adr/a.md': 5, 'docs/adr/b.md': 5, 'docs/adr/c.md': 5 },
+  });
+  assert.equal(r.dropped.length, 3, 'a codemod breaks many files at once; one-at-a-time reporting is useless');
+});
+
+// ---------- 3. version ids are row keys, not vocabulary ----------
+
+test('version id floors pass when the keys survive, fail on a blanket find-replace', () => {
+  const floors = { 'GDS-V3': 183, 'GDS-V4': 188 };
+  assert.equal(check.checkVersionIdFloors({ counts: { 'GDS-V3': 183, 'GDS-V4': 200 }, floors }).ok, true);
+
+  const r = check.checkVersionIdFloors({ counts: { 'GDS-V3': 0, 'GDS-V4': 188 }, floors });
+  assert.equal(r.ok, false, 'rewriting a version id MUST fail — it is a row key and stops resolving');
+  assert.deepEqual(r.dropped, [{ id: 'GDS-V3', was: 183, now: 0 }]);
+});
+
+test('the ratchet deliberately ignores version ids, so THIS check is the only thing watching them', () => {
+  // gds-literal-scan strips version ids before counting — that is correct for
+  // the ratchet and is exactly why the floors above have to exist.
+  assert.equal(scan.countInText(`${LITERAL}-V3 and ${LITERAL}-V4`), 0);
+  assert.deepEqual(check.PINNED_VERSION_IDS, ['GDS-V3', 'GDS-V4']);
+});
+
+// ---------- 4. the permanent alias mount ----------
+
+test('the alias mount passes while present and FAILS when dropped', () => {
+  const required = ['/api/gds'];
+  assert.equal(check.checkAliasMounts({ mounts: ['/api/bongos/v1', '/api/bongos', '/api/gds'], required }).ok, true);
+
+  const r = check.checkAliasMounts({ mounts: ['/api/bongos/v1', '/api/bongos'], required });
+  assert.equal(r.ok, false, 'shipped Dev Box binaries call the alias and cannot be force-updated');
+  assert.deepEqual(r.missing, ['/api/gds']);
+});
+
+test('the alias is asserted against the real exported mount list, not a grep', () => {
+  // A comment mentioning the alias must not be able to satisfy the check.
+  const { ALL_API_PREFIXES } = require(path.join(ROOT, 'src', 'bongos', 'api-prefix.js'));
+  assert.ok(ALL_API_PREFIXES.includes('/api/gds'), 'src/bongos/api-prefix.js still mounts the permanent alias');
+});
+
+// ---------- runAll: one broken codemod reports every property it broke ----------
+
+test('runAll reports ALL four failures together', () => {
+  const observed = {
+    migrationFiles: [],
+    frozenLiteralCounts: {},
+    versionIdCounts: { 'GDS-V3': 0, 'GDS-V4': 0 },
+    aliasMounts: ['/api/bongos'],
+  };
+  const baseline = {
+    migrationFiles: ['migrations/001_init.sql'],
+    frozenLiteralFloors: { 'docs/adr/0064-rename.md': 12 },
+    versionIdFloors: { 'GDS-V3': 183, 'GDS-V4': 188 },
+  };
+  const report = check.runAll({ observed, baseline });
+  assert.equal(report.ok, false);
+  for (const key of ['frozenFilenames', 'frozenLiteralFloors', 'versionIdFloors', 'aliasMounts']) {
+    assert.equal(report.results[key].ok, false, `${key} should have failed`);
+  }
+  const text = check.describe(report).join('\n');
+  for (const fragment of ['RE-RUNS', 'ERASED', 'REWRITTEN', 'REMOVED']) {
+    assert.ok(text.includes(fragment), `the failure report should say what broke: ${fragment}`);
+  }
+});
+
+// ---------- observe(): the aggregation, on injected inputs ----------
+
+test('observe classifies frozen vs go-forward files and counts version ids everywhere', () => {
+  const files = [
+    'docs/adr/0064-rename.md',
+    'migrations/019_rename_pms_v3_to_gds_v3.sql',
+    'modules/economy/migrations/economy_001_fix_gds_shipper_description.sql',
+    'src/bongos/routes.js',
+  ];
+  const texts = {
+    'docs/adr/0064-rename.md': `the ${LITERAL} acronym, twice: ${LITERAL}. and version GDS-V3`,
+    'migrations/019_rename_pms_v3_to_gds_v3.sql': '-- GDS-V3',
+    'modules/economy/migrations/economy_001_fix_gds_shipper_description.sql': '-- nothing',
+    'src/bongos/routes.js': `a go-forward mention of ${LITERAL} that this check does NOT pin`,
+  };
+  const observed = check.observe({
+    files,
+    readFile: (p) => texts[p],
+    aliasMounts: ['/api/gds'],
+  });
+
+  // module-owned migrations are found by the same rule as the core's
+  assert.deepEqual(observed.migrationFiles, [
+    'migrations/019_rename_pms_v3_to_gds_v3.sql',
+    'modules/economy/migrations/economy_001_fix_gds_shipper_description.sql',
+  ]);
+  // the frozen record is floored; a go-forward file is NOT (that is the ratchet's job)
+  assert.deepEqual(Object.keys(observed.frozenLiteralCounts), ['docs/adr/0064-rename.md']);
+  assert.equal(observed.frozenLiteralCounts['docs/adr/0064-rename.md'], 2, 'the version id on the line is not counted as vocabulary');
+  // version ids are counted across every file, frozen or not
+  assert.equal(observed.versionIdCounts['GDS-V3'], 2);
+  assert.equal(observed.versionIdCounts['GDS-V4'], 0);
+});
+
+test('the shared version-id regexes carry no state between files', () => {
+  // observe() compiles the version-id regexes ONCE and reuses them across every
+  // tracked file. That is only safe because String.match with a global regex
+  // ignores lastIndex — so count the same id across several files and assert
+  // none of them are silently skipped.
+  const files = ['a.md', 'b.md', 'c.md', 'd.md'];
+  const observed = check.observe({
+    files,
+    readFile: () => 'GDS-V3 GDS-V3 GDS-V4',
+    aliasMounts: ['/api/gds'],
+  });
+  assert.equal(observed.versionIdCounts['GDS-V3'], 8, 'two per file across four files');
+  assert.equal(observed.versionIdCounts['GDS-V4'], 4);
+});
+
+test('observe skips a binary file instead of guessing at its contents', () => {
+  const observed = check.observe({
+    files: ['docs/adr/logo.png'],
+    readFile: () => `${String.fromCharCode(0)}${LITERAL}`,
+    aliasMounts: ['/api/gds'],
+  });
+  assert.deepEqual(observed.frozenLiteralCounts, {});
+});
+
+// ---------- the committed baseline, and today's tree ----------
+
+test('the committed baseline pins the two migrations that literally carry the old name', () => {
+  const baseline = check.loadBaseline();
+  for (const p of [
+    'migrations/019_rename_pms_v3_to_gds_v3.sql',
+    'modules/economy/migrations/economy_001_fix_gds_shipper_description.sql',
+  ]) {
+    assert.ok(baseline.migrationFiles.includes(p), `baseline must pin ${p} — it sits directly in a codemod's path`);
+  }
+  assert.ok(baseline.migrationFiles.length > 100, 'every migration filename is pinned, not a sample');
+  assert.ok(Object.keys(baseline.frozenLiteralFloors).length > 100, 'the frozen record is pinned per file');
+});
+
+test('today’s tree passes — the cheap half, asserted last', () => {
+  const report = check.runAll({ observed: check.observe(), baseline: check.loadBaseline() });
+  assert.equal(report.ok, true, check.describe(report).join('\n'));
+});