@bongos/core 1.18.0 → 1.18.18

package/tests/goal_routes.mjs

@@ -141,16 +141,71 @@ await test('builder_id coercion contract: Number() accepts int + numeric string,
 });
 
 // ---- listCriteriaForGoal (db helper, deps.pool seam) ----
+// task 1002164: the projection now carries the per-criterion link counts and the
+// DERIVED pending_review flag, so the hall's goal-detail page can render the
+// third criterion state (met — ready to confirm) without a second round-trip.
+const CRIT_SQL_RE = /FROM done_when_criteria WHERE goal_id = \$1/;
+const critRow = (over = {}) => ({
+  id: 1, version_id: 'V1', criterion_id: 'c1', criterion_md: 'md', satisfied: false,
+  sort_order: 6, goal_id: 3, linked_tasks: 0, unshipped_tasks: 0, ...over,
+});
+const critPool = (rows) => fakePool((s) => (CRIT_SQL_RE.test(s) ? { rows } : null));
+
 await test('listCriteriaForGoal: SELECT by goal_id, ordered, returns rows', async () => {
-  const ROW = { id: 1, version_id: 'V1', criterion_id: 'c1', criterion_md: 'md', satisfied: false, sort_order: 6, goal_id: 3 };
-  const pool = fakePool((s) => (/FROM done_when_criteria WHERE goal_id = \$1/.test(s) ? { rows: [ROW] } : null));
+  const ROW = critRow();
+  const pool = critPool([ROW]);
   const out = await listCriteriaForGoal(3, { pool });
-  assert.deepEqual(out, [ROW]);
-  const sel = find(pool.queries, /FROM done_when_criteria WHERE goal_id = \$1/);
+  assert.deepEqual(out, [{ ...ROW, pending_review: false }]);
+  const sel = find(pool.queries, CRIT_SQL_RE);
   assert.equal(sel.params[0], 3);
   assert.match(sel.sql, /ORDER BY sort_order, id/);
 });
 
+await test('listCriteriaForGoal: pending_review true when every linked task shipped and not yet confirmed', async () => {
+  const pool = critPool([critRow({ satisfied: false, linked_tasks: 2, unshipped_tasks: 0 })]);
+  const [out] = await listCriteriaForGoal(3, { pool });
+  assert.equal(out.pending_review, true);
+});
+
+await test('listCriteriaForGoal: pending_review false once the criterion is confirmed', async () => {
+  const pool = critPool([critRow({ satisfied: true, linked_tasks: 2, unshipped_tasks: 0 })]);
+  const [out] = await listCriteriaForGoal(3, { pool });
+  assert.equal(out.pending_review, false);
+});
+
+await test('listCriteriaForGoal: pending_review false with NO linked tasks (vacuous truth guard)', async () => {
+  const pool = critPool([critRow({ satisfied: false, linked_tasks: 0, unshipped_tasks: 0 })]);
+  const [out] = await listCriteriaForGoal(3, { pool });
+  assert.equal(out.pending_review, false);
+});
+
+await test('listCriteriaForGoal: pending_review false while any linked task is unshipped', async () => {
+  const pool = critPool([critRow({ satisfied: false, linked_tasks: 3, unshipped_tasks: 1 })]);
+  const [out] = await listCriteriaForGoal(3, { pool });
+  assert.equal(out.pending_review, false);
+});
+
+await test('listCriteriaForGoal: counts are aggregated ONCE, not per-row correlated subqueries', async () => {
+  // Regression guard on the query SHAPE (grader finding, task 1002164). The first
+  // cut ran two correlated COUNT(*) subqueries per criterion row — 2N index
+  // lookups for N criteria. The counts must come from a single grouped pass that
+  // is itself narrowed to this goal's criteria before grouping.
+  const pool = critPool([critRow()]);
+  await listCriteriaForGoal(3, { pool });
+  const sql = String(find(pool.queries, CRIT_SQL_RE).sql).replace(/\s+/g, ' ');
+  assert.match(sql, /GROUP BY tc\.criterion_id/, 'counts come from one GROUP BY');
+  assert.match(sql, /WHERE tc\.criterion_id IN \(SELECT id FROM crit\)/, 'the aggregate is narrowed to this goal before grouping, not over all task_criteria');
+  assert.doesNotMatch(sql, /\(SELECT count\(\*\)[^)]*FROM task_criteria[^)]*WHERE tc\.criterion_id = done_when_criteria\.id/, 'no per-row correlated count subquery');
+});
+
+await test('listCriteriaForGoal: counts arrive as numbers even if the driver returns strings', async () => {
+  // node-postgres renders bigint/count as a string unless cast; the SQL casts to
+  // ::int, but the derivation must not silently flip on a string either way.
+  const pool = critPool([critRow({ satisfied: false, linked_tasks: '2', unshipped_tasks: '0' })]);
+  const [out] = await listCriteriaForGoal(3, { pool });
+  assert.equal(out.pending_review, true);
+});
+
 // ---- POST /goals/:id/tasks — request-validation schema (the bounded-authoring
 // gate's DECISION logic + abuse matrix live in tests/goal_abuse_matrix.mjs) ----
 // The EXACT schema declared in goals.js's POST /goals/:id/tasks — keep in sync.

package/tests/goal_tier.mjs

@@ -110,19 +110,28 @@ await test('getGoal: unknown id returns null (not undefined)', async () => {
 // =========================================================================
 // listGoals
 // =========================================================================
-await test('listGoals: no args binds [null, null] (both filters off)', async () => {
+await test('listGoals: no args binds [null, null, null] (all three filters off)', async () => {
   const pool = fakePool((s) => (/FROM goals/.test(s) ? { rows: [GOAL_ROW] } : null));
   const out = await listGoals(undefined, { pool });
   assert.deepEqual(out, [GOAL_ROW]);
   const sel = find(pool.queries, /FROM goals/);
-  assert.deepEqual(sel.params, [null, null]);
+  // task 1002539 added an OPTIONAL limit. Postgres treats `LIMIT NULL` as unbounded,
+  // so the goal board's read is byte-for-byte unchanged in behaviour.
+  assert.deepEqual(sel.params, [null, null, null]);
   assert.match(sel.sql, /ORDER BY version_id, sort_order, created_at, id/, 'priority-first, then stable ordering');
+  assert.match(sel.sql, /LIMIT \$3::int/, 'the limit is bound, never interpolated');
 });
 
 await test('listGoals: versionId + status flow through to the bound params', async () => {
   const pool = fakePool((s) => (/FROM goals/.test(s) ? { rows: [] } : null));
   await listGoals({ versionId: 'BONGOS-V1', status: 'open' }, { pool });
-  assert.deepEqual(find(pool.queries, /FROM goals/).params, ['BONGOS-V1', 'open']);
+  assert.deepEqual(find(pool.queries, /FROM goals/).params, ['BONGOS-V1', 'open', null]);
+});
+
+await test('listGoals: an explicit limit is bound so Postgres truncates, not JS', async () => {
+  const pool = fakePool((s) => (/FROM goals/.test(s) ? { rows: [] } : null));
+  await listGoals({ versionId: 'BONGOS-V1', status: 'open', limit: 6 }, { pool });
+  assert.deepEqual(find(pool.queries, /FROM goals/).params, ['BONGOS-V1', 'open', 6]);
 });
 
 // =========================================================================

package/tests/governance_catalog.mjs

@@ -0,0 +1,129 @@
+// tests/governance_catalog.mjs — the permission catalog + compat seed (BV1.R94, ADR 0151).
+//
+// Guards the "zero day-one behavior change" promise structurally: the seed is
+// DERIVED from per-permission floors, so these invariants prove the derivation is
+// sound before R93 transcribes it into DB rows and R103 runs the live parity test.
+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 cat = require(path.join(ROOT, 'modules', 'governance', 'catalog.js'));
+const { PERMISSIONS, RANK_ORDER, RANK_ROLE_SEED, permissionKeys, byKey, isSystem, isGrantable, systemKeys, grantableKeys, seedForRank } = cat;
+
+test('every permission is well-formed (key, boolean system, valid floor)', () => {
+  assert.ok(PERMISSIONS.length >= 60, `expected a substantial catalog, saw ${PERMISSIONS.length}`);
+  for (const p of PERMISSIONS) {
+    assert.equal(typeof p.key, 'string');
+    assert.ok(p.key.length > 0, 'non-empty key');
+    assert.equal(typeof p.system, 'boolean', `${p.key} system must be boolean`);
+    assert.ok(p.floor === null || RANK_ORDER.includes(p.floor), `${p.key} floor "${p.floor}" invalid`);
+  }
+});
+
+test('keys are unique', () => {
+  const keys = permissionKeys();
+  assert.equal(new Set(keys).size, keys.length, 'duplicate permission key');
+});
+
+test('system and operational partition the catalog exactly', () => {
+  const sys = new Set(systemKeys());
+  const op = new Set(grantableKeys());
+  assert.equal(sys.size + op.size, PERMISSIONS.length);
+  for (const k of sys) assert.ok(!op.has(k), `${k} in both sets`);
+  // union === all
+  assert.deepEqual([...sys, ...op].sort(), permissionKeys().slice().sort());
+});
+
+test('isGrantable: operational→true, system→false, unknown→false', () => {
+  assert.equal(isGrantable('idea.triage'), true);
+  assert.equal(isGrantable('builder.rank.set'), false); // system
+  assert.equal(isGrantable('deploy.push_main'), false); // system
+  assert.equal(isGrantable('nope.not.a.key'), false); // unknown fails closed
+  assert.equal(isSystem('nope.not.a.key'), null); // unknown → null (caller fails closed)
+});
+
+test('the four rank-roles exist; seed keys all reference real permissions', () => {
+  assert.deepEqual(Object.keys(RANK_ROLE_SEED).sort(), [...RANK_ORDER].sort());
+  const all = new Set(permissionKeys());
+  for (const rank of RANK_ORDER) {
+    for (const k of RANK_ROLE_SEED[rank]) assert.ok(all.has(k), `seed[${rank}] references unknown ${k}`);
+  }
+});
+
+test('seed is cumulative: archon ⊇ metic ⊇ thetes ⊇ xenos (nested supersets)', () => {
+  for (let i = 1; i < RANK_ORDER.length; i++) {
+    const lower = new Set(RANK_ROLE_SEED[RANK_ORDER[i - 1]]);
+    const higher = new Set(RANK_ROLE_SEED[RANK_ORDER[i]]);
+    for (const k of lower) assert.ok(higher.has(k), `${RANK_ORDER[i]} missing ${k} that ${RANK_ORDER[i - 1]} has`);
+    assert.ok(higher.size > lower.size, `${RANK_ORDER[i]} should strictly extend ${RANK_ORDER[i - 1]}`);
+  }
+});
+
+test('a role holds a permission iff its floor is a real rank at-or-below (derivation is faithful)', () => {
+  for (const rank of RANK_ORDER) {
+    const held = new Set(RANK_ROLE_SEED[rank]);
+    const tier = RANK_ORDER.indexOf(rank);
+    for (const p of PERMISSIONS) {
+      const shouldHold = p.floor !== null && RANK_ORDER.indexOf(p.floor) <= tier;
+      assert.equal(held.has(p.key), shouldHold, `${rank} vs ${p.key} (floor ${p.floor})`);
+    }
+  }
+});
+
+test('system permissions are Archon-only in the seed (never in xenos/thetes/metic)', () => {
+  for (const rank of ['xenos', 'thetes', 'metic']) {
+    for (const k of RANK_ROLE_SEED[rank]) {
+      assert.equal(isSystem(k), false, `${rank} seed must not hold system perm ${k}`);
+    }
+  }
+  // and archon DOES hold the archon-floored system perms (that is how Archon gets its power)
+  const archon = new Set(RANK_ROLE_SEED.archon);
+  assert.ok(archon.has('builder.rank.set'));
+  assert.ok(archon.has('deploy.push_main'));
+});
+
+test('machine principals are held by NO rank-role and are system + floor null', () => {
+  for (const p of PERMISSIONS.filter((x) => x.key.startsWith('principal.'))) {
+    assert.equal(p.system, true, `${p.key} must be system`);
+    assert.equal(p.floor, null, `${p.key} must have floor null (held by no rank-role)`);
+    for (const rank of RANK_ORDER) {
+      assert.ok(!RANK_ROLE_SEED[rank].includes(p.key), `${rank} must not hold principal ${p.key}`);
+    }
+  }
+  assert.ok(PERMISSIONS.some((p) => p.key === 'principal.bfg'));
+});
+
+test('threshold spot-checks reproduce today\'s requireRank floors', () => {
+  const has = (rank, k) => RANK_ROLE_SEED[rank].includes(k);
+  // idea.triage: metic+ only (requireRank('metic','archon'))
+  assert.equal(has('xenos', 'idea.triage'), false);
+  assert.equal(has('thetes', 'idea.triage'), false);
+  assert.equal(has('metic', 'idea.triage'), true);
+  assert.equal(has('archon', 'idea.triage'), true);
+  // task.claim.any: thetes+ (the general queue)
+  assert.equal(has('xenos', 'task.claim.any'), false);
+  assert.equal(has('thetes', 'task.claim.any'), true);
+  // builder.rank.set: archon only
+  assert.equal(has('metic', 'builder.rank.set'), false);
+  assert.equal(has('archon', 'builder.rank.set'), true);
+  // task.ship / own-work: everyone incl. xenos
+  assert.equal(has('xenos', 'task.ship'), true);
+  assert.equal(has('xenos', 'task.act.own'), true);
+});
+
+test('an unknown/reserved rank resolves to no permissions (fail-closed; ADR 0151 divergence)', () => {
+  assert.deepEqual(seedForRank('olympian'), []);
+  assert.deepEqual(seedForRank('helot'), []);
+  assert.deepEqual(seedForRank('bogus'), []);
+});
+
+test('byKey returns a frozen record or null', () => {
+  const p = byKey('governance.manage');
+  assert.ok(p && p.system === true && p.floor === 'archon');
+  assert.throws(() => { p.system = false; }, /Cannot assign|read only|frozen/i);
+  assert.equal(byKey('nope'), null);
+});

package/tests/governance_claim_eligibility.mjs

@@ -0,0 +1,262 @@
+// tests/governance_claim_eligibility.mjs — claim eligibility as PERMISSIONS
+// (BV1.R106, ADR 0151).
+//
+// DB-free. The whole point of R106 is that the queue half of claim-time authority
+// stops asking "what rank is this builder" and starts asking "does this builder
+// hold `task.claim.any` / `task.claim.newcomer`" — WITHOUT changing who can claim
+// what, and WITHOUT swallowing the per-task `requires_rank` floor, which is a
+// property of the TASK and a separate axis entirely.
+//
+// Three things are proved here:
+//
+//   A. THE TWO AXES STAY SEPARATE. Holding `task.claim.any` does not lift a task's
+//      `requires_rank` floor. Behavioural (the composed gate) + structural (the
+//      permission predicate cannot even see requires_rank, and db.js still calls
+//      rankAllowsTask as its own gate at every claim site).
+//   B. THE PERMISSION PREDICATE IS CORRECT on its own terms — newcomer-only vs the
+//      general queue, and fail-closed for a builder holding no claim permission.
+//   C. RANK-BY-RANK PARITY: the new predicate admits exactly the set the old rank
+//      rule admitted. Two INDEPENDENT oracles, deliberately:
+//        • a hand-written literal table (written from ADR 0018/0034, not from any
+//          code in the repo), and
+//        • db.xenosClaimAllowed itself — the real incumbent function, which reads
+//          GENERAL_QUEUE_RANKS and knows nothing about catalog floors.
+//      The new side reads catalog.seedForRank. A check whose two sides both read
+//      catalog.floor would pass while proving nothing (the lesson tests/
+//      governance_parity.mjs writes down); neither oracle here does.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+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 LIFECYCLE = path.join(ROOT, 'modules', 'lifecycle');
+const eligibility = require(path.join(LIFECYCLE, 'claim-eligibility.js'));
+const db = require(path.join(LIFECYCLE, 'db.js'));
+const catalog = require(path.join(ROOT, 'modules', 'governance', 'catalog.js'));
+
+const { CLAIM_ANY, CLAIM_NEWCOMER, permissionAllowsClaim, claimEligibilityAllows } = eligibility;
+
+// The four live ranks (ADR 0018 + ADR 0034), and the newcomer_friendly values the
+// column can actually hold — it is nullable, so null/undefined must read falsey.
+const LIVE_RANKS = ['xenos', 'thetes', 'metic', 'archon'];
+const NF_VALUES = [true, false, null, undefined];
+
+// A builder's seeded permission set, as the compat seed grants it.
+const seedSet = (rank) => new Set(catalog.seedForRank(rank));
+
+// The composed claim gate, OLD and NEW, so parity is compared end to end rather
+// than one half at a time. Both call rankAllowsTask as a SEPARATE conjunct — that
+// shape is the thing under test.
+const oldGate = (rank, nf, requiresRank) =>
+  db.xenosClaimAllowed(rank, nf) && db.rankAllowsTask(rank, requiresRank);
+
+const newGate = (rank, nf, requiresRank) =>
+  claimEligibilityAllows({
+    heldPermissions: seedSet(rank),
+    newcomerFriendly: nf,
+    rankRuleAllows: db.xenosClaimAllowed(rank, nf),
+  }) && db.rankAllowsTask(rank, requiresRank);
+
+// ── the catalog anchor ───────────────────────────────────────────────────────
+
+test('the two claim keys exist in the catalog at the floors this gate assumes', () => {
+  const any = catalog.byKey(CLAIM_ANY);
+  const newcomer = catalog.byKey(CLAIM_NEWCOMER);
+  assert.ok(any, `${CLAIM_ANY} must be a real catalog permission`);
+  assert.ok(newcomer, `${CLAIM_NEWCOMER} must be a real catalog permission`);
+  assert.equal(any.floor, 'thetes', 'task.claim.any is the general queue — thetes and up');
+  assert.equal(newcomer.floor, 'xenos', 'task.claim.newcomer is held by every authenticated builder');
+  // Operational, not trust-boundary: a custom role may legitimately grant either.
+  assert.equal(any.system, false);
+  assert.equal(newcomer.system, false);
+});
+
+// ── B. the permission predicate on its own terms ─────────────────────────────
+
+test('a xenos (task.claim.newcomer only) may claim a newcomer_friendly task', () => {
+  const held = seedSet('xenos');
+  assert.ok(held.has(CLAIM_NEWCOMER));
+  assert.ok(!held.has(CLAIM_ANY), 'the xenos role must NOT hold the general-queue permission');
+  assert.equal(permissionAllowsClaim(held, true), true);
+});
+
+test('a xenos may NOT claim a general-queue task', () => {
+  const held = seedSet('xenos');
+  assert.equal(permissionAllowsClaim(held, false), false);
+  assert.equal(permissionAllowsClaim(held, null), false, 'a NULL newcomer_friendly is not "open"');
+  assert.equal(permissionAllowsClaim(held, undefined), false);
+});
+
+test('thetes and up (task.claim.any) may claim the general queue', () => {
+  for (const rank of ['thetes', 'metic', 'archon']) {
+    const held = seedSet(rank);
+    assert.ok(held.has(CLAIM_ANY), `${rank} must hold ${CLAIM_ANY}`);
+    assert.equal(permissionAllowsClaim(held, false), true, `${rank} claims the general queue`);
+    assert.equal(permissionAllowsClaim(held, true), true, `${rank} also claims newcomer rows`);
+  }
+});
+
+test('a builder holding NO claim permission is refused (fail-closed)', () => {
+  for (const nf of NF_VALUES) {
+    assert.equal(permissionAllowsClaim(new Set(), nf), false, 'empty permission set');
+    assert.equal(permissionAllowsClaim([], nf), false, 'empty array');
+    assert.equal(permissionAllowsClaim(null, nf), false, 'no set at all');
+    assert.equal(permissionAllowsClaim(['idea.triage', 'cost.log'], nf), false, 'unrelated grants');
+    assert.equal(permissionAllowsClaim(['task.claim.everything'], nf), false, 'an invented key grants nothing');
+  }
+});
+
+test('an array of keys is accepted as well as a Set (the resolver returns an array)', () => {
+  assert.equal(permissionAllowsClaim([CLAIM_ANY], false), true);
+  assert.equal(permissionAllowsClaim([CLAIM_NEWCOMER], true), true);
+  assert.equal(permissionAllowsClaim([CLAIM_NEWCOMER], false), false);
+});
+
+// ── A. the per-task requires_rank floor is a SEPARATE axis ───────────────────
+
+test('requires_rank still refuses a builder below it EVEN when they hold task.claim.any', () => {
+  // The load-bearing case. A thetes holds the general-queue permission outright,
+  // so the queue axis says yes — and the task's own floor must still say no.
+  const held = seedSet('thetes');
+  assert.ok(held.has(CLAIM_ANY));
+  assert.equal(permissionAllowsClaim(held, false), true, 'the queue axis admits them');
+  assert.equal(db.rankAllowsTask('thetes', 'metic'), false, 'the task floor does not');
+  assert.equal(newGate('thetes', false, 'metic'), false, 'the composed gate refuses');
+
+  // Same shape one rung up: a metic holds task.claim.any and is still below an
+  // archon-floored task.
+  assert.equal(permissionAllowsClaim(seedSet('metic'), false), true);
+  assert.equal(newGate('metic', false, 'archon'), false);
+
+  // ...and a newcomer_friendly flag does NOT open a floored task either: the two
+  // gates are AND-ed, so opening the door does not lower the floor.
+  assert.equal(permissionAllowsClaim(seedSet('xenos'), true), true);
+  assert.equal(newGate('xenos', true, 'metic'), false);
+});
+
+test('the permission predicate cannot see requires_rank at all (structural)', () => {
+  const src = fs.readFileSync(path.join(LIFECYCLE, 'claim-eligibility.js'), 'utf8')
+    .split('\n').filter((l) => !l.trim().startsWith('//')).join('\n');
+  for (const banned of ['requires_rank', 'rankAllowsTask', 'REQUIRES_RANK_TIER']) {
+    assert.ok(!src.includes(banned), `claim-eligibility.js must not reach into the task-floor axis ("${banned}")`);
+  }
+});
+
+test('every claim path in db.js still gates on requires_rank as its own check', () => {
+  const src = fs.readFileSync(path.join(LIFECYCLE, 'db.js'), 'utf8');
+  // claimTask, claimTasksBatch, validateClaimBatch — three call sites, three
+  // separate rankAllowsTask conjuncts. If a refactor ever folds the floor into the
+  // permission predicate, this count drops and the test reds.
+  const floorChecks = src.match(/rankAllowsTask\((builderRank|builderRank), (task|t)\.requires_rank\)/g) || [];
+  assert.equal(floorChecks.length, 3, `expected 3 requires_rank gates in the claim paths, found ${floorChecks.length}`);
+  const queueChecks = src.match(/claimEligibilityAllows\(\{/g) || [];
+  assert.equal(queueChecks.length, 3, `expected 3 permission-expressed queue gates, found ${queueChecks.length}`);
+});
+
+// ── the "authority could not be established" fallback ────────────────────────
+
+test('a null permission set falls back to the incumbent rank rule, never to allow', () => {
+  for (const rank of LIVE_RANKS) {
+    for (const nf of NF_VALUES) {
+      const rankRuleAllows = db.xenosClaimAllowed(rank, nf);
+      assert.equal(
+        claimEligibilityAllows({ heldPermissions: null, newcomerFriendly: nf, rankRuleAllows }),
+        rankRuleAllows,
+        `${rank}/${String(nf)}: the fallback must reproduce the rank rule exactly`,
+      );
+    }
+  }
+  // ...and it is a fallback to the RULE, not an open door.
+  assert.equal(claimEligibilityAllows({ heldPermissions: null, newcomerFriendly: false, rankRuleAllows: false }), false);
+  assert.equal(claimEligibilityAllows({ heldPermissions: undefined, newcomerFriendly: true, rankRuleAllows: false }), false);
+});
+
+test('a reserved/unwired rank keeps TODAY behaviour through the fallback (no silent narrowing)', () => {
+  // A rank outside the four seeded ones resolves to zero permissions (the
+  // deliberate divergence governance_002 documents), so the claim path sees NULL
+  // and falls back — which is what keeps this swap behaviour-identical rather than
+  // quietly locking such a builder out of the newcomer queue.
+  for (const rank of ['helot', 'doulos', 'olympian', null, undefined]) {
+    assert.deepEqual(catalog.seedForRank(rank), [], `${String(rank)} has no seeded role`);
+    for (const nf of NF_VALUES) {
+      const rankRuleAllows = db.xenosClaimAllowed(rank, nf);
+      assert.equal(
+        claimEligibilityAllows({ heldPermissions: null, newcomerFriendly: nf, rankRuleAllows }),
+        rankRuleAllows,
+        `${String(rank)}/${String(nf)}`,
+      );
+    }
+  }
+});
+
+// ── C. rank-by-rank parity, against two independent oracles ──────────────────
+
+test('PARITY vs a hand-written table — the new predicate admits exactly today\'s set', () => {
+  // Written from the rules, not from the code: the sandboxed entry rank reaches
+  // only rows opened to it; thetes and up reach everything (ADR 0018 / ADR 0034).
+  // [rank][newcomer_friendly] → may claim (ignoring the task floor, tested above).
+  const EXPECTED = {
+    xenos: { true: true, false: false },
+    thetes: { true: true, false: true },
+    metic: { true: true, false: true },
+    archon: { true: true, false: true },
+  };
+  for (const rank of LIVE_RANKS) {
+    for (const nf of NF_VALUES) {
+      const expected = EXPECTED[rank][nf === true ? 'true' : 'false'];
+      assert.equal(
+        permissionAllowsClaim(seedSet(rank), nf),
+        expected,
+        `${rank} / newcomer_friendly=${String(nf)} should be ${expected}`,
+      );
+    }
+  }
+});
+
+test('PARITY vs db.xenosClaimAllowed — the real incumbent gate, over every live rank', () => {
+  for (const rank of LIVE_RANKS) {
+    for (const nf of NF_VALUES) {
+      assert.equal(
+        permissionAllowsClaim(seedSet(rank), nf),
+        db.xenosClaimAllowed(rank, nf),
+        `${rank} / newcomer_friendly=${String(nf)} diverges from the rank rule`,
+      );
+    }
+  }
+});
+
+test('PARITY of the COMPOSED gate — rank x newcomer_friendly x requires_rank', () => {
+  const REQUIRES_RANK = ['xenos', 'thetes', 'metic', 'archon', null];
+  let checked = 0;
+  for (const rank of LIVE_RANKS) {
+    for (const nf of NF_VALUES) {
+      for (const rr of REQUIRES_RANK) {
+        assert.equal(
+          newGate(rank, nf, rr),
+          oldGate(rank, nf, rr),
+          `${rank} / nf=${String(nf)} / requires_rank=${String(rr)}: permission gate diverges from the rank gate`,
+        );
+        checked++;
+      }
+    }
+  }
+  assert.equal(checked, LIVE_RANKS.length * NF_VALUES.length * REQUIRES_RANK.length);
+});
+
+test('the abuse case stays blocked: a xenos cannot reach the general queue by any route', () => {
+  const held = seedSet('xenos');
+  for (const rr of ['xenos', 'thetes', 'metic', 'archon']) {
+    assert.equal(newGate('xenos', false, rr), false, `xenos must not claim a general-queue task (requires_rank=${rr})`);
+  }
+  // Not even by holding every OTHER permission the catalog defines — only
+  // task.claim.any opens the general queue.
+  const everythingElse = catalog.permissionKeys().filter((k) => k !== CLAIM_ANY);
+  assert.equal(permissionAllowsClaim(everythingElse, false), false);
+  // And the one permission they do hold is scoped to opened rows only.
+  assert.equal(permissionAllowsClaim(held, false), false);
+  assert.equal(permissionAllowsClaim(held, true), true);
+});