@bongos/core 1.24.14 → 1.24.16

package/tests/pay_type_gates.mjs

@@ -0,0 +1,234 @@
+// tests/pay_type_gates.mjs — a pay type can be put on a task only after its gate is
+// cleared for the project (task 1004991, goal 1000092; ADR 0385 "Pay-type gates").
+//
+// What is real: modules/lifecycle/pay-type-gates.js (the list, the verdict, the checker,
+// the writer), the pay-type-gates router, the lifecycle tasks router (PATCH /tasks/:id)
+// and the project-settings router (the standing terms). What is faked: the caller
+// (requireBuilder, requireRank, requirePermission) and Postgres, a recording stand-in
+// holding the gate history and the pay-term sets in memory.
+//
+// Run:  node tests/pay_type_gates.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+process.env.NODE_ENV = 'test';
+
+let gateRows = [];
+let sets = [];
+let terms = [];
+const query = async (sql, params = []) => {
+  if (/^\s*(BEGIN|COMMIT|ROLLBACK)/i.test(sql)) return { rows: [] };
+  if (/INSERT INTO lifecycle_pay_type_gates/.test(sql)) {
+    const [pay_type, requirement, state, evidence_ref, decided_by] = params;
+    gateRows.push({ id: gateRows.length + 1, pay_type, requirement, state, evidence_ref, decided_by, decided_at: new Date(Date.UTC(2026, 9, 30, 0, gateRows.length)) });
+    return { rows: [] };
+  }
+  if (/FROM lifecycle_pay_type_gates/.test(sql)) {
+    const newest = new Map();
+    for (const r of gateRows.filter((x) => params[0].includes(x.pay_type))) newest.set(`${r.pay_type}/${r.requirement}`, r);
+    return { rows: [...newest.values()] };
+  }
+  if (/INSERT INTO lifecycle_pay_term_sets/.test(sql)) {
+    const row = { id: sets.length + 1, task_id: params[0], set_by: params[1], set_at: new Date() };
+    sets.push(row);
+    return { rows: [row] };
+  }
+  if (/INSERT INTO lifecycle_pay_terms/.test(sql)) {
+    params[1].forEach((pay_type, i) => terms.push({ set_id: params[0], pay_type, position: i }));
+    return { rows: [] };
+  }
+  if (/FROM lifecycle_pay_term_sets s LEFT JOIN builders/.test(sql)) return { rows: [] };
+  return { rows: [] };
+};
+const pool = { query, connect: async () => ({ query, release() {} }) };
+const poolPath = require.resolve('../src/bongos/pool.js');
+require.cache[poolPath] = { id: poolPath, filename: poolPath, loaded: true, exports: { pool } };
+
+let caller = { id: 7, rank: 'archon' };
+let held = [];
+const api = require('../src/module-api.js');
+const set = (k, v) => Object.defineProperty(api, k, { value: v, configurable: true, writable: true });
+set('requireBuilder', (req, _res, next) => { req.builder = { ...caller }; next(); });
+set('requireRank', (rank) => (req, res, next) => (req.builder.rank === rank ? next() : res.fail('rank_forbidden', { status: 403, message: `needs ${rank}` })));
+set('requirePermission', (atom) => (req, res, next) => (held.includes(atom) ? next() : res.fail('permission_denied', { status: 403, message: `needs ${atom}` })));
+set('requireActAlone', () => (_req, _res, next) => next());
+set('withTx', async (fn) => fn({ query }));
+
+const db = require('../modules/lifecycle/db.js');
+const TASK = { id: 5150, title: 'a task', status: 'ready', version_id: 'BONGOS-V2' };
+db.getTask = async (id) => (Number(id) === TASK.id ? { ...TASK } : null);
+db.getTaskDependencies = async () => [];
+db.getTaskDependents = async () => [];
+
+const lib = require('../modules/lifecycle/pay-type-gates.js');
+const payTerms = require('../modules/lifecycle/pay-terms.js');
+
+const express = require('express');
+const app = express();
+app.use(express.json());
+app.use((req, res, next) => {
+  res.fail = (code, o) => {
+    const opts = typeof o === 'number' ? { status: o } : (o || {});
+    return res.status(opts.status || 400).json({ error: code, message: opts.message });
+  };
+  next();
+});
+app.use('/api', require('../modules/lifecycle/routes/tasks.js')());
+app.use('/api', require('../modules/lifecycle/routes/project-settings.js')());
+app.use('/api', require('../modules/lifecycle/routes/pay-type-gates.js')());
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api`;
+const call = async (method, path, body) => {
+  const r = await fetch(base + path, { method, headers: { 'content-type': 'application/json' }, body: body ? JSON.stringify(body) : undefined });
+  return { status: r.status, body: await r.json().catch(() => null) };
+};
+const reset = () => { gateRows = []; sets = []; terms = []; held = ['task.edit', 'project.settings.manage', 'payout.approve']; caller = { id: 7, rank: 'archon' }; };
+const clear = (payType) => Promise.all(lib.requirementIds(payType).map((requirement) => call('PUT', `/pay-type-gates/${payType}/${requirement}`,
+  requirement === lib.ACKNOWLEDGEMENT ? { state: 'cleared', acknowledged: true } : { state: 'cleared', evidence_ref: `doc for ${requirement}` })));
+
+let passed = 0;
+let failed = 0;
+async function t(name, fn) {
+  reset();
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack}`); }
+}
+
+console.log('pay-type gates (task 1004991):');
+
+await t('every pay type a term can carry has a requirement list, and nothing else does', () => {
+  assert.deepEqual(Object.keys(lib.REQUIREMENTS).sort(), [...payTerms.PAY_TYPES].sort());
+  for (const p of payTerms.PAY_TYPES) assert.ok(lib.requirementIds(p).length > 0, `${p} has requirements`);
+  assert.deepEqual(lib.requirementIds('self_managed'), ['bongos_moves_and_guarantees_nothing']);
+  assert.ok(!('eu_labour' in lib.REQUIREMENTS), 'eu_labour has no list to clear');
+});
+
+await t('a pay term whose gate is not cleared is refused, and nothing is written', async () => {
+  const r = await call('PATCH', `/tasks/${TASK.id}`, { pay_terms: [{ pay_type: 'cash', amount: '500', unit: 'USD' }] });
+  assert.equal(r.status, 409);
+  assert.equal(r.body.error, 'pay_type_gate_not_cleared');
+  assert.match(r.body.message, /processor_onboarding/);
+  assert.deepEqual([sets.length, terms.length], [0, 0]);
+});
+
+await t('the project\'s standing terms obey the same gate', async () => {
+  const r = await call('PATCH', '/project-settings/pay-terms', { terms: [{ pay_type: 'equity' }] });
+  assert.equal(r.status, 409);
+  assert.equal(r.body.error, 'pay_type_gate_not_cleared');
+  assert.equal(sets.length, 0);
+});
+
+await t('a half-cleared gate still refuses; the last requirement opens it', async () => {
+  const [first, ...rest] = lib.requirementIds('cash');
+  assert.equal((await call('PUT', `/pay-type-gates/cash/${first}`, { state: 'cleared', evidence_ref: 'processor verdict 41' })).status, 200);
+  let r = await call('PATCH', `/tasks/${TASK.id}`, { pay_terms: [{ pay_type: 'cash' }] });
+  assert.equal(r.status, 409);
+  for (const req of rest) await call('PUT', `/pay-type-gates/cash/${req}`, { state: 'cleared', evidence_ref: 'on file' });
+  r = await call('PATCH', `/tasks/${TASK.id}`, { pay_terms: [{ pay_type: 'cash', amount: '500', unit: 'USD' }] });
+  assert.equal(r.status, 200);
+  assert.equal(terms.length, 1);
+});
+
+await t('revoking a requirement closes the gate again', async () => {
+  await clear('cash');
+  const req = lib.requirementIds('cash')[0];
+  assert.equal((await call('PUT', `/pay-type-gates/cash/${req}`, { state: 'revoked', evidence_ref: 'processor paused us' })).status, 200);
+  const r = await call('PATCH', `/tasks/${TASK.id}`, { pay_terms: [{ pay_type: 'cash' }] });
+  assert.equal(r.status, 409);
+});
+
+await t('self_managed clears with only the acknowledgement', async () => {
+  const req = lib.ACKNOWLEDGEMENT;
+  let r = await call('PUT', `/pay-type-gates/self_managed/${req}`, { state: 'cleared', evidence_ref: 'anything' });
+  assert.equal(r.status, 400, 'evidence alone is not the acknowledgement');
+  r = await call('PUT', `/pay-type-gates/self_managed/${req}`, { state: 'cleared', acknowledged: true });
+  assert.equal(r.status, 200);
+  assert.equal(r.body.gate.cleared, true);
+  assert.equal(r.body.gate.requirements[0].evidence_ref, payTerms.SELF_MANAGED_LABEL, 'the label is what was acknowledged');
+  const t1 = await call('PATCH', `/tasks/${TASK.id}`, { pay_terms: [{ pay_type: 'self_managed' }] });
+  assert.equal(t1.status, 200);
+});
+
+await t('eu_labour can never be cleared, by any route, and never reaches a term', async () => {
+  const w = await call('PUT', '/pay-type-gates/eu_labour/anything', { state: 'cleared', evidence_ref: 'counsel says so' });
+  assert.equal(w.status, 409);
+  assert.equal(w.body.error, 'pay_type_never_clearable');
+  assert.equal(gateRows.length, 0, 'no row written');
+  const p = await call('PATCH', `/tasks/${TASK.id}`, { pay_terms: [{ pay_type: 'eu_labour' }] });
+  assert.equal(p.status, 400);
+  assert.equal(sets.length, 0);
+  const all = (await call('GET', '/pay-type-gates')).body.gates.find((g) => g.pay_type === 'eu_labour');
+  assert.deepEqual([all.cleared, all.never], [false, true]);
+  assert.deepEqual(lib.gateVerdict('eu_labour', [{ pay_type: 'eu_labour', requirement: 'x', state: 'cleared' }]).cleared, false);
+});
+
+await t('a forged client request that claims a cleared gate is refused', async () => {
+  for (const forged of [
+    { pay_type: 'cash', gate_cleared: true },
+    { pay_type: 'cash', cleared: true, cleared_by: 7 },
+    { pay_type: 'cash', gate: { state: 'cleared' } },
+  ]) {
+    const r = await call('PATCH', `/tasks/${TASK.id}`, { pay_terms: [forged] });
+    assert.equal(r.status, 400, JSON.stringify(forged));
+  }
+  const top = await call('PATCH', `/tasks/${TASK.id}`, { gate_cleared: true, pay_terms: [{ pay_type: 'cash' }] });
+  assert.ok(top.status >= 400, 'a top-level claim does not open it either');
+  assert.deepEqual([sets.length, terms.length, gateRows.length], [0, 0, 0]);
+});
+
+await t('only the owner records a requirement, and who recorded it is the caller, not the body', async () => {
+  const req = lib.requirementIds('cash')[0];
+  caller = { id: 9, rank: 'metic' }; held = held.filter((a) => a !== 'payout.approve');
+  let r = await call('PUT', `/pay-type-gates/cash/${req}`, { state: 'cleared', evidence_ref: 'x' });
+  assert.equal(r.status, 403);
+  assert.equal(gateRows.length, 0);
+  caller = { id: 7, rank: 'archon' }; held = [...held, 'payout.approve'];
+  r = await call('PUT', `/pay-type-gates/cash/${req}`, { state: 'cleared', evidence_ref: 'x', decided_by: 99 });
+  assert.equal(r.status, 400, 'a recorder in the body is refused');
+  r = await call('PUT', `/pay-type-gates/cash/${req}`, { state: 'cleared', evidence_ref: 'x' });
+  assert.equal(r.status, 200);
+  assert.equal(gateRows[0].decided_by, 7);
+  assert.equal(r.body.gate.requirements[0].cleared_by, 7);
+});
+
+await t('a non-owner sees met or missing, never the evidence or who cleared it', async () => {
+  await clear('cash');
+  const owner = (await call('GET', '/pay-type-gates')).body.gates.find((g) => g.pay_type === 'cash');
+  assert.ok(owner.requirements[0].evidence_ref && owner.requirements[0].cleared_by, 'the owner sees both');
+  caller = { id: 9, rank: 'metic' }; held = held.filter((a) => a !== 'payout.approve');
+  const other = (await call('GET', '/pay-type-gates')).body.gates.find((g) => g.pay_type === 'cash');
+  assert.equal(other.cleared, true);
+  for (const r of other.requirements) {
+    assert.equal(r.met, true);
+    assert.ok(!('evidence_ref' in r) && !('cleared_by' in r) && !('cleared_at' in r));
+  }
+});
+
+await t('a write needs a known requirement, a state and evidence', async () => {
+  const req = lib.requirementIds('cash')[0];
+  assert.equal((await call('PUT', '/pay-type-gates/wages/x', { state: 'cleared', evidence_ref: 'x' })).status, 404);
+  assert.equal((await call('PUT', '/pay-type-gates/cash/not_a_requirement', { state: 'cleared', evidence_ref: 'x' })).status, 404);
+  assert.equal((await call('PUT', `/pay-type-gates/cash/${req}`, { state: 'maybe', evidence_ref: 'x' })).status, 400);
+  assert.equal((await call('PUT', `/pay-type-gates/cash/${req}`, { state: 'cleared', evidence_ref: '   ' })).status, 400);
+  assert.equal((await call('PUT', `/pay-type-gates/cash/${req}`, { state: 'cleared', evidence_ref: 'x'.repeat(501) })).status, 400);
+  assert.equal(gateRows.length, 0);
+});
+
+await t('a stray row for a requirement not on the list cannot clear a gate', () => {
+  const rows = [{ pay_type: 'cash', requirement: 'made_up', state: 'cleared', evidence_ref: 'x', decided_by: 1, decided_at: new Date() }];
+  assert.equal(lib.gateVerdict('cash', rows).cleared, false);
+});
+
+await t('no terms means no gate read; clearing every type then lets a mixed list through', async () => {
+  const r0 = await call('PATCH', `/tasks/${TASK.id}`, { pay_terms: [] });
+  assert.equal(r0.status, 200);
+  for (const p of payTerms.PAY_TYPES) await clear(p);
+  const all = await call('PATCH', `/tasks/${TASK.id}`, { pay_terms: payTerms.PAY_TYPES.map((pay_type) => ({ pay_type })) });
+  assert.equal(all.status, 200);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+server.close();
+process.exit(failed ? 1 : 0);

package/tests/pay_type_gates_db.mjs

@@ -0,0 +1,84 @@
+// tests/pay_type_gates_db.mjs — task 1004991 (ADR 0385 "Pay-type gates"). Real DB.
+// The gate table built from the real migration (lifecycle_019) in a throwaway schema,
+// written and read through the real modules/lifecycle/pay-type-gates.js, proving the
+// DATABASE holds the rules the DB-free tests/pay_type_gates.mjs assumes: the history
+// cannot be edited or deleted, a row for eu_labour or an unknown type is refused, a
+// state or evidence the writer would never send is refused, and the read SQL resolves
+// the newest record per requirement into a verdict.
+// Self-skips without a reachable Postgres.
+// Run:  DATABASE_URL=... node tests/pay_type_gates_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(`pay_type_gates_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pgPool.end().catch(() => {});
+  process.exit(0);
+}
+const SCHEMA = `t1004991_${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);
+};
+
+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, github_login text NOT NULL)');
+  await client.query(readFileSync(join(here, '..', 'modules', 'lifecycle', 'migrations', 'lifecycle_019_pay_type_gates.sql'), 'utf8'));
+  await client.query("INSERT INTO builders (github_login) VALUES ('owner'), ('lead')");
+  await client.query('BEGIN');
+
+  const lib = require('../modules/lifecycle/pay-type-gates.js');
+  const o = { db: client };
+  const rec = (payType, requirement, state, evidenceRef, builderId = 1) =>
+    lib.recordRequirement({ payType, requirement, state, evidenceRef, builderId }, o);
+
+  let v = await rec('self_managed', lib.ACKNOWLEDGEMENT, 'cleared', 'acknowledged');
+  ok(v.cleared === true && Number(v.requirements[0].cleared_by) === 1, 'the one self-managed requirement clears its gate, naming who cleared it');
+
+  for (const req of lib.requirementIds('cash')) v = await rec('cash', req, 'cleared', `ref ${req}`, 2);
+  ok(v.cleared === true, 'every cash requirement cleared opens the gate');
+  v = await rec('cash', 'tax_details', 'revoked', 'details withdrawn');
+  ok(v.cleared === false && v.missing.join() === 'tax_details', 'the newest record per requirement wins: a revoke closes it again');
+  v = await rec('cash', 'tax_details', 'cleared', 'collected again');
+  ok(v.cleared === true, 'a later clearing reopens it');
+
+  const refusal = await lib.refuseUnclearedGates([{ pay_type: 'equity' }, { pay_type: 'cash' }], o);
+  ok(refusal && refusal.pay_type === 'equity', 'the checker names the first type whose gate is open');
+  ok((await lib.refuseUnclearedGates([{ pay_type: 'cash' }, { pay_type: 'self_managed' }], o)) === null, 'cleared types pass');
+
+  const all = await lib.readGates(o);
+  ok(all.length === 7 && all.find((g) => g.pay_type === 'eu_labour').never === true, 'the owner view lists eu_labour as never clearable');
+
+  const { rows: [aRow] } = await client.query('SELECT id FROM lifecycle_pay_type_gates LIMIT 1');
+  await refused('UPDATE lifecycle_pay_type_gates SET state = $1 WHERE id = $2', ['revoked', aRow.id], 'a record cannot be edited');
+  await refused('DELETE FROM lifecycle_pay_type_gates WHERE id = $1', [aRow.id], 'a record cannot be deleted');
+  await refused("INSERT INTO lifecycle_pay_type_gates (pay_type, requirement, state, evidence_ref, decided_by) VALUES ('eu_labour', 'x', 'cleared', 'y', 1)", [], 'the database refuses any row for eu_labour');
+  await refused("INSERT INTO lifecycle_pay_type_gates (pay_type, requirement, state, evidence_ref, decided_by) VALUES ('wages', 'x', 'cleared', 'y', 1)", [], 'an unknown pay type is refused');
+  await refused("INSERT INTO lifecycle_pay_type_gates (pay_type, requirement, state, evidence_ref, decided_by) VALUES ('cash', 'x', 'pending', 'y', 1)", [], 'a state other than cleared or revoked is refused');
+  await refused("INSERT INTO lifecycle_pay_type_gates (pay_type, requirement, state, evidence_ref, decided_by) VALUES ('cash', 'x', 'cleared', '', 1)", [], 'a record with no evidence reference is refused');
+  await refused("INSERT INTO lifecycle_pay_type_gates (pay_type, requirement, state, evidence_ref, decided_by) VALUES ('cash', 'x', 'cleared', 'y', 999)", [], 'a recorder who is not a builder is refused');
+
+  await client.query('ROLLBACK');
+  console.log(`pay_type_gates_db: ${pass} passed`);
+} finally {
+  await client.query('ROLLBACK').catch(() => {});
+  await client.query('SET search_path TO public').catch(() => {});
+  await client.query(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`).catch(() => {});
+  client.release();
+  await pgPool.end();
+}

package/tests/project_account.mjs

@@ -0,0 +1,125 @@
+// tests/project_account.mjs — the project account's record and view (task 1003182,
+// goal 1000092; ADR 0385, ADR 0397). Behaviour of modules/economy/project-account.js:
+//   - every movement names its cause, and a missing cause is refused before the INSERT;
+//   - the direction is fixed by the kind, so a row cannot disagree with itself;
+//   - a retried processor reference books nothing the second time;
+//   - the view sums the record, shows what is held, and names drift only when the
+//     processor's own figure is known; an unreadable processor never blocks the view.
+// The SQL itself is proven against real Postgres in tests/project_account_db.mjs.
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const A = require('../modules/economy/project-account.js');
+
+const refusal = (input) => { try { A.checkMovement(input); } catch (e) { return e; } return null; };
+
+test('a payout must name the builder, the task and the processor transfer', () => {
+  const full = { kind: 'payout', amountMicro: 5_000_000, builderId: 7, taskId: 99, processorRef: 'tr_1' };
+  assert.equal(refusal(full), null);
+  for (const missing of ['builderId', 'taskId', 'processorRef']) {
+    const e = refusal({ ...full, [missing]: undefined });
+    assert.ok(e instanceof A.MovementRefusal && e.code === 'cause_missing', `no ${missing} must be refused`);
+  }
+});
+
+test('funding and fees need a processor reference; a return needs the builder too', () => {
+  assert.equal(refusal({ kind: 'funding', amountMicro: 1, processorRef: 'ch_1' }), null);
+  assert.equal(refusal({ kind: 'funding', amountMicro: 1 }).code, 'cause_missing');
+  assert.equal(refusal({ kind: 'fee', amountMicro: 1 }).code, 'cause_missing');
+  assert.equal(refusal({ kind: 'payout_return', amountMicro: 1, processorRef: 'tr_1' }).code, 'cause_missing');
+  assert.equal(refusal({ kind: 'payout_return', amountMicro: 1, processorRef: 'tr_1', builderId: 7 }), null);
+});
+
+test('a correction names the movement it corrects, who made it, and why', () => {
+  const adj = { kind: 'adjustment', direction: 'in', amountMicro: 10, correctsId: 4, actorId: 1, note: 'fee booked twice' };
+  assert.equal(refusal(adj), null);
+  assert.equal(refusal({ ...adj, correctsId: undefined }).code, 'cause_missing');
+  assert.equal(refusal({ ...adj, note: '  ' }).code, 'cause_missing');
+  assert.equal(refusal({ ...adj, direction: 'sideways' }).code, 'bad_direction');
+});
+
+test('a hold is for a task; the amount is a positive whole number', () => {
+  assert.equal(refusal({ kind: 'hold', amountMicro: 5 }).code, 'cause_missing');
+  assert.equal(refusal({ kind: 'hold', amountMicro: 5, taskId: 3 }), null);
+  for (const bad of [0, -1, 1.5, NaN, 'x']) assert.equal(refusal({ kind: 'hold', taskId: 3, amountMicro: bad }).code, 'bad_amount');
+  assert.equal(refusal({ kind: 'spend', amountMicro: 5 }).code, 'bad_kind');
+});
+
+test('the direction comes from the kind, never from the caller', () => {
+  const row = A.checkMovement({ kind: 'payout', amountMicro: 5, builderId: 1, taskId: 2, processorRef: 't', direction: 'in' });
+  assert.equal(row.direction, 'out');
+  assert.equal(A.checkMovement({ kind: 'funding', amountMicro: 5, processorRef: 'c' }).direction, 'in');
+  assert.equal(A.checkMovement({ kind: 'hold', amountMicro: 5, taskId: 1 }).direction, 'none');
+});
+
+// A stand-in for the table that enforces the one-per-(kind, reference) rule the way the
+// unique index does, so the retry path through recordMovement is exercised for real.
+function fakeTable() {
+  const rows = [];
+  return {
+    rows,
+    async query(sql, p) {
+      if (/^\s*INSERT/.test(sql)) {
+        const [kind, direction, amount_micro, builder_id, task_id, corrects_id, processor_ref] = p;
+        if (processor_ref && rows.some((r) => r.kind === kind && r.processor_ref === processor_ref)) return { rows: [] };
+        const row = { id: rows.length + 1, kind, direction, amount_micro, builder_id, task_id, corrects_id, processor_ref };
+        rows.push(row);
+        return { rows: [row] };
+      }
+      return { rows: rows.filter((r) => r.kind === p[0] && r.processor_ref === p[1]) };
+    },
+  };
+}
+
+test('a retried payout books nothing the second time and hands back the first row', async () => {
+  const db = fakeTable();
+  const input = { kind: 'payout', amountMicro: 5_000_000, builderId: 7, taskId: 99, processorRef: 'tr_1' };
+  const first = await A.recordMovement(db, input);
+  const again = await A.recordMovement(db, input);
+  assert.equal(first.recorded, true);
+  assert.equal(again.recorded, false);
+  assert.equal(again.row.id, first.row.id);
+  assert.equal(db.rows.length, 1);
+});
+
+test('a refused movement never reaches the database', async () => {
+  const db = fakeTable();
+  await assert.rejects(() => A.recordMovement(db, { kind: 'payout', amountMicro: 5 }), A.MovementRefusal);
+  assert.equal(db.rows.length, 0);
+});
+
+// ---- the view ---------------------------------------------------------------
+
+const totals = { recorded_balance_micro: '7000000', in_micro: '10000000', out_micro: '3000000', held_micro: '2000000', movements: '4' };
+
+test('available is the recorded balance less what is held, and the account holds no money', () => {
+  const v = A.shapeAccount(totals, [], null);
+  assert.equal(v.recorded_balance_micro, 7_000_000);
+  assert.equal(v.held_micro, 2_000_000);
+  assert.equal(v.available_micro, 5_000_000);
+  assert.equal(v.holds_money, false);
+});
+
+test('drift is named only when the processor figure is known', () => {
+  assert.equal(A.shapeAccount(totals, [], null).drift_micro, null);
+  assert.equal(A.shapeAccount(totals, [], null).processor_balance_micro, null);
+  const v = A.shapeAccount(totals, [], 6_500_000);
+  assert.equal(v.processor_balance_micro, 6_500_000);
+  assert.equal(v.drift_micro, -500_000);
+  assert.equal(A.shapeAccount(totals, [], 0).drift_micro, -7_000_000, 'a processor balance of zero is a real figure, not "unknown"');
+});
+
+test('readAccount reads the record and survives an unreadable processor', async () => {
+  const db = { async query(sql) { return /SUM\(/.test(sql) ? { rows: [totals] } : { rows: [{ id: 1, kind: 'funding', amount_micro: '10000000' }] }; } };
+  const ok = await A.readAccount(db, { processor: { balanceMicro: async () => 7_000_000 } });
+  assert.equal(ok.drift_micro, 0);
+  assert.equal(ok.movements[0].amount_micro, 10_000_000);
+  const down = await A.readAccount(db, { processor: { balanceMicro: async () => { throw new Error('processor down'); } } });
+  assert.equal(down.processor_balance_micro, null);
+  assert.match(down.processor_error, /could not be read/);
+  assert.doesNotMatch(down.processor_error, /processor down/, 'the raw processor error never reaches the client');
+  assert.equal(down.recorded_balance_micro, 7_000_000, 'the record still answers');
+});

package/tests/project_account_db.mjs

@@ -0,0 +1,97 @@
+// tests/project_account_db.mjs — task 1003182 (goal 1000092). Real DB.
+//
+// Applies the REAL modules/economy/migrations/economy_002_project_account.sql and proves what
+// Postgres itself refuses: a payout with no task, a funding with no processor reference, an
+// adjustment that corrects nothing, a row whose direction contradicts its kind, an UPDATE or
+// DELETE of any row, and a second movement for the same processor reference; then that the real
+// readAccount sums the record. Two rules are probed by dropping them (the cause rule and the
+// append-only trigger): with the rule gone the same write lands, so the refusal was the rule's.
+//
+// Self-skips without a reachable Postgres.
+// Run:  DATABASE_URL=... node tests/project_account_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 A = require('../modules/economy/project-account.js');
+const here = dirname(fileURLToPath(import.meta.url));
+const MIGRATION = readFileSync(join(here, '..', 'modules', 'economy', 'migrations', 'economy_002_project_account.sql'), 'utf8');
+
+const pgPool = new Pool({ connectionString: process.env.DATABASE_URL || undefined, max: 1 });
+let client;
+try { client = await pgPool.connect(); } catch (e) {
+  console.log(`project_account_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pgPool.end().catch(() => {});
+  process.exit(0);
+}
+const SCHEMA = `t1003182_${process.pid}`;
+let pass = 0;
+const ok = (c, m) => { assert.ok(c, m); pass++; console.log(`  ok - ${m}`); };
+const T = 'economy_project_account_movements';
+const rejects = async (sql, params) => {
+  await client.query('SAVEPOINT s');
+  let err = null;
+  try { await client.query(sql, params); } catch (e) { err = e; }
+  await client.query('ROLLBACK TO SAVEPOINT s');
+  return err;
+};
+const INS = `INSERT INTO ${T} (kind, direction, amount_micro, builder_id, task_id, corrects_id, processor_ref, actor_id, note)
+             VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)`;
+
+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, display_name text)');
+  await client.query('CREATE TABLE tasks (id bigserial PRIMARY KEY, title text)');
+  await client.query('CREATE TABLE schema_migrations (version text PRIMARY KEY)');
+  await client.query("INSERT INTO builders (display_name) VALUES ('Ada'), ('Owner')");
+  await client.query("INSERT INTO tasks (title) VALUES ('Build the thing')");
+  await client.query(MIGRATION);
+  await client.query('BEGIN');
+
+  const code = (e) => e && e.code;
+  ok(code(await rejects(INS, ['payout', 'out', 5, 1, null, null, 'tr_x', null, ''])) === '23514', 'a payout with no task is refused by the database');
+  ok(code(await rejects(INS, ['payout', 'out', 5, null, 1, null, 'tr_x', null, ''])) === '23514', 'a payout with no builder is refused');
+  ok(code(await rejects(INS, ['payout', 'out', 5, 1, 1, null, null, null, ''])) === '23514', 'a payout with no processor transfer is refused');
+  ok(code(await rejects(INS, ['funding', 'in', 5, null, null, null, null, null, ''])) === '23514', 'a funding with no processor reference is refused');
+  ok(code(await rejects(INS, ['adjustment', 'in', 5, null, null, null, null, 2, 'why'])) === '23514', 'an adjustment that corrects nothing is refused');
+  ok(code(await rejects(INS, ['payout', 'in', 5, 1, 1, null, 'tr_x', null, ''])) === '23514', 'a payout that says it came IN is refused');
+  ok(code(await rejects(INS, ['funding', 'in', 0, null, null, null, 'ch_x', null, ''])) === '23514', 'a zero amount is refused');
+  ok(code(await rejects(INS, ['spend', 'out', 5, null, null, null, 'x', null, ''])) === '23514', 'an unknown kind is refused');
+
+  // the real writer, through the real read
+  const q = { query: (s, p) => client.query(s, p) };
+  await A.recordMovement(q, { kind: 'funding', amountMicro: 10_000_000, processorRef: 'ch_1' });
+  const pay = await A.recordMovement(q, { kind: 'payout', amountMicro: 3_000_000, builderId: 1, taskId: 1, processorRef: 'tr_1' });
+  await A.recordMovement(q, { kind: 'hold', amountMicro: 2_000_000, taskId: 1 });
+  const dup = await A.recordMovement(q, { kind: 'payout', amountMicro: 3_000_000, builderId: 1, taskId: 1, processorRef: 'tr_1' });
+  ok(pay.recorded && !dup.recorded, 'the same processor transfer books once; the retry is a no-op');
+  const v = await A.readAccount(q, { processor: { balanceMicro: async () => 7_000_000 } });
+  ok(v.recorded_balance_micro === 7_000_000 && v.held_micro === 2_000_000 && v.available_micro === 5_000_000, 'the view sums the record and shows what is held');
+  ok(v.drift_micro === 0 && v.movement_count === 3, 'no drift when the processor agrees');
+  const named = v.movements.find((m) => m.kind === 'payout');
+  ok(named.builder_name === 'Ada' && named.task_title === 'Build the thing', 'a payout row shows who was paid and for which task');
+
+  await A.recordMovement(q, { kind: 'adjustment', direction: 'in', amountMicro: 3_000_000, correctsId: pay.row.id, actorId: 2, note: 'payout returned by the processor' });
+  const after = await A.readAccount(q);
+  ok(after.recorded_balance_micro === 10_000_000, 'a correction is a new row that moves the balance');
+
+  ok(/append-only/.test((await rejects(`UPDATE ${T} SET amount_micro = 1`)).message), 'an UPDATE is refused');
+  ok(/append-only/.test((await rejects(`DELETE FROM ${T}`)).message), 'a DELETE is refused');
+
+  await client.query(`DROP TRIGGER economy_project_account_movements_no_rewrite ON ${T}`);
+  ok((await rejects(`UPDATE ${T} SET amount_micro = 1`)) === null, 'without the trigger the UPDATE lands (the probe)');
+  // probe: with the cause rule dropped the same payout lands, so the refusals above were real
+  await client.query(`ALTER TABLE ${T} DROP CONSTRAINT economy_project_account_cause_chk`);
+  ok((await rejects(INS, ['payout', 'out', 5, null, null, null, 'tr_probe', null, ''])) === null, 'without the cause rule the causeless payout lands (the probe)');
+  await client.query('ROLLBACK');
+  console.log(`project_account_db.mjs: ${pass} passed`);
+} finally {
+  await client.query('ROLLBACK').catch(() => {});
+  await client.query(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`).catch(() => {});
+  client.release();
+  await pgPool.end().catch(() => {});
+}