@bongos/core 1.18.0 → 1.18.18

package/tests/route_rank_check.mjs

@@ -80,6 +80,109 @@ test('a route declared with NO middleware does not borrow the NEXT route\'s rank
   assert.equal(rows.find((x) => x.method === 'POST').rank, 'archon');
 });
 
+// ---------- BV1.R109b: multi-line route DECLARATIONS are visible at all ----------
+//
+// Distinct from the "multi-line middleware" test above: there the METHOD AND PATH were
+// still on one line and only the middleware wrapped. Here the declaration itself opens
+// on its own line and the PATH is below it — the form that made 10 real routes (6 of
+// them writes) invisible to this auditor entirely: never gate-checked, never pinned,
+// never published to the API contract.
+
+test('multi-line DECLARATION (path on the next line) is discovered [BV1.R109b]', () => {
+  const src = [
+    '  router.get(',
+    "    '/security/adr',",
+    '    auth.requireBuilder,',
+    "    auth.requireRank('metic', 'archon'),",
+    '    async (_req, res) => {',
+    '      res.json({});',
+    '    }',
+    '  );',
+  ].join('\n');
+  const r = rrc.classifyText(src);
+  assert.equal(r.length, 1, 'a multi-line declaration must emit exactly one route');
+  assert.equal(r[0].key, 'GET /security/adr');
+  assert.equal(r[0].rank, 'metic+archon', 'the gate scan must still find middleware below the path line');
+});
+
+test('multi-line declaration with an interleaved comment still resolves [BV1.R109b]', () => {
+  const src = [
+    '  router.post(',
+    '    // the path lives below this note',
+    "    '/x',",
+    "    auth.requireRank('archon'),",
+    '    h);',
+  ].join('\n');
+  assert.equal(rrc.classifyText(src)[0].key, 'POST /x');
+});
+
+test('an UNRESOLVABLE path is not silently emitted, and reds as a finding [BV1.R109b]', () => {
+  // A computed path can't be classified. The old scanner dropped it silently; the fix
+  // must FAIL CLOSED — no invented route row, and a hard finding from checkRouteRanks.
+  const src = "  router.post(\n    BASE + '/x',\n    auth.requireRank('archon'),\n    h);";
+  assert.equal(rrc.classifyText(src).length, 0, 'must not invent a route with a bogus path');
+  const decls = rrc.scanDeclarations(src);
+  assert.equal(decls.length, 1, 'the declaration must still be COUNTED (the census sees it)');
+  assert.equal(decls[0].route, null);
+  assert.equal(decls[0].method, 'POST');
+});
+
+test('scanDeclarations counts both forms and never loses one [BV1.R109b]', () => {
+  const src = [
+    "  router.get('/a', h);",
+    '  router.post(',
+    "    '/b',",
+    '    h);',
+    "  // router.get('/not-a-route', h);  <- a commented-out line is not a declaration",
+  ].join('\n');
+  const decls = rrc.scanDeclarations(src);
+  assert.deepEqual(decls.map((d) => `${d.method} ${d.route}`), ['GET /a', 'POST /b']);
+});
+
+test('a multi-line WRITE route with NO gate hard-fails the build [BV1.R109b fixture]', () => {
+  // The whole point of the fix: before it, this route was INVISIBLE, so deleting its
+  // gate kept the build green. Now it must trip the ungated-write blocker.
+  const os = require('node:os');
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rrc-multiline-'));
+  fs.writeFileSync(path.join(dir, 'shim.js'), [
+    '  router.post(',
+    "    '/danger',",
+    '    async (req, res) => {',
+    '      res.json({});',
+    '    }',
+    '  );',
+  ].join('\n'));
+  const res = rrc.checkRouteRanks({ routesDir: dir, modulesDir: path.join(dir, '__no_modules__') });
+  fs.rmSync(dir, { recursive: true, force: true });
+
+  const ungated = res.findings.find((f) => f.route === 'POST /danger');
+  assert.ok(ungated, 'the multi-line write route must be DISCOVERED (it was invisible before R109b)');
+  assert.equal(ungated.severity, 'blocker', 'an ungated write route is a hard fail');
+  assert.equal(res.hardFail, true);
+});
+
+test('an UNRESOLVABLE multi-line write declaration also hard-fails [BV1.R109b fixture]', () => {
+  const os = require('node:os');
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rrc-unresolved-'));
+  fs.writeFileSync(path.join(dir, 'shim.js'), [
+    '  router.post(',
+    '    ROUTES.danger,',
+    "    auth.requireRank('archon'),",
+    '    h);',
+  ].join('\n'));
+  const res = rrc.checkRouteRanks({ routesDir: dir, modulesDir: path.join(dir, '__no_modules__') });
+  fs.rmSync(dir, { recursive: true, force: true });
+
+  const f = res.findings.find((x) => x.rank === '(unparsed)');
+  assert.ok(f, 'a declaration whose path cannot be resolved must surface a finding, not vanish');
+  assert.equal(f.severity, 'blocker', 'an unverifiable WRITE declaration is a hard fail');
+  assert.equal(res.hardFail, true);
+});
+
 // ---------- classifyText: `rank:` annotation fallback ----------
 
 test('rank: annotation directly above → classifies', () => {
@@ -118,6 +221,79 @@ test('typo annotation (not a known rank) → unknown', () => {
   assert.equal(r[0].rank, 'unknown', 'a misspelled rank surfaces rather than being trusted');
 });
 
+// ---------- BV1.R109d: a COMMENT is not a gate ----------
+// A `rank:` annotation is reached ONLY when no middleware was found, so a comment
+// naming a privileged rank asserts a gate that provably does not exist. Before this,
+// such a route satisfied the ungated-write invariant AND every exact pin.
+
+test('provenance: a real gate is `middleware`, a bare comment is `annotation` [BV1.R109d]', () => {
+  const gated = rrc.classifyText(`  router.post('/x', auth.requireBuilder, auth.requireRank('archon'), h);`);
+  assert.equal(gated[0].via, 'middleware');
+  const claimed = rrc.classifyText(`  // rank: archon\n  router.post('/x', h);`);
+  assert.equal(claimed[0].via, 'annotation');
+  assert.equal(claimed[0].rank, 'archon', 'the label is still read — it is the PROVENANCE that differs');
+});
+
+test('a bare identifier gate (destructured doorway) counts as middleware [BV1.R109d]', () => {
+  // modules/platform-identity does `const { requireBuilder, requireRank } = api` and
+  // passes BARE identifiers. Recognising only the namespaced spelling made 11 correctly
+  // gated routes — 5 of them archon — visible to the auditor only via their comment.
+  const r = rrc.classifyText(`  router.post('/projects', requireBuilder, requireRank('archon'), h);`);
+  assert.equal(r[0].rank, 'archon');
+  assert.equal(r[0].via, 'middleware', 'a destructured guard is a real gate, not prose');
+});
+
+test('the identifier in PROSE never counts as a gate [BV1.R109d]', () => {
+  const r = rrc.classifyText(`  // this route used to call requireRank('archon') before the migration\n  // rank: public\n  router.get('/x', h);`);
+  assert.equal(r[0].via, 'annotation', 'a guard name inside a comment is not argument position');
+  assert.equal(r[0].rank, 'public');
+});
+
+test('a privileged comment-only WRITE route hard-fails the build [BV1.R109d]', () => {
+  const os = require('node:os'); const fs = require('node:fs'); const path = require('node:path');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rrc-r109d-'));
+  fs.writeFileSync(path.join(dir, 'shim.js'), `  // rank: archon\n  router.patch('/builders/:id/rank', h);\n`);
+  const res = rrc.checkRouteRanks({ routesDir: dir, modulesDir: path.join(dir, '__none__') });
+  // The load-bearing assertion is the SPECIFIC finding below, not hardFail — a shim dir
+  // hardFails anyway on the missing pinned routes, so hardFail alone proves nothing here.
+  const f = res.findings.find((x) => x.route.includes('/builders/:id/rank') && /carries NO auth middleware/.test(x.summary));
+  assert.ok(f, `expected a comment-only finding; got: ${res.findings.map((x) => x.summary).join(' | ')}`);
+  assert.equal(f.severity, 'blocker');
+});
+
+test('`rank: public` on an unauthenticated route still passes — no false positive [BV1.R109d]', () => {
+  const os = require('node:os'); const fs = require('node:fs'); const path = require('node:path');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rrc-r109d-pub-'));
+  fs.writeFileSync(path.join(dir, 'shim.js'), `  // rank: public\n  router.get('/healthz', h);\n`);
+  const res = rrc.checkRouteRanks({ routesDir: dir, modulesDir: path.join(dir, '__none__') });
+  // NB: assert on the comment-only findings specifically, NOT on hardFail — a shim dir
+  // contains none of the pinned routes, so every EXPECTED_RANKS pin reports "vanished"
+  // and hardFail is true for reasons this test is not about.
+  assert.equal(res.findings.filter((x) => /carries NO auth middleware/.test(x.summary)).length, 0,
+    'public is the annotation’s legitimate use and must not red');
+});
+
+test('a pin is NOT satisfiable by a comment [BV1.R109d]', () => {
+  // The pins are the deterministic alarm for "routes whose downgrade would be a real
+  // authority breach". A comment satisfying one would let prose certify authority.
+  const claimed = rrc.classifyText(`  // rank: archon\n  router.patch('/builders/:id/rank', h);`)[0];
+  assert.match(rrc.pinMismatch('archon', claimed) || '', /NO auth middleware/);
+  assert.match(rrc.pinMismatch('perm:builder.rank.set', claimed) || '', /NO auth middleware/);
+  const real = rrc.classifyText(`  router.patch('/builders/:id/rank', auth.requireBuilder, auth.requireRank('archon'), h);`)[0];
+  assert.equal(rrc.pinMismatch('archon', real), null, 'a real gate still satisfies its pin');
+});
+
+test('LIVE: no privileged route in this repo is gated only by a comment [BV1.R109d]', () => {
+  const fs = require('node:fs');
+  const offenders = [];
+  for (const { abs, rel } of rrc.discoverRouteFiles()) {
+    for (const r of rrc.classifyText(fs.readFileSync(abs, 'utf8'))) {
+      if (r.via === 'annotation' && r.rank !== 'public') offenders.push(`${r.key} (${rel}) claims '${r.rank}'`);
+    }
+  }
+  assert.deepEqual(offenders, [], 'a privileged route certified only by prose');
+});
+
 // ---------- checkRouteRanks invariant (via a fixture-free routesDir shim) ----------
 // checkRouteRanks reads files; we exercise the finding logic through the pure
 // path by constructing routes through classifyText + the documented severity
@@ -147,11 +323,17 @@ test('toWorkerResult: read-unknown only → concerns (not fail)', () => {
 
 // ---------- EXPECTED_RANKS: exact-rank pin on privileged routes (#999) ----------
 
-test('EXPECTED_RANKS: pins are non-empty and all to known ranks', () => {
+test('EXPECTED_RANKS: pins are non-empty and every value is a known rank OR a defined permission', () => {
   const keys = Object.keys(rrc.EXPECTED_RANKS);
   assert.ok(keys.length > 0, 'should pin at least one privileged route');
   for (const [k, v] of Object.entries(rrc.EXPECTED_RANKS)) {
-    assert.ok(rrc.KNOWN_RANKS.has(v), `pinned expected rank '${v}' for ${k} must be a known rank`);
+    const pin = rrc.parsePin(v);
+    if (pin.kind === 'rank') {
+      assert.ok(rrc.KNOWN_RANKS.has(pin.rank), `pinned expected rank '${v}' for ${k} must be a known rank`);
+    } else {
+      assert.notEqual(rrc.rankForPermissions(pin.perms), 'unknown',
+        `pinned permission(s) '${pin.perms.join(', ')}' for ${k} must exist in the governance catalog`);
+    }
   }
 });
 
@@ -168,21 +350,34 @@ test('EXPECTED_RANKS: a DOWNGRADE on a pinned route trips a blocker via a routes
   const emit = (key, expected) => {
     const [method, route] = key.split(' ');
     const m = method.toLowerCase();
+    const pin = rrc.parsePin(expected);
     if (key === 'PATCH /builders/:id/rank') {
       // DOWNGRADE: requireBuilder only → classifies any-builder, not archon.
       lines.push(`  router.${m}('${route}', auth.requireBuilder, h);`);
-    } else if (expected === 'archon') {
+    } else if (pin.kind === 'permission') {
+      // The MIGRATED spelling. A permission pin is satisfied by naming exactly its
+      // atoms — this arm is what proves the post-R104 gate form clears the pin.
+      lines.push(`  router.${m}('${route}', auth.requireBuilder, auth.requirePermission(${pin.perms.map((p) => `'${p}'`).join(', ')}), h);`);
+    } else if (pin.rank === 'archon') {
       lines.push(`  router.${m}('${route}', auth.requireBuilder, auth.requireRank('archon'), h);`);
-    } else if (expected === 'metic+archon') {
+    } else if (pin.rank === 'metic+archon') {
       lines.push(`  router.${m}('${route}', auth.requireRank('metic', 'archon'), h);`);
-    } else {
-      lines.push(`  // rank: ${expected}`);
+    } else if (pin.rank === 'bfg-principal') {
+      lines.push(`  router.${m}('${route}', auth.requireBuilder, auth.requireBfgPrincipal, h);`);
+    } else if (pin.rank === 'public') {
+      // The ONE honest comment-only gate: 'public' asserts nothing is protected.
+      lines.push(`  // rank: public`);
       lines.push(`  router.${m}('${route}', h);`);
+    } else {
+      // Real middleware, NOT a `rank:` comment (BV1.R109d). This branch used to emit
+      // a bare annotation, which only classified because a comment could stand in for
+      // a gate — the hole R109d closed. A pinned route must carry its real gate, or
+      // the fixture reds for a reason this test is not about.
+      lines.push(`  router.${m}('${route}', auth.requireBuilder, h);`);
     }
-    // A blank gap matching a real handler body — keeps classifyRank's 20-line
-    // middleware lookahead on the downgraded route from "borrowing" a NEIGHBOUR
-    // route's requireRank('archon') line.
-    lines.push('  });', '', '', '', '', '', '');
+    // A gap wider than classifyGate's 20-line middleware lookahead, so no route can
+    // "borrow" a NEIGHBOUR's gate — every emitted route stands on its own.
+    lines.push('  });', ...Array(21).fill(''));
   };
   // Emit every pinned route EXCEPT the downgraded one first, then the downgraded
   // one LAST (so nothing with requireRank('archon') sits within its lookahead).
@@ -198,6 +393,11 @@ test('EXPECTED_RANKS: a DOWNGRADE on a pinned route trips a blocker via a routes
   assert.ok(downgrade, 'a downgraded pinned route must surface a finding');
   assert.equal(downgrade.severity, 'blocker', 'a rank downgrade on a privileged route is a hard fail');
   assert.equal(res.hardFail, true);
+  // The other side of the same fixture: every OTHER pin is satisfied by the gate
+  // spelling it was emitted in — rank pins by requireRank/annotation, permission
+  // pins by requirePermission. A stray finding here means a pin is unsatisfiable.
+  assert.deepEqual(res.findings.map((f) => f.route), ['PATCH /builders/:id/rank'],
+    `only the deliberately-downgraded route should red; got: ${res.findings.map((f) => `${f.route} — ${f.summary}`).join(' | ')}`);
 });
 
 test('EXPECTED_RANKS: a MISSING pinned route trips a blocker (a protected route vanished)', () => {
@@ -227,14 +427,56 @@ test('LIVE: checkRouteRanks() on src/bongos/routes/ has zero unknowns', () => {
   assert.equal(res.hardFail, false);
 });
 
-test('LIVE: every pinned privileged route still classifies to its EXPECTED rank', () => {
+// The census invariant (BV1.R109b). Asserting that the 10 known multi-line paths parse
+// would prove nothing about the ELEVENTH — the next route someone declares in a form
+// this scanner doesn't handle. So count instead: every `router.<method>(` line in every
+// discovered route file must yield exactly one classified route.
+//
+// The census regex below is HAND-WRITTEN here on purpose and NOT imported from the
+// module. Importing ROUTE_DECL_RE would move both sides of the comparison together and
+// prove nothing (the oracle trap tests/route_permission_check.mjs documents).
+const CENSUS_DECL_RE = /^\s*router\.(?:get|post|patch|put|delete)\s*\(/;
+// A floor, so a change that silently guts BOTH sides (e.g. discoverRouteFiles stops
+// finding module routes) reds instead of trivially "matching" at a smaller number.
+const ROUTE_CENSUS_FLOOR = 258;
+
+test('LIVE census: every router.<method>( declaration classifies to exactly one route [BV1.R109b]', () => {
+  const fs = require('node:fs');
+  let declared = 0;
+  let classified = 0;
+  const shortfall = [];
+  for (const { abs, rel } of rrc.discoverRouteFiles()) {
+    const text = fs.readFileSync(abs, 'utf8');
+    const d = text.split('\n').filter((l) => CENSUS_DECL_RE.test(l)).length;
+    const c = rrc.classifyText(text).length;
+    declared += d;
+    classified += c;
+    if (d !== c) shortfall.push(`${rel}: ${d} declared vs ${c} classified`);
+  }
+  assert.equal(shortfall.length, 0,
+    `every declared route must be visible to the auditor; invisible in: ${shortfall.join('; ')}`);
+  assert.equal(classified, declared, 'declaration census must equal the classified route count');
+  assert.ok(declared >= ROUTE_CENSUS_FLOOR,
+    `expected at least ${ROUTE_CENSUS_FLOOR} route declarations, found ${declared} — did route discovery break?`);
+});
+
+test('LIVE: checkRouteRanks reports ZERO unparsed declarations [BV1.R109b]', () => {
+  const res = rrc.checkRouteRanks();
+  const unparsed = res.findings.filter((f) => f.rank === '(unparsed)');
+  assert.equal(unparsed.length, 0,
+    `no route declaration may be unresolvable: ${unparsed.map((f) => f.route).join(', ')}`);
+  assert.ok(res.routeCount >= ROUTE_CENSUS_FLOOR,
+    `checkRouteRanks must cover at least ${ROUTE_CENSUS_FLOOR} routes, saw ${res.routeCount}`);
+});
+
+test('LIVE: every pinned privileged route still satisfies its pin', () => {
   const res = rrc.checkRouteRanks();
   const byKey = new Map();
   for (const r of res.routes) if (!byKey.has(r.key)) byKey.set(r.key, r);
   for (const [key, expected] of Object.entries(rrc.EXPECTED_RANKS)) {
     const r = byKey.get(key);
     assert.ok(r, `pinned route ${key} must exist in the live route set`);
-    assert.equal(r.rank, expected, `pinned route ${key} must classify as '${expected}', got '${r.rank}'`);
+    assert.equal(rrc.pinMismatch(expected, r), null, `pinned route ${key}: ${rrc.pinMismatch(expected, r)}`);
   }
 });
 

package/tests/route_validation.mjs

@@ -196,10 +196,18 @@ const BLOCKERS_POST_SCHEMA = {
   source_ref: { type: 'string', maxLength: LIMITS.SOURCE_REF },
 };
 
+// Hand-mirrored from modules/ideas/routes/inbox.js's PATCH validator (the route
+// declares it inline, so there is nothing to import). Strict mode rejects
+// unknown fields, so a field missing HERE makes the mirror assert the opposite
+// of the route — keep the two in step. `reviewed_at` had already drifted out
+// when task 1002447 added the last two.
 const INBOX_PATCH_SCHEMA = {
   status: { type: 'string', enum: ['open', 'promoted', 'discarded', 'merged'] },
   kind: { type: 'string', maxLength: 64 },
   promoted_to_task_id: { type: 'integer', min: 1 },
+  reviewed_at: {},
+  merged_into_idea_id: { type: 'integer', min: 1 },
+  triage_note: { type: 'string', maxLength: 1000 },
 };
 
 // ---- supervisor hot path 1: POST /api/gds/claims with full body ----
@@ -332,6 +340,22 @@ test('inbox: PATCH /inbox/:id with status promote passes', () => {
   assert.equal(validate({ status: 'promoted', promoted_to_task_id: 254 }, INBOX_PATCH_SCHEMA), null);
 });
 
+// task 1002447 — the merge target + the verdict's reason (migration core_195).
+test('inbox: PATCH /inbox/:id merge carries a target + a note', () => {
+  const body = { status: 'merged', merged_into_idea_id: 412, triage_note: 'same request as #412' };
+  assert.equal(validate(body, INBOX_PATCH_SCHEMA), null);
+});
+
+test('inbox: PATCH /inbox/:id discard carries a reason', () => {
+  assert.equal(validate({ status: 'discarded', triage_note: 'superseded by the new gate' }, INBOX_PATCH_SCHEMA), null);
+});
+
+// A typed field still accepts an explicit null — validateField returns early
+// for a null non-required field — so the un-merge needs no untyped escape hatch.
+test('inbox: PATCH /inbox/:id may clear the merge link with null', () => {
+  assert.equal(validate({ merged_into_idea_id: null }, INBOX_PATCH_SCHEMA), null);
+});
+
 // ===========================================================================
 // C. Bad input must return structured 400, never 500.
 // ===========================================================================
@@ -400,6 +424,12 @@ test('BAD: PATCH /inbox/:id with bad status enum', () => {
   assert.ok(r.details.some((d) => d.reason === 'not_in_enum'));
 });
 
+test('BAD: PATCH /inbox/:id with an oversize triage_note → too_long', () => {
+  const r = validate({ status: 'discarded', triage_note: 'x'.repeat(1001) }, INBOX_PATCH_SCHEMA);
+  assert.ok(r);
+  assert.ok(r.details.some((d) => d.field === 'triage_note' && d.reason === 'too_long'));
+});
+
 test('BAD: POST /tasks/:id/grade with signals=string (must be object)', () => {
   const r = validate({ signals: 'oops' }, TASKS_GRADE_SCHEMA);
   assert.ok(r);

package/tests/sequence.mjs

@@ -0,0 +1,267 @@
+// tests/sequence.mjs — pure-core coverage for the sequential chain runner
+// (task 1002484). Hermetic: feeds fixtures to topoOrder/chainFrom/haltReasons;
+// no DB, no API. Run: node tests/sequence.mjs (also runs in the unit gate).
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const {
+  readArgv,
+  edgeIds,
+  rowsOf,
+  topoOrder,
+  chainFrom,
+  haltReasons,
+  summarize,
+  MIN_SPEC_CHARS,
+} = require('../scripts/gds/sequence.js');
+
+let passed = 0, failed = 0;
+const t = (n, f) => { try { f(); passed++; console.log(`  PASS  ${n}`); } catch (e) { failed++; console.log(`  FAIL  ${n}\n        ${e.message}`); } };
+
+// A description long enough to clear the thin-spec gate, so fixtures testing
+// OTHER halt reasons don't trip it incidentally.
+const SPEC = 'x'.repeat(MIN_SPEC_CHARS + 1);
+const task = (over = {}) => ({
+  id: 1, title: 'T', status: 'ready', kind: 'feature', description: SPEC,
+  touches: [], dependencies: [], dependents: [], requires_rank: 'xenos',
+  credits_reward: 10, est_minutes: 30, priority: null, ...over,
+});
+
+// ---------------------------------------------------------------- argv
+
+t('readArgv parses --from/--goal/--check in both spellings', () => {
+  assert.equal(readArgv(['--from', '7']).from, 7);
+  assert.equal(readArgv(['--from=7']).from, 7);
+  assert.equal(readArgv(['--goal=42']).goal, 42);
+  assert.equal(readArgv(['--check=9']).check, 9);
+  assert.equal(readArgv(['--from', '7', '--next']).next, true);
+  assert.equal(readArgv(['--from', '7', '--json']).json, true);
+});
+
+t('readArgv accepts a bare task id as --from', () => {
+  assert.equal(readArgv(['1002277']).from, 1002277);
+});
+
+// ---------------------------------------------------------------- edge shapes
+
+t('edgeIds tolerates both bare-number and {id} edge rows', () => {
+  assert.deepEqual(edgeIds([1, '2', { id: 3 }, { id: '4' }]), [1, 2, 3, 4]);
+  assert.deepEqual(edgeIds(null), []);
+  assert.deepEqual(edgeIds([null, undefined, 'nope']), []);
+});
+
+t('rowsOf finds the array under each envelope key the API uses', () => {
+  assert.deepEqual(rowsOf({ claimable: [{ id: 1 }] }), [{ id: 1 }]);
+  assert.deepEqual(rowsOf({ tasks: [{ id: 2 }] }), [{ id: 2 }]);
+  assert.deepEqual(rowsOf([{ id: 3 }]), [{ id: 3 }]);
+});
+
+t('rowsOf returns null (not []) for an unrecognized envelope', () => {
+  // This distinction is load-bearing: null means "could not check", which
+  // haltReasons must treat as silence rather than halting every task.
+  assert.equal(rowsOf({ error: 'boom' }), null);
+  assert.equal(rowsOf(null), null);
+});
+
+// ---------------------------------------------------------------- ordering
+
+t('topoOrder puts a dependency before its dependent', () => {
+  const { order, cycle } = topoOrder([
+    task({ id: 2, dependencies: [1] }),
+    task({ id: 1 }),
+  ]);
+  assert.deepEqual(order.map((x) => x.id), [1, 2]);
+  assert.deepEqual(cycle, []);
+});
+
+t('topoOrder handles a three-deep chain', () => {
+  const { order } = topoOrder([
+    task({ id: 3, dependencies: [2] }),
+    task({ id: 1 }),
+    task({ id: 2, dependencies: [1] }),
+  ]);
+  assert.deepEqual(order.map((x) => x.id), [1, 2, 3]);
+});
+
+t('topoOrder reports a cycle instead of silently dropping it', () => {
+  const { order, cycle } = topoOrder([
+    task({ id: 1, dependencies: [2] }),
+    task({ id: 2, dependencies: [1] }),
+  ]);
+  assert.deepEqual(order, []);
+  assert.deepEqual(cycle, [1, 2]);
+});
+
+t('topoOrder keeps the acyclic part and reports only the cyclic remainder', () => {
+  const { order, cycle } = topoOrder([
+    task({ id: 1 }),
+    task({ id: 2, dependencies: [3] }),
+    task({ id: 3, dependencies: [2] }),
+  ]);
+  assert.deepEqual(order.map((x) => x.id), [1]);
+  assert.deepEqual(cycle, [2, 3]);
+});
+
+t('topoOrder ignores dependencies pointing OUTSIDE the scope', () => {
+  // An out-of-scope dep must not stall ordering — it surfaces later as a
+  // deps_unmet halt, which is the honest place for it.
+  const { order, cycle } = topoOrder([task({ id: 5, dependencies: [999] })]);
+  assert.deepEqual(order.map((x) => x.id), [5]);
+  assert.deepEqual(cycle, []);
+});
+
+t('topoOrder breaks ties on priority, then estimate, then id', () => {
+  const { order } = topoOrder([
+    task({ id: 10, priority: 3, est_minutes: 5 }),
+    task({ id: 11, priority: 1, est_minutes: 90 }),
+    task({ id: 12, priority: 1, est_minutes: 10 }),
+  ]);
+  assert.deepEqual(order.map((x) => x.id), [11, 12, 10].sort((a, b) => {
+    const p = { 10: 3, 11: 1, 12: 1 }, m = { 10: 5, 11: 90, 12: 10 };
+    return p[a] - p[b] || m[a] - m[b] || a - b;
+  }));
+  assert.equal(order[0].id, 12, 'priority 1 + shortest estimate leads');
+});
+
+// ---------------------------------------------------------------- chain scope
+
+t('chainFrom walks dependents transitively', () => {
+  const rows = [
+    task({ id: 1, dependents: [2] }),
+    task({ id: 2, dependents: [3], status: 'backlog' }),
+    task({ id: 3, status: 'backlog' }),
+  ];
+  const byId = new Map(rows.map((r) => [r.id, r]));
+  assert.deepEqual(chainFrom(1, byId).map((x) => x.id), [1, 2, 3]);
+});
+
+t('chainFrom walks THROUGH a shipped task but excludes it from the plan', () => {
+  const rows = [
+    task({ id: 1, status: 'shipped', dependents: [2] }),
+    task({ id: 2, status: 'ready' }),
+  ];
+  const byId = new Map(rows.map((r) => [r.id, r]));
+  assert.deepEqual(chainFrom(1, byId).map((x) => x.id), [2]);
+});
+
+t('chainFrom does not loop forever on a cyclic dependents graph', () => {
+  const rows = [
+    task({ id: 1, dependents: [2] }),
+    task({ id: 2, dependents: [1] }),
+  ];
+  const byId = new Map(rows.map((r) => [r.id, r]));
+  assert.deepEqual(chainFrom(1, byId).map((x) => x.id).sort(), [1, 2]);
+});
+
+t('chainFrom honours the limit', () => {
+  const rows = [1, 2, 3, 4, 5].map((id) => task({ id, dependents: id < 5 ? [id + 1] : [] }));
+  const byId = new Map(rows.map((r) => [r.id, r]));
+  assert.equal(chainFrom(1, byId, { limit: 3 }).length, 3);
+});
+
+t('chainFrom stays inside its scope — an unrelated task is not pulled in', () => {
+  const rows = [task({ id: 1, dependents: [2] }), task({ id: 2 }), task({ id: 99 })];
+  const byId = new Map(rows.map((r) => [r.id, r]));
+  assert.deepEqual(chainFrom(1, byId).map((x) => x.id), [1, 2]);
+});
+
+// ---------------------------------------------------------------- halt matrix
+
+const clean = { rank: 'archon', claimableIds: new Set([1]) };
+const codes = (tk, opts = clean) => haltReasons(tk, opts).map((r) => r.code);
+
+t('a clean ready task produces no halt reasons', () => {
+  assert.deepEqual(codes(task()), []);
+});
+
+t('halts on needs_migration', () => {
+  assert.ok(codes(task({ needs_migration: true })).includes('needs_migration'));
+});
+
+t('halts on security_sensitive', () => {
+  assert.ok(codes(task({ security_sensitive: true })).includes('security_sensitive'));
+});
+
+t('halts when touches[] hits a protected path', () => {
+  const c = codes(task({ touches: ['src/bongos/auth.js'] }));
+  assert.ok(c.includes('protected_path'), `expected protected_path, got ${c}`);
+});
+
+t('does NOT flag an ordinary path as protected', () => {
+  assert.ok(!codes(task({ touches: ['modules/hall-ui/public/work.js'] })).includes('protected_path'));
+});
+
+t('halts when the task requires a rank above the builder', () => {
+  const c = haltReasons(task({ requires_rank: 'archon' }), { rank: 'xenos', claimableIds: new Set([1]) });
+  assert.ok(c.map((r) => r.code).includes('rank_floor'));
+  assert.match(c.find((r) => r.code === 'rank_floor').detail, /archon/);
+});
+
+t('does not flag rank_floor when the builder outranks the floor', () => {
+  assert.ok(!codes(task({ requires_rank: 'metic' })).includes('rank_floor'));
+});
+
+t('halts on a judgement kind (decision, spike)', () => {
+  assert.ok(codes(task({ kind: 'decision' })).includes('judgement_kind'));
+  assert.ok(codes(task({ kind: 'spike' })).includes('judgement_kind'));
+  assert.ok(!codes(task({ kind: 'feature' })).includes('judgement_kind'));
+});
+
+t('halts on a thin spec', () => {
+  assert.ok(codes(task({ description: '' })).includes('thin_spec'));
+  assert.ok(codes(task({ description: 'do the thing' })).includes('thin_spec'));
+  assert.ok(!codes(task({ description: SPEC })).includes('thin_spec'));
+});
+
+t('halts when the task is still gated (not ready)', () => {
+  assert.ok(codes(task({ status: 'backlog' })).includes('deps_unmet'));
+  assert.ok(codes(task({ status: 'blocked' })).includes('deps_unmet'));
+});
+
+t('halts when the task is already mid-ship, distinctly from deps_unmet', () => {
+  for (const status of ['active', 'completed', 'confirmed']) {
+    const c = codes(task({ status }));
+    assert.ok(c.includes('in_flight'), `${status} should read in_flight`);
+    assert.ok(!c.includes('deps_unmet'), `${status} should not read deps_unmet`);
+  }
+});
+
+t('halts when ready but absent from the server claimable feed', () => {
+  assert.ok(haltReasons(task(), { rank: 'archon', claimableIds: new Set([42]) })
+    .map((r) => r.code).includes('not_claimable'));
+});
+
+t('stays quiet about claimability when the feed could not be read', () => {
+  // The regression this guards: reading the claimable envelope under the wrong
+  // key yielded an empty set, which halted every task with not_claimable.
+  assert.deepEqual(haltReasons(task(), { rank: 'archon', claimableIds: null }), []);
+});
+
+t('reports every applicable reason, not just the first', () => {
+  const c = codes(task({ needs_migration: true, security_sensitive: true, description: '' }));
+  assert.ok(c.includes('needs_migration') && c.includes('security_sensitive') && c.includes('thin_spec'));
+});
+
+t('a missing task reports not_found rather than throwing', () => {
+  assert.deepEqual(haltReasons(null, clean).map((r) => r.code), ['not_found']);
+});
+
+// ---------------------------------------------------------------- totals
+
+t('summarize totals count, credits and calibrated minutes', () => {
+  const s = summarize([
+    task({ id: 1, credits_reward: 30, est_minutes: 20 }),
+    task({ id: 2, credits_reward: 15, est_minutes_calibrated: 7, est_minutes: 99 }),
+  ]);
+  assert.deepEqual(s, { count: 2, credits: 45, minutes: 27 });
+});
+
+t('summarize tolerates missing numbers', () => {
+  assert.deepEqual(summarize([task({ credits_reward: null, est_minutes: null })]),
+    { count: 1, credits: 0, minutes: 0 });
+});
+
+console.log(`\nsequence: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);