@bongos/core 1.23.22 → 1.24.1

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();
+}