@bongos/core 1.23.22 → 1.24.1

package/tests/payout_approvals.mjs

@@ -0,0 +1,253 @@
+// tests/payout_approvals.mjs — the payout approval step (task 1004913, ADR 0385 D4).
+// DB-free: the pure rules, then the real router over real HTTP with a fake store.
+// Pins: a signature needs the person's own web session (never a CLI token, never a
+// machine principal); a narrowing can never widen; one approval per request, no
+// batch; a run pays only after its pause window, within its caps, unheld and as
+// noticed; the permission gate is payout.approve on every route.
+// Run:  node tests/payout_approvals.mjs
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import http from 'node:http';
+const require = createRequire(import.meta.url);
+const express = require('express');
+const lib = require('../src/bongos/payout-approvals');
+const build = require('../src/bongos/routes/payout-approvals');
+
+// The N10 payout gates, standing in as "everyone may be paid": this file tests
+// the approval step; tests/payout_gates.mjs tests the gates and their wiring.
+const passGates = {
+  gateOwedPay: async () => ({ ok: true, pay_to: 'self', needs_guardian_cosign: false }),
+  gateRecipient: async () => ({ ok: true, pay_to: 'self', needs_guardian_cosign: false }),
+  hasCosign: async () => true,
+  gateOwedPayMany: async (m) => new Map([...m.keys()].map((k) => [k, { ok: true, pay_to: 'self', needs_guardian_cosign: false }])),
+  cosignedInRun: async () => new Set(),
+};
+
+let n = 0;
+const ok = (name) => { n++; console.log(`ok - ${name}`); };
+
+const TERMS = {
+  caps: { per_payout_cents: 50_000, per_run_cents: 200_000, per_month_cents: 500_000 },
+  currency: 'USD',
+  formula: { kind: 'task_pay_terms' },
+  schedule: 'weekly',
+  pause_hours: 48,
+};
+
+// ── 1. pure rules ──────────────────────────────────────────────────────────
+{
+  const v = lib.validateRuleTerms(TERMS);
+  assert.deepEqual(v.terms, TERMS); ok('a complete rule validates to exactly what was sent');
+  assert.ok(lib.validateRuleTerms({ ...TERMS, extra: 1 }).errors); ok('an unknown term is refused, not dropped');
+  assert.ok(lib.validateRuleTerms({ ...TERMS, caps: { per_payout_cents: 1.5, per_run_cents: 10 } }).errors); ok('fractional cents refused');
+  assert.ok(lib.validateRuleTerms({ ...TERMS, caps: { per_payout_cents: 300, per_run_cents: 200 } }).errors); ok('per-payout above per-run refused');
+  assert.ok(lib.validateRuleTerms({ ...TERMS, pause_hours: 0 }).errors); ok('a rule with no pause window is refused');
+  assert.ok(lib.validateRuleTerms({ ...TERMS, formula: { kind: 'credit_share' } }).errors); ok('a credit-share rule must name its credit row kinds (ADR 0387 D5)');
+  assert.ok(lib.validateRuleTerms({ ...TERMS, formula: { kind: 'credit_share', credit_row_kinds: ['session.token_reward'] } }).terms); ok('a credit-share rule naming its rows validates');
+
+  const tighter = { ...TERMS, caps: { per_payout_cents: 40_000, per_run_cents: 100_000, per_month_cents: 400_000 }, pause_hours: 72 };
+  assert.deepEqual(lib.wideningReasons(TERMS, tighter), []); ok('lower caps and a longer pause are a narrowing');
+  assert.ok(lib.wideningReasons(TERMS, { ...TERMS, caps: { ...TERMS.caps, per_run_cents: 300_000 } }).length); ok('a higher cap widens');
+  const { per_month_cents: _drop, ...noMonth } = TERMS.caps;
+  assert.ok(lib.wideningReasons(TERMS, { ...TERMS, caps: noMonth }).length); ok('removing a cap widens');
+  assert.ok(lib.wideningReasons(TERMS, { ...TERMS, pause_hours: 24 }).length); ok('a shorter pause widens');
+  assert.ok(lib.wideningReasons(TERMS, { ...TERMS, schedule: 'on_ship' }).length); ok('a different schedule is not a narrowing');
+  assert.ok(lib.wideningReasons(TERMS, { ...TERMS, formula: { kind: 'fixed_per_task', amount_cents: 1 } }).length); ok('a different formula is not a narrowing');
+
+  const web = { builder: { id: '7', rank: 'archon', system_role: null }, gdsSession: { source: 'web', session_id: '91' } };
+  assert.equal(lib.personalSession(web).ok, true); ok('a person on the website is personal');
+  assert.equal(lib.personalSession({ ...web, gdsSession: { source: 'cli', session_id: '91' } }).reason, 'not_a_web_session'); ok('a CLI (AI) session is not personal');
+  assert.equal(lib.personalSession({ ...web, gdsSession: { source: null, session_id: '91' } }).reason, 'not_a_web_session'); ok('a legacy sourceless session is not personal');
+  assert.equal(lib.personalSession({ ...web, builder: { ...web.builder, system_role: 'bfg' } }).reason, 'machine_principal'); ok('a machine principal is never personal');
+}
+
+// ── 2. judging a run ───────────────────────────────────────────────────────
+{
+  const at = (h) => new Date(Date.UTC(2026, 9, 10) + h * 3600_000).toISOString();
+  const signed = { id: '1', kind: 'rule_signed', terms: TERMS, actor_id: '7', created_at: at(0) };
+  const notice = (id, key, payouts, h) => ({ id, kind: 'run_noticed', rule_id: '1', run_key: key, amount_cents: payouts.reduce((s, p) => s + p.amount_cents, 0), currency: 'USD', terms: { payouts }, created_at: at(h) });
+  const P = [{ recipient_id: '8', amount_cents: 30_000 }, { recipient_id: '9', amount_cents: 20_000 }];
+  const events = [signed, notice('2', 'w1', P, 1)];
+  const rule = lib.foldRule(events);
+  const judge = (extra = {}) => lib.judgeRun({ rule, ruleEvents: events, runKey: 'w1', payouts: P, now: new Date(at(60)), ...extra });
+
+  assert.equal(judge().ok, true); ok('a noticed run inside its caps pays after the pause');
+  assert.equal(judge({ now: new Date(at(10)) }).reason, 'in_pause_window'); ok('it does not pay inside the pause window');
+  assert.equal(judge({ runKey: 'w2' }).reason, 'run_not_noticed'); ok('an unnoticed run never pays');
+  assert.equal(judge({ payouts: [{ recipient_id: '8', amount_cents: 50_000 }] }).reason, 'run_differs_from_notice'); ok('a run that differs from its notice does not pay');
+  assert.equal(judge({ payouts: [...P].reverse() }).ok, true); ok('order of payouts does not matter');
+  assert.equal(lib.judgeRun({ rule, ruleEvents: [...events, { id: '3', kind: 'run_held', rule_id: '1', run_key: 'w1', created_at: at(2) }], runKey: 'w1', payouts: P, now: new Date(at(60)) }).reason, 'run_held'); ok('a held run never pays');
+  const revokedEvents = [...events, { id: '3', kind: 'rule_revoked', rule_id: '1', actor_id: '7', created_at: at(2) }];
+  assert.equal(lib.judgeRun({ rule: lib.foldRule(revokedEvents), ruleEvents: revokedEvents, runKey: 'w1', payouts: P, now: new Date(at(60)) }).reason, 'rule_revoked'); ok('a revoked rule pays nothing, even a run noticed before');
+  const narrowed = [...events, { id: '3', kind: 'rule_narrowed', rule_id: '1', terms: { ...TERMS, caps: { ...TERMS.caps, per_payout_cents: 25_000 } }, created_at: at(2) }];
+  assert.equal(lib.judgeRun({ rule: lib.foldRule(narrowed), ruleEvents: narrowed, runKey: 'w1', payouts: P, now: new Date(at(60)) }).reason, 'over_per_payout_cap'); ok('a narrowing binds runs already noticed');
+  const big = [{ recipient_id: '8', amount_cents: 50_000 }, { recipient_id: '9', amount_cents: 50_000 }, { recipient_id: '10', amount_cents: 50_000 }];
+  const month = [signed, notice('2', 'a', big, 1), notice('3', 'b', big, 2), notice('4', 'c', big, 3), notice('5', 'd', big, 4)];
+  const mr = lib.foldRule(month);
+  assert.equal(lib.judgeRun({ rule: mr, ruleEvents: month, runKey: 'c', payouts: big, now: new Date(at(200)) }).ok, true); ok('runs within the month cap pay');
+  assert.equal(lib.judgeRun({ rule: mr, ruleEvents: month, runKey: 'd', payouts: big, now: new Date(at(200)) }).reason, 'over_per_month_cap'); ok('the run that crosses the month cap does not');
+}
+
+// ── 3. the router over real HTTP ───────────────────────────────────────────
+const rows = [];
+let nextId = 1;
+const store = {
+  ...lib,
+  insertEvent: async (e) => {
+    const row = { id: String(nextId++), kind: e.kind, rule_id: e.rule_id ? String(e.rule_id) : null, run_key: e.run_key ?? null, actor_id: String(e.actor.id), session_source: e.actor.session_source, session_id: e.actor.session_id, recipient_id: e.recipient_id ?? null, amount_cents: e.amount_cents ?? null, currency: e.currency ?? null, terms: e.terms || {}, note: e.note ?? null, created_at: new Date().toISOString() };
+    rows.push(row);
+    return row;
+  },
+  readRule: async (id) => { const events = rows.filter((r) => r.id === String(id) || r.rule_id === String(id)); return { rule: lib.foldRule(events), events }; },
+  listRules: async () => [],
+  listLog: async () => [...rows].reverse(),
+};
+let who = { builder: { id: '7', rank: 'archon', system_role: null }, gdsSession: { source: 'web', session_id: '91' } };
+const gated = [];
+const app = express();
+app.use(express.json());
+app.use((req, res, next) => { res.fail = (code, { status = 400, message } = {}) => res.status(status).json({ error: code, message }); next(); });
+app.use((req, res, next) => { req.builder = who.builder; req.gdsSession = who.gdsSession; next(); });
+app.use('/', build({ store, gates: passGates, requireBuilder: (q, r, nx) => nx(), requirePermission: (...p) => { gated.push(p.join(',')); return (q, r, nx) => nx(); } }));
+const server = http.createServer(app).listen(0);
+const port = server.address().port;
+const call = (method, path, body) => new Promise((resolve) => {
+  const r = http.request({ port, path, method, headers: { 'content-type': 'application/json' } }, (res) => {
+    let d = ''; res.on('data', (c) => (d += c)); res.on('end', () => { let b = null; try { b = JSON.parse(d); } catch { /* not json */ } resolve({ status: res.statusCode, body: b }); });
+  });
+  if (body) r.write(JSON.stringify(body));
+  r.end();
+});
+
+try {
+  assert.ok(gated.length >= 9 && gated.every((g) => g === 'payout.approve')); ok('every route gates on payout.approve');
+
+  let r = await call('POST', '/payouts/rules', { terms: TERMS });
+  assert.equal(r.status, 201); assert.equal(r.body.approval.session_source, 'web'); ok('a person signs a rule from the website');
+  const ruleId = r.body.approval.id;
+
+  who = { ...who, gdsSession: { source: 'cli', session_id: '92' } };
+  for (const [m, p, b] of [['POST', '/payouts/rules', { terms: TERMS }], ['POST', `/payouts/rules/${ruleId}/narrow`, { terms: TERMS }], ['POST', `/payouts/rules/${ruleId}/revoke`, {}], ['POST', '/payouts/approve', { recipient_id: 8, amount_cents: 100, currency: 'USD' }], ['POST', '/payouts/grants', { recipient_id: 8, terms: { title: 'Grant', summary: 'one grant' } }], ['POST', '/payouts/contracts', { recipient_id: 8, terms: { title: 'Contract', summary: 'one contract' } }]]) {
+    const before = rows.length;
+    r = await call(m, p, b);
+    assert.equal(r.status, 403, p); assert.equal(r.body.error, 'personal_approval_required'); assert.equal(rows.length, before);
+  }
+  ok('an AI (CLI) session can sign nothing, and nothing is written');
+
+  r = await call('POST', `/payouts/rules/${ruleId}/runs`, { run_key: 'w1', payouts: [{ recipient_id: 8, amount_cents: 30_000 }] });
+  assert.equal(r.status, 201); assert.ok(r.body.pays_from); ok('the runner may notice a run (it authorises nothing) and is told when it may pay');
+  r = await call('POST', `/payouts/rules/${ruleId}/runs`, { run_key: 'w2', payouts: [{ recipient_id: 8, amount_cents: 60_000 }] });
+  assert.equal(r.status, 409); assert.equal(r.body.error, 'over_cap'); ok('a run over the caps cannot even be noticed');
+  r = await call('POST', `/payouts/rules/${ruleId}/runs/w1/hold`, {});
+  assert.equal(r.status, 403); ok('holding a run is a person\'s act too');
+
+  who = { ...who, builder: { ...who.builder, system_role: 'bfg' }, gdsSession: { source: 'web', session_id: '93' } };
+  r = await call('POST', '/payouts/approve', { recipient_id: 8, amount_cents: 100, currency: 'USD' });
+  assert.equal(r.status, 403); ok('a machine principal is refused even on a web session');
+
+  who = { builder: { id: '7', rank: 'archon', system_role: null }, gdsSession: { source: 'web', session_id: '91' } };
+  r = await call('POST', `/payouts/rules/${ruleId}/narrow`, { terms: { ...TERMS, caps: { ...TERMS.caps, per_run_cents: 300_000 } } });
+  assert.equal(r.status, 409); assert.equal(r.body.error, 'would_widen'); ok('a narrowing that would widen is refused in words');
+  r = await call('POST', `/payouts/rules/${ruleId}/narrow`, { terms: { ...TERMS, pause_hours: 96 } });
+  assert.equal(r.status, 201); ok('a real narrowing is recorded');
+  r = await call('POST', `/payouts/rules/${ruleId}/runs/w1/hold`, { note: 'checking the numbers' });
+  assert.equal(r.status, 201); ok('a person holds a run in its pause');
+  r = await call('POST', `/payouts/rules/${ruleId}/runs/w1/hold`, {});
+  assert.equal(r.status, 409); ok('a run is held once');
+
+  r = await call('POST', '/payouts/approve', [{ recipient_id: 8, amount_cents: 100, currency: 'USD' }]);
+  assert.equal(r.status, 400); ok('a list of payouts is refused: no batch approve');
+  r = await call('POST', '/payouts/approve', { recipient_id: [8, 9], amount_cents: 100, currency: 'USD' });
+  assert.equal(r.status, 400); assert.equal(r.body.error, 'one_at_a_time'); ok('a list hidden in a field is refused too');
+  r = await call('POST', '/payouts/approve', { recipient_id: 8, amount_cents: 12_345, currency: 'USD' });
+  assert.equal(r.status, 201); assert.equal(r.body.approval.kind, 'payout_approved'); ok('one payout approved by one person');
+  r = await call('POST', '/payouts/grants', { recipient_id: 8, terms: { title: 'Profit interest', summary: 'as approved by counsel', secret: 1 } });
+  assert.equal(r.status, 400); ok('a grant with unknown terms is refused');
+  r = await call('POST', '/payouts/grants', { recipient_id: 8, terms: { title: 'Profit interest', summary: 'as approved by counsel' } });
+  assert.equal(r.status, 201); assert.equal(r.body.approval.kind, 'grant_signed'); ok('one equity grant, one signature');
+
+  r = await call('POST', `/payouts/rules/${ruleId}/revoke`, {});
+  assert.equal(r.status, 201); ok('a person revokes a rule');
+  r = await call('POST', `/payouts/rules/${ruleId}/runs`, { run_key: 'w3', payouts: [{ recipient_id: 8, amount_cents: 100 }] });
+  assert.equal(r.status, 409); assert.equal(r.body.error, 'rule_revoked'); ok('nothing runs under a revoked rule');
+
+  r = await call('GET', '/payouts/approvals');
+  assert.equal(r.status, 200); assert.equal(r.body.approvals[0].kind, 'rule_revoked'); ok('the log reads back newest first');
+} finally {
+  server.close();
+}
+
+// ── 4. the migration says what the code relies on ──────────────────────────
+{
+  const sql = readFileSync(new URL('../migrations/core_283_payout_approvals.sql', import.meta.url), 'utf8');
+  assert.match(sql, /BEFORE UPDATE OR DELETE ON payout_approvals/); assert.match(sql, /BEFORE TRUNCATE ON payout_approvals/); ok('the table refuses edits, deletes and truncation by trigger');
+  assert.match(sql, /kind = 'run_noticed' OR \(session_source = 'web' AND session_id IS NOT NULL\)/); ok('the table demands a web session on every signature');
+  assert.match(sql, /system_role INTO machine/); ok('the table refuses a machine principal\'s signature');
+  for (const k of lib.SIGNED_KINDS.concat('run_noticed')) assert.ok(sql.includes(`'${k}'`), k);
+  ok('every kind the code writes is one the table accepts');
+  const grant = readFileSync(new URL('../modules/government/migrations/government_035_payout_approve.sql', import.meta.url), 'utf8');
+  assert.match(grant, /SELECT 'archon', unnest\(ARRAY\[\s*'payout.approve'/); ok('payout.approve is granted to archon');
+}
+
+// ── 5. checkApproval: the one-off check the paying tasks call ─────────────
+{
+  const stored = {
+    5: { id: 5, kind: 'payout_approved', rule_id: null, actor_id: 7, recipient_id: 8, amount_cents: '12345', currency: 'USD', terms: {}, created_at: 'x' },
+    6: { id: 6, kind: 'grant_signed', rule_id: null, actor_id: 7, recipient_id: 8, amount_cents: null, currency: null, terms: { title: 'g', summary: 'g' }, created_at: 'x' },
+  };
+  const seen = [];
+  const pool = { query: async (sql, params) => { seen.push(params); return { rows: stored[params[0]] ? [stored[params[0]]] : [] }; } };
+  const chk = (a) => lib.checkApproval(a, { pool, gates: passGates });
+  assert.equal((await chk({ id: 5, recipientId: 8, amountCents: 12345, currency: 'USD' })).ok, true); ok('checkApproval: the exact payout it approved passes');
+  assert.equal((await chk({ id: 5, recipientId: '8', amountCents: 12345, currency: 'USD' })).ok, true); ok('checkApproval: ids compare as text, not by type');
+  assert.equal((await chk({ id: 5, recipientId: 9, amountCents: 12345, currency: 'USD' })).reason, 'different_recipient'); ok('checkApproval: another recipient is refused');
+  assert.equal((await chk({ id: 5, recipientId: 8, amountCents: 12346, currency: 'USD' })).reason, 'different_amount'); ok('checkApproval: another amount is refused');
+  assert.equal((await chk({ id: 5, recipientId: 8, amountCents: 12345, currency: 'EUR' })).reason, 'different_amount'); ok('checkApproval: another currency is refused');
+  assert.equal((await chk({ id: 404, recipientId: 8, amountCents: 1, currency: 'USD' })).reason, 'no_such_approval'); ok('checkApproval: an unknown id is refused');
+  const before = seen.length;
+  assert.equal((await chk({ id: 'drop table', recipientId: 8 })).reason, 'no_such_approval'); assert.equal(seen.length, before); ok('checkApproval: a malformed id never reaches the database');
+  assert.equal((await chk({ id: 6, recipientId: 8, amountCents: 1, currency: 'USD' })).reason, 'no_such_approval'); ok('checkApproval: a grant is not a payout approval');
+  assert.equal((await chk({ id: 6, kind: 'grant_signed', recipientId: 8 })).ok, true); ok('checkApproval: a grant checks as a grant, for its recipient');
+  assert.equal((await chk({ id: 5, kind: 'grant_signed', recipientId: 8 })).reason, 'no_such_approval'); ok('checkApproval: a payout approval is not a grant');
+}
+
+// ── 6. holding a run: allowed after the pause too, refused when nothing to hold ──
+{
+  const r2 = [];
+  let id = 100;
+  const st = { ...store, insertEvent: async (e) => { const row = { id: String(id++), kind: e.kind, rule_id: e.rule_id ? String(e.rule_id) : null, run_key: e.run_key ?? null, actor_id: '7', terms: e.terms || {}, created_at: '2026-01-01T00:00:00.000Z' }; r2.push(row); return row; },
+    readRule: async (rid) => { const ev = r2.filter((r) => r.id === String(rid) || r.rule_id === String(rid)); return { rule: lib.foldRule(ev), events: ev }; } };
+  const app2 = express();
+  app2.use(express.json());
+  app2.use((req, res, next) => { res.fail = (code, { status = 400, message } = {}) => res.status(status).json({ error: code, message }); next(); });
+  app2.use((req, res, next) => { req.builder = { id: '7', rank: 'archon', system_role: null }; req.gdsSession = { source: 'web', session_id: '91' }; next(); });
+  app2.use('/', build({ store: st, gates: passGates, requireBuilder: (q, r, nx) => nx(), requirePermission: () => (q, r, nx) => nx() }));
+  const srv = http.createServer(app2).listen(0);
+  const p2 = srv.address().port;
+  const call2 = (method, path, body) => new Promise((resolve) => {
+    const r = http.request({ port: p2, path, method, headers: { 'content-type': 'application/json' } }, (res) => { let d = ''; res.on('data', (c) => (d += c)); res.on('end', () => resolve({ status: res.statusCode, body: JSON.parse(d || 'null') })); });
+    if (body) r.write(JSON.stringify(body));
+    r.end();
+  });
+  try {
+    const rule = (await call2('POST', '/payouts/rules', { terms: TERMS })).body.approval.id;
+    let r = await call2('POST', `/payouts/rules/${rule}/runs/nope/hold`, {});
+    assert.equal(r.status, 404); assert.equal(r.body.error, 'run_not_noticed'); ok('a run never noticed cannot be held');
+    r = await call2('POST', '/payouts/rules/999/runs/w1/hold', {});
+    assert.equal(r.status, 404); assert.equal(r.body.error, 'no_such_rule'); ok('a run under no rule cannot be held');
+    await call2('POST', `/payouts/rules/${rule}/runs`, { run_key: 'old', payouts: [{ recipient_id: 8, amount_cents: 100 }] });
+    r = await call2('POST', `/payouts/rules/${rule}/runs/old/hold`, {});
+    assert.equal(r.status, 201); ok('a run whose pause has long passed can still be held before it is paid');
+  } finally { srv.close(); }
+}
+
+{
+  const sql = readFileSync(new URL('../migrations/core_283_payout_approvals.sql', import.meta.url), 'utf8');
+  assert.match(sql, /payout_approvals_rules_idx[\s\S]*WHERE kind IN \('rule_signed', 'rule_narrowed', 'rule_revoked'\)/);
+  const src = readFileSync(new URL('../src/bongos/payout-approvals.js', import.meta.url), 'utf8');
+  assert.match(src, /WHERE kind IN \('rule_signed', 'rule_narrowed', 'rule_revoked'\)/);
+  ok('the rules list reads exactly the kinds its index covers');
+}
+
+console.log(`\n${n} passed`);

package/tests/payout_approvals_db.mjs

@@ -0,0 +1,106 @@
+// tests/payout_approvals_db.mjs — task 1004913 (ADR 0385 D4, ADR 0387 D2). Real DB.
+// The approval log built from the real migration in a throwaway schema, proving the
+// DATABASE (not the code that writes it) refuses: any UPDATE, DELETE or TRUNCATE; a
+// signature with no web session; a machine principal's signature; a narrowing that
+// widens; anything after a revocation. Then the store's checkRun over real rows.
+// Self-skips without a reachable Postgres.
+// Run:  DATABASE_URL=... node tests/payout_approvals_db.mjs
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { strict as assert } from 'node:assert';
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+const here = dirname(fileURLToPath(import.meta.url));
+
+const pgPool = new Pool({ connectionString: process.env.DATABASE_URL || undefined, max: 1 });
+let client;
+try { client = await pgPool.connect(); } catch (e) {
+  console.log(`payout_approvals_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pgPool.end().catch(() => {});
+  process.exit(0);
+}
+const SCHEMA = `t1004913_${process.pid}`;
+let pass = 0;
+const ok = (c, m) => { assert.ok(c, m); pass++; console.log(`  ok - ${m}`); };
+const refused = async (sql, params, m) => {
+  await client.query('SAVEPOINT s');
+  let threw = false;
+  try { await client.query(sql, params); } catch { threw = true; }
+  await client.query('ROLLBACK TO SAVEPOINT s');
+  ok(threw, m);
+};
+
+const TERMS = { caps: { per_payout_cents: 500, per_run_cents: 1000, per_month_cents: 5000 }, currency: 'USD', formula: { kind: 'task_pay_terms' }, schedule: 'weekly', pause_hours: 48 };
+
+try {
+  await client.query(`CREATE SCHEMA ${SCHEMA}`);
+  await client.query(`SET search_path TO ${SCHEMA}`);
+  await client.query('CREATE TABLE builders (id bigserial PRIMARY KEY, system_role text)');
+  await client.query(readFileSync(join(here, '..', 'migrations', 'core_283_payout_approvals.sql'), 'utf8'));
+  await client.query("INSERT INTO builders (system_role) VALUES (NULL), (NULL), ('bfg')");
+  await client.query('BEGIN');
+
+  const lib = require('../src/bongos/payout-approvals.js');
+  const o = { pool: client };
+  // The N10 gates pass everyone here; tests/payout_gates_db.mjs runs them for real.
+  const og = { pool: client, gates: { gateOwedPay: async () => ({ ok: true, pay_to: 'self' }), gateRecipient: async () => ({ ok: true, pay_to: 'self' }), hasCosign: async () => true, gateOwedPayMany: async (m) => new Map([...m.keys()].map((k) => [k, { ok: true, pay_to: 'self' }])), cosignedInRun: async () => new Set() } };
+  const person = { id: 1, rank: 'archon', session_id: 11, session_source: 'web' };
+
+  const rule = await lib.insertEvent({ kind: 'rule_signed', actor: person, terms: TERMS }, o);
+  ok(rule.kind === 'rule_signed', 'a person signs a rule');
+
+  await refused('UPDATE payout_approvals SET note = $1 WHERE id = $2', ['x', rule.id], 'an UPDATE is refused by the database');
+  await refused('DELETE FROM payout_approvals WHERE id = $1', [rule.id], 'a DELETE is refused by the database');
+  await refused('TRUNCATE payout_approvals', [], 'a TRUNCATE is refused by the database');
+
+  const ins = "INSERT INTO payout_approvals (kind, actor_id, session_id, session_source, recipient_id, amount_cents, currency) VALUES ('payout_approved', $1, $2, $3, 2, 100, 'USD')";
+  await refused(ins, [1, 12, 'cli'], 'a signature from a CLI session is refused by the database');
+  await refused(ins, [1, null, 'web'], 'a signature naming no session is refused');
+  await refused(ins, [3, 13, 'web'], 'a machine principal cannot sign, even on a web session');
+  await client.query(ins, [1, 14, 'web']);
+  ok(true, 'a person on the website approves one payout');
+
+  const narrow = (terms) => client.query(
+    "INSERT INTO payout_approvals (kind, rule_id, actor_id, session_id, session_source, terms) VALUES ('rule_narrowed', $1, 1, 15, 'web', $2::jsonb)",
+    [rule.id, JSON.stringify(terms)],
+  );
+  const widen = async (terms, m) => { await client.query('SAVEPOINT s'); let threw = false; try { await narrow(terms); } catch { threw = true; } await client.query('ROLLBACK TO SAVEPOINT s'); ok(threw, m); };
+  await widen({ ...TERMS, caps: { ...TERMS.caps, per_run_cents: 2000 } }, 'the database refuses a narrowing that raises a cap');
+  await widen({ ...TERMS, caps: { per_payout_cents: 500, per_run_cents: 1000 } }, 'the database refuses a narrowing that removes a cap');
+  await widen({ ...TERMS, pause_hours: 1 }, 'the database refuses a narrowing that shortens the pause');
+  await widen({ ...TERMS, schedule: 'on_ship' }, 'the database refuses a narrowing that changes the schedule');
+  await narrow({ ...TERMS, caps: { ...TERMS.caps, per_payout_cents: 400 }, pause_hours: 72 });
+  ok(true, 'a real narrowing is accepted');
+  await widen({ ...TERMS, pause_hours: 48 }, 'the bar is the LATEST terms, not the signed ones');
+
+  const runner = { id: 3, session_id: null, session_source: 'cli' };
+  await lib.insertEvent({ kind: 'run_noticed', rule_id: rule.id, run_key: 'w1', actor: runner, amount_cents: 700, currency: 'USD', terms: { payouts: [{ recipient_id: '2', amount_cents: 400 }, { recipient_id: '1', amount_cents: 300 }] } }, o);
+  ok(true, 'a runner (even a machine) may notice a run: it authorises nothing');
+  const P = [{ recipient_id: '1', amount_cents: 300 }, { recipient_id: '2', amount_cents: 400 }];
+  ok((await lib.checkRun({ ruleId: rule.id, runKey: 'w1', payouts: P }, og)).reason === 'in_pause_window', 'a fresh run waits out its pause');
+  const later = new Date(Date.now() + 73 * 3600_000);
+  ok((await lib.checkRun({ ruleId: rule.id, runKey: 'w1', payouts: P, now: later }, og)).ok, 'after the pause it pays exactly as noticed');
+
+  await refused("INSERT INTO payout_approvals (kind, rule_id, run_key, actor_id, session_id, session_source) VALUES ('run_held', $1, 'nope', 1, 16, 'web')", [rule.id], 'holding a run never noticed is refused');
+  await lib.insertEvent({ kind: 'run_held', rule_id: rule.id, run_key: 'w1', actor: person }, o);
+  ok((await lib.checkRun({ ruleId: rule.id, runKey: 'w1', payouts: P, now: later }, og)).reason === 'run_held', 'a held run never pays');
+
+  await lib.insertEvent({ kind: 'rule_revoked', rule_id: rule.id, actor: person }, o);
+  await refused("INSERT INTO payout_approvals (kind, rule_id, run_key, actor_id, amount_cents, currency) VALUES ('run_noticed', $1, 'w2', 3, 100, 'USD')", [rule.id], 'nothing may follow a revocation');
+  ok((await lib.listRules(o))[0].active === false, 'the rule reads back revoked');
+  ok((await lib.listLog(o)).length >= 6, 'the log reads back');
+
+  const one = await lib.insertEvent({ kind: 'payout_approved', actor: person, recipient_id: 2, amount_cents: 250, currency: 'USD' }, o);
+  ok((await lib.checkApproval({ id: one.id, recipientId: 2, amountCents: 250, currency: 'USD' }, og)).ok, 'checkApproval passes the exact stored approval');
+  ok((await lib.checkApproval({ id: one.id, recipientId: 1, amountCents: 250, currency: 'USD' }, og)).reason === 'different_recipient', 'checkApproval refuses another recipient against real rows');
+  ok((await lib.checkApproval({ id: one.id, recipientId: 2, amountCents: 251, currency: 'USD' }, og)).reason === 'different_amount', 'checkApproval refuses another amount against real rows');
+  ok((await lib.checkApproval({ id: rule.id, recipientId: 2, amountCents: 250, currency: 'USD' }, og)).reason === 'no_such_approval', 'a rule is not a one-off approval');
+  await client.query('ROLLBACK');
+} finally {
+  await client.query(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`).catch(() => {});
+  client.release();
+  await pgPool.end();
+}
+console.log(`payout_approvals_db.mjs: ${pass} passed`);