@bongos/core 1.23.21 → 1.24.1

package/tests/task_criteria_unlink_db.mjs

@@ -0,0 +1,123 @@
+// tests/task_criteria_unlink_db.mjs — what unlinking an OPEN task from a criterion
+// does to that criterion's close (task 1004984, gap 4). REAL DB: the close is one
+// UPDATE ... FROM candidate statement whose grouping, FILTER counts and sign-off
+// recency clause only Postgres evaluates.
+//
+// The scenario. One criterion gates two tasks: one SHIPPED, one still OPEN. A
+// current backend_signoff sits on the criterion (recorded after the shipped task
+// landed). While the open task is linked, the delivery guard holds the criterion
+// open. Then the open task's link is removed (removeTaskCriterion, the DELETE
+// route's write) and autoSatisfyShippedCriteria runs.
+//
+// The recorded outcome (task 1004984's ship notes): the criterion CLOSES, on the
+// sign-off it already had, attributed to the shipped task. The sign-off is current
+// by the reconciler's rule — no linked task shipped after it — so this is the
+// intended rule, not a close without a fresh sign-off. The goal does NOT achieve,
+// because the unlinked task is still an unfinished task of the goal. A second
+// criterion with the same links and NO sign-off stays open: unlinking alone never
+// closes a criterion.
+//
+// Real-DB integration test (self-skips without a reachable Postgres; in the
+// INTEGRATION set so the default DB-free lane never runs it).
+//
+// Run:  DATABASE_URL=... node tests/task_criteria_unlink_db.mjs
+
+import { createRequire } from 'node:module';
+import { strict as assert } from 'node:assert';
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`task_criteria_unlink_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const seams = require('../src/module-seams.js');
+if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../modules/economy/reward.js'));
+const db = require('../modules/lifecycle/db.js');
+const { autoSatisfyShippedCriteria } = require('../modules/lifecycle/done-when.js');
+
+const VER = 'ZZZ-CRIT-UNLINK', SIGNER = 90000411;
+const q = (sql, params) => pool.query(sql, params).then((r) => r.rows);
+
+async function cleanup() {
+  const ids = (await q(`SELECT id FROM tasks WHERE version_id=$1`, [VER]).catch(() => [])).map((r) => r.id);
+  const crits = (await q(`SELECT id FROM done_when_criteria WHERE version_id=$1`, [VER]).catch(() => [])).map((r) => r.id);
+  await q(`DELETE FROM lifecycle_criterion_uats WHERE criterion_id = ANY($1::bigint[])`, [crits]).catch(() => {});
+  await q(`DELETE FROM task_criteria WHERE task_id = ANY($1::bigint[]) OR criterion_id = ANY($2::bigint[])`, [ids, crits]).catch(() => {});
+  await q(`UPDATE done_when_criteria SET satisfied_by_task_id = NULL WHERE version_id=$1`, [VER]).catch(() => {});
+  await q(`DELETE FROM dependencies WHERE (from_kind='task' AND from_id = ANY($1::bigint[])) OR (to_kind='task' AND to_id = ANY($1::bigint[]))`, [ids]).catch(() => {});
+  await q(`DELETE FROM done_when_criteria WHERE version_id=$1`, [VER]).catch(() => {});
+  await q(`DELETE FROM tasks WHERE version_id=$1`, [VER]).catch(() => {});
+  await q(`DELETE FROM goal_members WHERE goal_id IN (SELECT id FROM goals WHERE version_id=$1)`, [VER]).catch(() => {});
+  await q(`DELETE FROM goals WHERE version_id=$1`, [VER]).catch(() => {});
+  await q(`DELETE FROM builders WHERE id=$1`, [SIGNER]).catch(() => {});
+  await q(`DELETE FROM versions WHERE id=$1`, [VER]).catch(() => {});
+}
+
+let pass = 0;
+const ok = (cond, msg) => { assert.ok(cond, msg); console.log(`  ok  ${msg}`); pass++; };
+const crit = async (id) => (await q(`SELECT satisfied, satisfied_by_task_id FROM done_when_criteria WHERE id=$1`, [id]))[0];
+const goalStatus = async (id) => (await q(`SELECT status FROM goals WHERE id=$1`, [id]))[0].status;
+
+try {
+  await cleanup();
+  await q(`INSERT INTO versions (id,name,status,track) VALUES ($1,'unlink','building','internal') ON CONFLICT (id) DO NOTHING`, [VER]);
+  await q(`INSERT INTO builders (id,github_id,github_login,display_name,rank) VALUES ($1,'unlink-s','unlink-signer','Unlink Signer','archon')`, [SIGNER]);
+
+  const goal = await db.createGoal({ versionId: VER, title: 'Unlink goal', createdBy: SIGNER });
+  const shipped = await db.createTask({ versionId: VER, goalId: goal.id, title: 'The shipped half', kind: 'feature', discipline: 'engineer', creditsReward: 10 });
+  const open = await db.createTask({ versionId: VER, goalId: goal.id, title: 'The open half', kind: 'feature', discipline: 'engineer', creditsReward: 10 });
+  await q(`UPDATE tasks SET status='shipped', shipped_at = now() - interval '1 hour' WHERE id=$1`, [shipped.id]);
+
+  // Two criteria, the same two links on each. Only the first carries a sign-off.
+  const [signed] = await q(
+    `INSERT INTO done_when_criteria (version_id, goal_id, criterion_id, criterion_md, sort_order)
+     VALUES ($1, $2, 'unlink-signed', 'Signed criterion', 1) RETURNING id`, [VER, goal.id]);
+  const [unsigned] = await q(
+    `INSERT INTO done_when_criteria (version_id, goal_id, criterion_id, criterion_md, sort_order)
+     VALUES ($1, $2, 'unlink-unsigned', 'Unsigned criterion', 2) RETURNING id`, [VER, goal.id]);
+  for (const c of [signed.id, unsigned.id]) {
+    await db.addTaskCriterion(shipped.id, c, 'manual');
+    await db.addTaskCriterion(open.id, c, 'manual');
+  }
+  // A current backend sign-off: created now, after the shipped task's shipped_at.
+  await q(
+    `INSERT INTO lifecycle_criterion_uats (criterion_id, kind, signed_off_by, live_basis, note)
+     VALUES ($1, 'backend_signoff', $2, 'attested', 'signed while the open task was linked')`,
+    [signed.id, SIGNER]);
+
+  // 1) While the open task is linked, the delivery guard holds BOTH criteria open.
+  for (const c of [signed.id, unsigned.id]) await autoSatisfyShippedCriteria(pool, { criterionId: c });
+  ok((await crit(signed.id)).satisfied === false, 'a linked open task holds the signed criterion open');
+  ok((await crit(unsigned.id)).satisfied === false, 'a linked open task holds the unsigned criterion open');
+
+  // 2) Unlink the open task from both (the DELETE route's write).
+  ok(await db.removeTaskCriterion(open.id, signed.id), 'the open task\'s link to the signed criterion is removed');
+  ok(await db.removeTaskCriterion(open.id, unsigned.id), 'the open task\'s link to the unsigned criterion is removed');
+  ok((await db.removeTaskCriterion(open.id, signed.id)) === false, 'a second unlink removes nothing and says so');
+
+  // 3) Run the reconciler's close, scoped per criterion so no other test's data is swept.
+  const outSigned = await autoSatisfyShippedCriteria(pool, { criterionId: signed.id });
+  const outUnsigned = await autoSatisfyShippedCriteria(pool, { criterionId: unsigned.id });
+
+  const s = await crit(signed.id);
+  ok(s.satisfied === true, 'OUTCOME: the signed criterion closes once only the shipped task is linked');
+  ok(Number(s.satisfied_by_task_id) === Number(shipped.id), 'the close is attributed to the shipped task');
+  ok(outSigned.criteria.length === 1, 'the call reports exactly that one criterion closed');
+
+  ok((await crit(unsigned.id)).satisfied === false, 'with no sign-off, unlinking alone never closes a criterion');
+  ok(outUnsigned.criteria.length === 0, 'and the call reports nothing closed');
+
+  ok((await goalStatus(goal.id)) === 'open', 'the goal stays open — the unlinked task is still unfinished work of the goal');
+  ok(outSigned.goals.length === 0, 'no goal was achieved by the close');
+
+  console.log(`\ntask_criteria_unlink_db.mjs: ${pass} passed`);
+} finally {
+  await cleanup();
+  await pool.end();
+}

package/tests/task_needs.mjs

@@ -0,0 +1,233 @@
+// tests/task_needs.mjs — a task says what it needs; each person's lists show only
+// what they can do (task 1004950, ADR 0395). DB-free: the real feed
+// (listClaimableTasks), the real claim gate (taskNeedsFailures) and the real
+// capability read (resolveCapabilities) run against a stand-in pool that answers
+// each query from fixtures — and the feed's stand-in applies the predicate the
+// SQL names (`needs <@ capabilities`) to the parameter the code actually bound,
+// so a feed that bound the wrong capabilities, or none, fails here.
+// tests/task_needs_db.mjs proves the same rows against real Postgres.
+//
+// Run:  node tests/task_needs.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+
+const require = createRequire(import.meta.url);
+const api = require('../src/module-api.js');
+const seams = require('../src/module-seams.js');
+const { setCapabilityGrants } = require('../src/bongos/task-needs.js');
+const needs = { ...api.taskNeeds, setCapabilityGrants };
+const gate = require('../modules/lifecycle/task-needs-gate.js');
+const db = require('../modules/lifecycle/db.js');
+
+let passed = 0, failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ---- fixtures: four people and four tasks --------------------------------
+const OWNER = 7, GRANTED = 8, PLAIN = 9, FOUNDER = 3;
+const GRANTS = { [OWNER]: [], [GRANTED]: ['server'], [PLAIN]: [], [FOUNDER]: [] };
+const TASKS = [
+  { id: 101, needs: [] },
+  { id: 102, needs: ['owner'] },
+  { id: 103, needs: ['server'] },
+  { id: 104, needs: ['owner', 'server'] },
+];
+const seatHolder = { id: OWNER };
+const governmentPort = { positionsFor: async (id) => ({ held: String(id) === String(seatHolder.id) ? [{ kind: 'owner' }] : [] }) };
+
+const subset = (a, b) => a.every((x) => b.includes(x));
+let lastFeed = null;
+const realQuery = api.pool.query;
+api.pool.query = async (sql, params = []) => {
+  if (/SELECT capability_grants FROM builders/.test(sql)) return { rows: [{ capability_grants: GRANTS[params[0]] || [] }] };
+  if (/FROM builders WHERE system_role IS NULL ORDER BY id/.test(sql)) return { rows: [{ id: String(FOUNDER) }] };
+  if (/SELECT ct\.\*, sf\.fits_session_modes/.test(sql)) { // the session optimizer
+    const m = sql.match(/COALESCE\(ct\.needs, '\{\}'::text\[\]\) <@ \$(\d+)::text\[\]/);
+    lastFeed = { sql, params, capsParam: m ? params[Number(m[1]) - 1] : undefined };
+    const caps = m ? lastFeed.capsParam : ['owner', 'server'];
+    return { rows: TASKS.filter((r) => subset(r.needs, caps)).map((r) => ({ ...r, touches: [`f${r.id}`], est_minutes: 10 })) };
+  }
+  if (/FROM \(\s*SELECT t\.\*, pms_calibrated_minutes/.test(sql)) {
+    const m = sql.match(/COALESCE\(v\.needs, '\{\}'::text\[\]\) <@ \$(\d+)::text\[\]/);
+    lastFeed = { sql, params, capsParam: m ? params[Number(m[1]) - 1] : undefined };
+    if (!m) return { rows: TASKS.map((r) => ({ ...r })) }; // no clause bound → nothing narrows
+    const caps = lastFeed.capsParam;
+    const oneNeed = sql.match(/v\.needs @> ARRAY\[\$(\d+)\]::text\[\]/);
+    const none = /cardinality\(v\.needs\) = 0/.test(sql);
+    return {
+      rows: TASKS
+        .filter((r) => subset(r.needs, caps))
+        .filter((r) => (none ? r.needs.length === 0 : true))
+        .filter((r) => (oneNeed ? r.needs.includes(params[Number(oneNeed[1]) - 1]) : true))
+        .map((r) => ({ ...r })),
+    };
+  }
+  throw new Error(`unexpected query: ${sql.slice(0, 80)}`);
+};
+if (seams.hasProvider && seams.hasProvider('government')) throw new Error('test expects no government provider');
+seams.registerProvider('government', governmentPort);
+
+const feedIds = async (builderId, opts = {}) =>
+  (await db.listClaimableTasks({ builderId, ...opts })).map((r) => Number(r.id)).sort();
+
+// ---- the vocabulary --------------------------------------------------------
+await t('normalizeNeeds accepts arrays, comma lists and nothing; refuses unknown words', () => {
+  assert.deepEqual(needs.normalizeNeeds(['server', 'owner', 'server']).needs, ['owner', 'server']);
+  assert.deepEqual(needs.normalizeNeeds('server, owner').needs, ['owner', 'server']);
+  assert.deepEqual(needs.normalizeNeeds(null).needs, []);
+  assert.deepEqual(needs.normalizeNeeds([]).needs, []);
+  assert.deepEqual(needs.normalizeNeeds(['dns']), { ok: false, bad: ['dns'] });
+  assert.equal(needs.normalizeNeeds(5).ok, false);
+});
+
+await t('the migration CHECK and the code list name the same needs', () => {
+  const mig = readFileSync(new URL('../migrations/core_285_task_needs.sql', import.meta.url), 'utf8');
+  const tasksCheck = mig.match(/needs <@ ARRAY\[([^\]]+)\]/)[1].match(/'([a-z]+)'/g).map((s) => s.slice(1, -1));
+  assert.deepEqual(tasksCheck, [...needs.TASK_NEEDS]);
+  const grantCheck = mig.match(/capability_grants <@ ARRAY\[([^\]]+)\]/)[1].match(/'([a-z]+)'/g).map((s) => s.slice(1, -1));
+  assert.deepEqual(grantCheck, [...needs.GRANTABLE_CAPABILITIES]);
+});
+
+await t('only server refuses a claim; owner never does', () => {
+  assert.deepEqual(needs.claimRefusalNeeds(['owner'], []), []);
+  assert.deepEqual(needs.claimRefusalNeeds(['server'], []), ['server']);
+  assert.deepEqual(needs.claimRefusalNeeds(['owner', 'server'], ['owner']), ['server']);
+  assert.deepEqual(needs.claimRefusalNeeds(['server'], ['server']), []);
+});
+
+// ---- capabilities are read, never asserted ---------------------------------
+await t('the owner seat gives owner; a grant gives server; a plain builder has neither', async () => {
+  assert.deepEqual(await needs.resolveCapabilities(OWNER), ['owner']);
+  assert.deepEqual(await needs.resolveCapabilities(GRANTED), ['server']);
+  assert.deepEqual(await needs.resolveCapabilities(PLAIN), []);
+});
+
+await t('with no seat held, the founding builder is the owner (the UAT sign-off fallback)', async () => {
+  assert.deepEqual(await needs.resolveCapabilities(FOUNDER, { government: null }), ['owner']);
+  assert.deepEqual(await needs.resolveCapabilities(OWNER, { government: null }), []);
+  const broken = { positionsFor: async () => { throw new Error('down'); } };
+  assert.deepEqual(await needs.resolveCapabilities(FOUNDER, { government: broken }), ['owner'], 'a failed seat read falls back, never widens');
+});
+
+// ---- the feed --------------------------------------------------------------
+await t('a builder without server access sees no server task, and no owner task', async () => {
+  assert.deepEqual(await feedIds(PLAIN), [101]);
+  assert.deepEqual(lastFeed.capsParam, [], 'the capabilities bound into the query are the viewer\'s');
+});
+
+await t('the owner sees owner tasks in their own list, but not server work', async () => {
+  assert.deepEqual(await feedIds(OWNER), [101, 102]);
+});
+
+await t('a builder granted server access sees server tasks', async () => {
+  assert.deepEqual(await feedIds(GRANTED), [101, 103]);
+});
+
+await t('the owner holding a server grant sees everything', async () => {
+  GRANTS[OWNER] = ['server'];
+  try { assert.deepEqual(await feedIds(OWNER), [101, 102, 103, 104]); }
+  finally { GRANTS[OWNER] = []; }
+});
+
+await t('the autonomous runner never holds owner, whoever it runs as', async () => {
+  assert.deepEqual(await feedIds(OWNER, { fit: 'autonomous' }), [101]);
+  assert.deepEqual(lastFeed.capsParam, []);
+});
+
+await t('?needs=owner is the owner\'s "waiting on you" queue', async () => {
+  assert.deepEqual(await feedIds(OWNER, { needs: 'owner' }), [102]);
+  assert.deepEqual(await feedIds(PLAIN, { needs: 'owner' }), [], 'it never widens what a viewer is shown');
+  assert.deepEqual(await feedIds(OWNER, { needs: 'none' }), [101]);
+});
+
+await t('the board filter on GET /tasks narrows by need without the capability rule', () => {
+  const params = [];
+  assert.equal(gate.needsFilterWhere('server', '', params), 'needs @> ARRAY[$1]::text[]');
+  assert.deepEqual(params, ['server']);
+  assert.equal(gate.needsFilterWhere('none', '', []), 'cardinality(needs) = 0');
+  assert.equal(gate.needsFilterWhere(undefined, '', []), null);
+});
+
+// ---- the session optimizer (the other recommend list) -----------------------
+const optimizer = require('../src/bongos/optimizer.js');
+const planIds = async (builderId, mode) =>
+  [...(await optimizer.optimizeSession({ builderId, mode, timeBudgetMin: 600, maxParallel: 10 })).recommended.map((r) => Number(r.id))].sort();
+
+await t('the session plan applies the same rule, per capability', async () => {
+  assert.deepEqual(await planIds(PLAIN, 'active'), [101]);
+  assert.deepEqual(await planIds(OWNER, 'active'), [101, 102]);
+  assert.deepEqual(await planIds(GRANTED, 'active'), [101, 103]);
+});
+
+await t('an autonomous session plan never holds owner, even for the owner', async () => {
+  assert.deepEqual(await planIds(OWNER, 'autonomous'), [101]);
+  assert.deepEqual(lastFeed.capsParam, []);
+});
+
+// ---- the claim gate --------------------------------------------------------
+const fakeClient = {
+  query: async (sql, params) => {
+    assert.match(sql, /SELECT id, needs FROM tasks WHERE id = ANY/);
+    return { rows: TASKS.filter((r) => params[0].includes(r.id) && r.needs.length > 0) };
+  },
+};
+
+await t('a server task refuses a claimer without the grant, in plain words', async () => {
+  const f = await gate.taskNeedsFailures({ client: fakeClient, tasks: [{ id: 103 }], builderId: PLAIN });
+  assert.equal(f.length, 1);
+  assert.equal(f[0].refusal.code, 'NEEDS_SERVER_ACCESS');
+  assert.match(f[0].refusal.message, /server access/);
+  assert.doesNotMatch(f[0].refusal.message, /capabilit|grant|NEEDS_/, 'no machinery in the sentence a person reads');
+});
+
+await t('the same server task is claimable with the grant', async () => {
+  assert.deepEqual(await gate.taskNeedsFailures({ client: fakeClient, tasks: [{ id: 103 }, { id: 104 }], builderId: GRANTED }), []);
+});
+
+await t('owner work is claimable — by the owner and, if they reach it, by anyone', async () => {
+  assert.deepEqual(await gate.taskNeedsFailures({ client: fakeClient, tasks: [{ id: 102 }], builderId: OWNER }), []);
+  assert.deepEqual(await gate.taskNeedsFailures({ client: fakeClient, tasks: [{ id: 102 }], builderId: PLAIN }), []);
+});
+
+await t('a task needing owner AND server refuses the owner without a grant (server is the refusal)', async () => {
+  const f = await gate.taskNeedsFailures({ client: fakeClient, tasks: [{ id: 104 }], builderId: OWNER });
+  assert.deepEqual(f.map((x) => x.refusal.needs), [['server']]);
+});
+
+await t('all three claim surfaces call the gate', () => {
+  const src = readFileSync(new URL('../modules/lifecycle/db-claims.js', import.meta.url), 'utf8');
+  assert.equal((src.match(/await taskNeedsFailures\(/g) || []).length, 3);
+});
+
+// ---- granting server access ------------------------------------------------
+await t('the module doorway publishes the reads, never the grant write', () => {
+  assert.equal(typeof api.taskNeeds.resolveCapabilities, 'function');
+  assert.equal(api.taskNeeds.setCapabilityGrants, undefined, 'a module must not be able to grant server access');
+});
+
+await t('only the owner seat can grant server access — checked at the write itself', async () => {
+  const writes = [];
+  const grantPool = {
+    query: async (sql, params) => {
+      if (/SELECT capability_grants FROM builders/.test(sql)) return { rows: [{ capability_grants: [] }] };
+      if (/SELECT id, system_role FROM builders/.test(sql)) return { rows: [{ id: params[0], system_role: null }] };
+      if (/UPDATE builders SET capability_grants/.test(sql)) { writes.push(params); return { rows: [{ id: params[0], capability_grants: params[1] }] }; }
+      throw new Error(`unexpected: ${sql.slice(0, 60)}`);
+    },
+  };
+  const deps = { pool: grantPool, government: governmentPort, getFoundingBuilder: async () => ({ id: FOUNDER }) };
+  let refused = null;
+  try { await needs.setCapabilityGrants({ actorBuilderId: PLAIN, builderId: PLAIN, grants: ['server'] }, deps); } catch (e) { refused = e; }
+  assert.equal(refused && refused.code, 'NOT_PROJECT_OWNER');
+  assert.equal(writes.length, 0, 'nothing written for a non-owner');
+  const row = await needs.setCapabilityGrants({ actorBuilderId: OWNER, builderId: PLAIN, grants: ['server', 'owner'] }, deps);
+  assert.deepEqual(row.capability_grants, ['server'], 'owner is never granted by hand');
+});
+
+api.pool.query = realQuery;
+console.log(`\ntask_needs (task 1004950): ${passed} passed, ${failed} failed`);
+if (failed) process.exitCode = 1;

package/tests/task_needs_db.mjs

@@ -0,0 +1,110 @@
+// tests/task_needs_db.mjs — task 1004950 (ADR 0395), real DB.
+//
+// What a task needs, against real Postgres: core_285's columns and CHECKs, the
+// real claimable feed and the real claim gate on all three surfaces, each driven
+// with and without each capability. tests/task_needs.mjs covers the same rules
+// DB-free; this is the proof the SQL says what the stand-in assumed.
+// Real-DB integration test (self-skips without a reachable Postgres; in the
+// INTEGRATION set so the default DB-free lane never runs it).
+//
+// Run:  DATABASE_URL=... node tests/task_needs_db.mjs
+
+import { createRequire } from 'node:module';
+import { strict as assert } from 'node:assert';
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`task_needs_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const seams = require('../src/module-seams.js');
+if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../modules/economy/reward.js'));
+const db = require('../modules/lifecycle/db.js');
+
+const VER = 'ZZZ-TN';
+const OWNER = 90000901, GRANTED = 90000902, PLAIN = 90000903;
+const T_NONE = 90000911, T_OWNER = 90000912, T_SERVER = 90000913;
+const BUILDERS = [OWNER, GRANTED, PLAIN];
+const TASKS = [T_NONE, T_OWNER, T_SERVER];
+// The owner seat, as the government port answers it — only OWNER holds it here.
+if (!seams.hasProvider('government')) {
+  seams.registerProvider('government', { positionsFor: async (id) => ({ held: Number(id) === OWNER ? [{ kind: 'owner' }] : [] }) });
+}
+const q = (sql, params) => pool.query(sql, params).then((r) => r.rows);
+
+async function cleanup() {
+  await q(`DELETE FROM credit_log WHERE builder_id = ANY($1::bigint[]) OR task_id = ANY($2::bigint[])`, [BUILDERS, TASKS]).catch(() => {});
+  await q(`DELETE FROM claims WHERE task_id = ANY($1::bigint[])`, [TASKS]).catch(() => {});
+  await q(`DELETE FROM tasks WHERE id = ANY($1::bigint[])`, [TASKS]).catch(() => {});
+  await q(`DELETE FROM builders WHERE id = ANY($1::bigint[])`, [BUILDERS]).catch(() => {});
+  await q(`DELETE FROM versions WHERE id=$1`, [VER]).catch(() => {});
+}
+
+let pass = 0;
+const ok = (cond, msg) => { assert.ok(cond, msg); console.log(`  ok  ${msg}`); pass++; };
+const ours = (rows) => rows.map((r) => Number(r.id)).filter((id) => TASKS.includes(id)).sort();
+
+try {
+  await cleanup();
+  await q(`INSERT INTO versions (id,name,status,track) VALUES ($1,'tn','building','internal') ON CONFLICT (id) DO NOTHING`, [VER]);
+  for (const [id, grants] of [[OWNER, '{}'], [GRANTED, '{server}'], [PLAIN, '{}']]) {
+    await q(`INSERT INTO builders (id,github_id,github_login,display_name,rank,capability_grants) VALUES ($1,$2,$3,$3,'metic',$4::text[])`,
+      [id, `tn-${id}`, `tn-${id}`, grants]);
+  }
+  for (const [id, needs] of [[T_NONE, '{}'], [T_OWNER, '{owner}'], [T_SERVER, '{server}']]) {
+    await q(`INSERT INTO tasks (id,version_id,title,status,credits_reward,kind,discipline,needs) VALUES ($1,$2,$3,'ready',10,'feature','engineer',$4::text[])`,
+      [id, VER, `tn ${id}`, needs]);
+  }
+
+  // The columns refuse a need nobody knows.
+  let bad = null;
+  try { await q(`UPDATE tasks SET needs='{dns}' WHERE id=$1`, [T_NONE]); } catch (e) { bad = e; }
+  ok(bad && bad.code === '23514', 'tasks.needs refuses an unknown need (CHECK)');
+  bad = null;
+  try { await q(`UPDATE builders SET capability_grants='{owner}' WHERE id=$1`, [PLAIN]); } catch (e) { bad = e; }
+  ok(bad && bad.code === '23514', 'owner can never be granted by hand — it is the seat');
+  ok((await q(`SELECT needs FROM claimable_tasks WHERE id=$1`, [T_SERVER]))[0].needs.includes('server'),
+    'the claimable_tasks view carries needs (core_285 rebuilt it)');
+
+  // The feed.
+  ok(JSON.stringify(ours(await db.listClaimableTasks({ builderId: PLAIN }))) === JSON.stringify([T_NONE]),
+    'without server access or the seat: only the task that needs nothing');
+  ok(JSON.stringify(ours(await db.listClaimableTasks({ builderId: OWNER }))) === JSON.stringify([T_NONE, T_OWNER]),
+    'the owner sees owner work in their own list');
+  ok(JSON.stringify(ours(await db.listClaimableTasks({ builderId: GRANTED }))) === JSON.stringify([T_NONE, T_SERVER]),
+    'server access shows server work');
+  ok(JSON.stringify(ours(await db.listClaimableTasks({ builderId: OWNER, needs: 'owner' }))) === JSON.stringify([T_OWNER]),
+    '?needs=owner is the owner\'s waiting-on-you queue');
+  ok(ours(await db.listTasks({ versionId: VER })).length === 3, 'every task stays readable on the board');
+  ok(JSON.stringify(ours(await db.listTasks({ versionId: VER, needs: 'server' }))) === JSON.stringify([T_SERVER]),
+    'the board filters by need');
+
+  // The claim gate, three surfaces.
+  let threw = null;
+  try { await db.claimTask({ taskId: String(T_SERVER), builderId: String(PLAIN), worktreeName: 'tn-plain' }); } catch (e) { threw = e; }
+  ok(threw && threw.code === 'NEEDS_SERVER_ACCESS' && /server access/.test(threw.message), 'claimTask refuses server work without the grant, in plain words');
+  const dry = await db.validateClaimBatch({ taskIds: [T_SERVER], builderId: String(PLAIN) });
+  ok(JSON.stringify(dry).includes('NEEDS_SERVER_ACCESS'), 'the dry run greys it out too');
+  let batchThrew = null;
+  try { await db.claimTasksBatch({ taskIds: [T_SERVER], builderId: String(PLAIN), worktreePrefix: 'tn-batch' }); } catch (e) { batchThrew = e; }
+  ok((batchThrew && batchThrew.failures || []).some((f) => Number(f.task_id) === T_SERVER && f.reason === 'NEEDS_SERVER_ACCESS'),
+    'the batch path refuses it the same way');
+  const claim = await db.claimTask({ taskId: String(T_SERVER), builderId: String(GRANTED), worktreeName: 'tn-granted' });
+  ok(claim && Number(claim.task_id) === T_SERVER, 'with the grant, the claim succeeds');
+  const ownerClaim = await db.claimTask({ taskId: String(T_OWNER), builderId: String(OWNER), worktreeName: 'tn-owner' });
+  ok(ownerClaim && Number(ownerClaim.task_id) === T_OWNER, 'owner work is claimable by the owner');
+
+  console.log(`\ntask_needs_db (task 1004950): ${pass} passed, 0 failed`);
+} catch (e) {
+  console.error('task_needs_db.mjs FAILED:', e.stack || e.message);
+  process.exitCode = 1;
+} finally {
+  await cleanup();
+  await pool.end();
+}