@bongos/core 1.24.23 → 1.24.25

package/tests/cash_outs_db.mjs

@@ -0,0 +1,205 @@
+// tests/cash_outs_db.mjs — task 1004911 (goal 1000092 N7). Real DB.
+//
+// Applies the REAL core_283 (approval log), core_284 + core_291 (payout gates), economy_003
+// (member accounts) and core_293 (cash-outs) migrations, then proves what Postgres itself
+// refuses: a cash-out approval by someone other than the person it pays, a cash-out citing
+// an owner's payout approval or another amount, two cash-outs on one approval, a try number
+// the processor has not earned, an arrival nobody sent, a second payout on one try, anything
+// after a cancellation or while a payout is out, and any rewrite. Then drives the real
+// requestCashOut / retryCashOut / cancelCashOut / recordProcessorOutcome against a stand-in
+// processor with test references only: held with no processor, sent once whatever the
+// presses, a timeout retried on the SAME key, a refusal or a bank return retried on a new
+// one, a gated person held with a hold that tells them, the minimum, one open at a time.
+//
+// Self-skips without a reachable Postgres.
+// Run:  DATABASE_URL=... node tests/cash_outs_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 C = require('../src/bongos/cash-outs.js');
+const approvals = require('../src/bongos/payout-approvals.js');
+const gates = require('../src/bongos/payout-gates.js');
+const { memberAccount } = require('../modules/economy/user-balances.js');
+const here = dirname(fileURLToPath(import.meta.url));
+const mig = (...p) => readFileSync(join(here, '..', ...p), 'utf8');
+
+const pgPool = new Pool({ connectionString: process.env.DATABASE_URL || undefined, max: 1 });
+let client;
+try { client = await pgPool.connect(); } catch (e) {
+  console.log(`cash_outs_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pgPool.end().catch(() => {});
+  process.exit(0);
+}
+const SCHEMA = `t1004911_${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 err = null;
+  try { await client.query(sql, params); } catch (e) { err = e; }
+  await client.query('ROLLBACK TO SAVEPOINT s');
+  ok(err !== null, m);
+};
+const refusal = async (fn) => { try { await fn(); } catch (e) { return e; } return null; };
+
+// 1 owner · 2 Ada (adult, cleared) · 3 Bo (no age recorded) · 4 a machine principal
+const actor = (id) => ({ id, rank: 'thetes', session_id: 900 + Number(id), session_source: 'web' });
+const deps = (extra = {}) => ({ pool: client, authority: approvals, account: { memberAccount }, ...extra });
+
+// A stand-in processor with test references. It is idempotent on the key, as the real one is.
+function fakeProcessor() {
+  const calls = [];
+  const made = new Map();
+  let next = null;
+  return {
+    calls,
+    failNext(err) { next = err; },
+    memberBalanceMicro: async () => 500 * 10_000 * 100, // $500.00
+    memberPayout: async (req) => {
+      calls.push(req);
+      if (next) { const e = next; next = null; throw e; }
+      if (!made.has(req.idempotencyKey)) made.set(req.idempotencyKey, `po_test_${made.size + 1}`);
+      return { ref: made.get(req.idempotencyKey) };
+    },
+  };
+}
+
+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, system_role text)');
+  await client.query('CREATE TABLE schema_migrations (version text PRIMARY KEY)');
+  for (const m of ['core_283_payout_approvals.sql', 'core_284_payout_gates.sql', 'core_291_payout_nda_tax.sql']) await client.query(mig('migrations', m));
+  await client.query(mig('modules', 'economy', 'migrations', 'economy_003_user_balances.sql'));
+  await client.query(mig('migrations', 'core_293_cash_outs.sql'));
+  await client.query(mig('migrations', 'core_293_cash_outs.sql'));
+  ok(true, 'core_293 applies twice (idempotent)');
+
+  await client.query("INSERT INTO builders (display_name, system_role) VALUES ('Owner', NULL), ('Ada', NULL), ('Bo', NULL), ('bot', 'agent')");
+  await client.query("INSERT INTO economy_member_accounts (builder_id, processor_account) VALUES (2, 'acct_test_ada'), (3, 'acct_test_bo')");
+  const o = { pool: client };
+  await gates.recordAge({ builderId: 2, tier: 'adult', basis: 'verified_by_person', recordedBy: 1 }, o);
+  await gates.recordScreening({ builderId: 2, result: 'clear', screenedBy: 'person:owner', validUntil: new Date(Date.now() + 86_400_000).toISOString(), recordedBy: 1 }, o);
+  await gates.recordNda({ builderId: 2, status: 'on_file', ndaVersion: 'beta-v1', reference: 'envelope-test-1', recordedBy: 1 }, o);
+  await gates.recordTaxDetails({ builderId: 2, status: 'collected', collectedBy: 'processor:test', reference: 'kyc-test-1', recordedBy: 1 }, o);
+  ok((await gates.gateRecipient(2, o)).ok === true, 'Ada passes the payout gates');
+  await client.query('BEGIN');
+
+  // ── what the database refuses ────────────────────────────────────────────
+  const APPROVE = `INSERT INTO payout_approvals (kind, actor_id, session_id, session_source, recipient_id, amount_cents, currency)
+                   VALUES ($1,$2,901,'web',$3,$4,'USD') RETURNING id`;
+  await refused(APPROVE, ['cashout_approved', 1, 2, 2000], 'a cash-out approval by anyone but the person it pays is refused');
+  await refused("INSERT INTO payout_approvals (kind, actor_id, session_id, session_source, recipient_id, amount_cents, currency) VALUES ('cashout_approved', 2, 1, 'cli', 2, 2000, 'USD')", [], 'a cash-out approval from a CLI session is refused');
+  await refused(APPROVE, ['cashout_approved', 4, 4, 2000], 'a machine principal cannot approve its own cash-out');
+  const ownerPay = (await client.query(APPROVE, ['payout_approved', 1, 2, 2000])).rows[0].id;
+  const mine = (await client.query(APPROVE, ['cashout_approved', 2, 2, 2000])).rows[0].id;
+  const CO = `INSERT INTO cash_outs (builder_id, approval_id, from_account, amount_cents, currency, instruction_id)
+              VALUES ($1,$2,'acct_test_ada',$3,'USD',$4) RETURNING id`;
+  await refused(CO, [2, ownerPay, 2000, 'press-owner-0001'], "an owner's payout approval cannot be spent as a cash-out");
+  await refused(CO, [2, mine, 2500, 'press-amount-001'], 'a cash-out for another amount than its approval is refused');
+  await refused(CO, [3, mine, 2000, 'press-other-0001'], "someone else's approval cannot be spent");
+  const co = (await client.query(CO, [2, mine, 2000, 'press-raw-00001'])).rows[0].id;
+  await refused(CO, [2, mine, 2000, 'press-raw-00002'], 'one approval pays one cash-out');
+  const TRY = 'INSERT INTO cash_out_attempts (cash_out_id, try_no, outcome, processor_ref, reason) VALUES ($1,$2,$3,$4,$5)';
+  await refused(TRY, [co, 2, 'sent', 'po_raw_1', null], 'a try number the processor has not earned is refused');
+  await refused(TRY, [co, 1, 'paid', 'po_raw_1', null], 'an arrival nobody sent is refused');
+  await refused(TRY, [co, 1, 'failed', null, null], 'a failure with no reason is refused');
+  await client.query(TRY, [co, 1, 'sent', 'po_raw_1', null]);
+  await refused(TRY, [co, 1, 'sent', 'po_raw_2', null], 'a second payout on one try is refused');
+  await refused(TRY, [co, 1, 'held', null, 'x'], 'nothing but arrival or return follows a sent payout');
+  await refused(TRY, [co, 1, 'cancelled', null, 'x'], 'a sent payout cannot be cancelled');
+  await refused(TRY, [co, 1, 'paid', 'po_raw_9', null], 'only the payout that was sent can arrive');
+  await client.query(TRY, [co, 1, 'returned', 'po_raw_1', 'account_closed']);
+  await client.query(TRY, [co, 2, 'cancelled', null, 'cancelled by the person']);
+  await refused(TRY, [co, 2, 'held', null, 'x'], 'nothing follows a cancellation');
+  await refused('UPDATE cash_outs SET amount_cents = 1 WHERE id = $1', [co], 'a cash-out cannot be edited');
+  await refused('DELETE FROM cash_out_attempts WHERE cash_out_id = $1', [co], 'an attempt cannot be deleted');
+  await refused('TRUNCATE cash_outs CASCADE', [], 'cash-outs cannot be truncated');
+
+  // ── the real flow ────────────────────────────────────────────────────────
+  let e = await refusal(() => C.requestCashOut({ builderId: '2', actor: actor(2), amountCents: 999, instructionId: 'press-min-00001' }, deps()));
+  ok(e && e.code === 'below_minimum' && e.details.minimum_cents === C.MIN_CASH_OUT_CENTS, 'below the minimum is refused, naming the minimum');
+  e = await refusal(() => C.requestCashOut({ builderId: '2', actor: { ...actor(2), session_source: 'cli' }, amountCents: 2000, instructionId: 'press-cli-00001' }, deps()));
+  ok(e && e.code === 'personal_session_required', 'a CLI session cannot take money out');
+  e = await refusal(() => C.requestCashOut({ builderId: '2', actor: actor(1), amountCents: 2000, instructionId: 'press-own-00001' }, deps()));
+  ok(e && e.code === 'personal_session_required', 'nobody can cash out for someone else');
+
+  let r = await C.requestCashOut({ builderId: '2', actor: actor(2), amountCents: 2500, instructionId: 'press-ada-00001' }, deps());
+  ok(r.status === 'held' && r.reason === 'no_processor' && r.cash_out.still_yours && r.cash_out.can_retry, 'with no processor it is recorded, held, and still yours');
+  const first = r.cash_out.id;
+  const again = await C.requestCashOut({ builderId: '2', actor: actor(2), amountCents: 2500, instructionId: 'press-ada-00001' }, deps());
+  ok(again.cash_out.id === first, 'pressing again with the same instruction is the same cash-out');
+  e = await refusal(() => C.requestCashOut({ builderId: '2', actor: actor(2), amountCents: 3000, instructionId: 'press-ada-00001' }, deps()));
+  ok(e && e.code === 'instruction_reused', 'the same instruction for another amount is refused');
+  e = await refusal(() => C.requestCashOut({ builderId: '2', actor: actor(2), amountCents: 2000, instructionId: 'press-ada-00002' }, deps()));
+  ok(e && e.code === 'cash_out_open' && e.details.cash_out_id === first, 'a second cash-out while one is open is refused, naming the open one');
+
+  const p = fakeProcessor();
+  e = await refusal(() => C.requestCashOut({ builderId: '2', actor: actor(2), amountCents: 2000, instructionId: 'press-ada-00003' }, deps({ processor: { ...p, memberBalanceMicro: async () => 1000 * 10_000 } })));
+  ok(e && e.code === 'over_balance', 'more than the processor says they have is refused');
+
+  r = await C.retryCashOut({ builderId: '2', cashOutId: first }, deps({ processor: p }));
+  ok(r.status === 'sent' && p.calls.length === 1 && p.calls[0].idempotencyKey === C.idempotencyKey(first, 1) && p.calls[0].account === 'acct_test_ada', 'retry sends from their own account with the try-1 key');
+  ok(p.calls[0].payTo === 'self' && p.calls[0].amountCents === 2500, 'it pays the person themself the approved amount');
+  r = await C.retryCashOut({ builderId: '2', cashOutId: first }, deps({ processor: p }));
+  ok(r.status === 'sent' && r.already && p.calls.length === 1, 'a second press on a sent cash-out sends nothing');
+  e = await refusal(() => C.cancelCashOut({ builderId: '2', cashOutId: first }, deps()));
+  ok(e && e.code === 'cannot_cancel', 'a sent cash-out cannot be cancelled');
+  e = await refusal(() => C.retryCashOut({ builderId: '3', cashOutId: first }, deps({ processor: p })));
+  ok(e && e.code === 'no_such_cash_out' && e.status === 404, "someone else's cash-out is not found");
+
+  ok((await C.recordProcessorOutcome({ processorRef: 'po_test_1', outcome: 'returned', reason: 'account_closed' }, o)).status === 'returned', 'the bank returns it');
+  ok((await C.recordProcessorOutcome({ processorRef: 'po_test_1', outcome: 'returned', reason: 'account_closed' }, o)).already, 'the same news twice is a no-op');
+  ok(await C.recordProcessorOutcome({ processorRef: 'po_never', outcome: 'paid' }, o) === null, 'news of a payout we never sent is ignored');
+  let list = await C.listMyCashOuts(2, deps({ processor: p }));
+  ok(list.cash_outs[0].status === 'returned' && list.cash_outs[0].still_yours && list.minimum_cents === C.MIN_CASH_OUT_CENTS, 'a returned cash-out stays on the list as still theirs');
+  r = await C.retryCashOut({ builderId: '2', cashOutId: first }, deps({ processor: p }));
+  ok(r.status === 'sent' && p.calls[1].idempotencyKey === C.idempotencyKey(first, 2), 'after a return the retry uses a NEW key');
+  await C.recordProcessorOutcome({ processorRef: r.processor_ref, outcome: 'paid' }, o);
+  list = await C.listMyCashOuts(2, deps({ processor: p }));
+  ok(list.cash_outs[0].status === 'paid' && !list.cash_outs[0].still_yours && list.cash_outs[0].tries === 2, 'it arrives on try 2');
+
+  // a timeout may have paid: the retry keeps the key, so the processor hands back the same payout
+  p.failNext(Object.assign(new Error('the processor did not answer in time'), { code: 'timeout' }));
+  r = await C.requestCashOut({ builderId: '2', actor: actor(2), amountCents: 1500, instructionId: 'press-ada-00004' }, deps({ processor: p }));
+  ok(r.status === 'failed' && r.cash_out.can_retry, 'a timeout is recorded as failed, open for retry');
+  const second = r.cash_out.id;
+  r = await C.retryCashOut({ builderId: '2', cashOutId: second }, deps({ processor: p }));
+  ok(r.status === 'sent' && p.calls[2].idempotencyKey === p.calls[3].idempotencyKey, 'the retry after a timeout uses the SAME key');
+  await C.recordProcessorOutcome({ processorRef: r.processor_ref, outcome: 'paid' }, o);
+
+  // a definite refusal made nothing: the next try gets a new key
+  p.failNext(Object.assign(new Error('insufficient funds'), { code: 'balance_insufficient', refused: true }));
+  r = await C.requestCashOut({ builderId: '2', actor: actor(2), amountCents: 1200, instructionId: 'press-ada-00005' }, deps({ processor: p }));
+  ok(r.status === 'refused' && /insufficient/.test(r.reason), 'a processor refusal is recorded with its reason');
+  const third = r.cash_out.id;
+  r = await C.cancelCashOut({ builderId: '2', cashOutId: third }, deps());
+  ok(r.status === 'cancelled' && !r.cash_out.can_retry, 'the person cancels a refused cash-out');
+  r = await C.retryCashOut({ builderId: '2', cashOutId: third }, deps({ processor: p }));
+  ok(r.status === 'cancelled' && r.already && p.calls.length === 5, 'a cancelled cash-out is never sent');
+
+  // a gated person: held, with a hold that tells them and what is theirs
+  r = await C.requestCashOut({ builderId: '3', actor: actor(3), amountCents: 2000, instructionId: 'press-bo-000001' }, deps({ processor: p }));
+  ok(r.status === 'held' && /^recipient_gated/.test(r.reason) && r.freeze_id && p.calls.length === 5, 'a person who fails the gates is held and nothing is sent');
+  const hold = await gates.readFreeze(r.freeze_id, o);
+  ok(hold.reason === 'age_unknown' && hold.owed_cents === 2000 && hold.notice_text, 'the hold tells them why, with the amount');
+  ok(r.cash_out.words === C.HELD_WORDS.recipient_gated, 'the cash-out says so in plain words');
+
+  const log = await approvals.listLog({ pool: client });
+  ok(log.filter((x) => x.kind === 'cashout_approved' && x.actor_id === '2' && x.recipient_id === '2').length === 4, "each of Ada's cash-outs is her own logged approval");
+
+  await client.query('ROLLBACK');
+  console.log(`\ncash_outs_db.mjs: ${pass} passed`);
+} catch (err) {
+  await client.query('ROLLBACK').catch(() => {});
+  console.error(err);
+  process.exitCode = 1;
+} finally {
+  await client.query(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`).catch(() => {});
+  client.release();
+  await pgPool.end();
+}

package/tests/funded_project_pays_proof_db.mjs

@@ -0,0 +1,181 @@
+// tests/funded_project_pays_proof_db.mjs — task 1003186 (goal 1000092 M07; criterion
+// money-cannot-outrun). Real DB: the integration lane's fully migrated database.
+//
+// THE PROOF, end to end, on the real schema and the real code paths — no stand-in tables:
+//   1. the project is funded (a `funding` movement, as the fund-project transfer books it);
+//   2. a builder claims a cash task through the real claimTask: the funding wall holds its pay;
+//   3. a second claim the balance cannot cover is refused with the reason and the shortfall;
+//   4. the first task ships through the real resolveClaim → confirmTask → shipTask, and its pay
+//      STAYS held until the builder is paid — the hole this proof found: the hold used to go at
+//      the ship, so the same money could be promised to another task before anyone was paid;
+//   5. the owner approves the payout (the real append-only approval log), the builder clears the
+//      real payout gates, and the first transfer fails: the debt is on record, owed, with why;
+//   6. the owner's outflow view shows the debt as owed-but-unpaid and the balance after it;
+//   7. pay is pressed again, twice at once: money leaves the account exactly once, and a third
+//      press sends nothing;
+//   8. the owner sees the payout, the per-builder total and nothing left owed;
+//   9. the balance is drained by one more claim, and the next is refused with its shortfall.
+//
+// WHAT IS NOT REAL. The processor. No payment-rail adapter exists yet (ADR 0397: Stripe
+// Connect, and only an adapter may name it; payout-approvals.js passes `processor = null`), so
+// step 5/7's transfers go to a test rail at the one port builder-payouts.js defines,
+// { transfer(req) → { ref } }, which remembers each idempotency key as a processor does. Every
+// other step is the code a live instance runs. No real money moves here.
+//
+// The tables it writes are append-only by design (the movements, debts, attempts, approvals),
+// so it cleans up nothing: its rows use ids unique to the run and it measures the account
+// relative to the balance it finds. Run it only against a throwaway database (the CI lane's).
+// Self-skips without a reachable Postgres.
+// Run:  DATABASE_URL=... node tests/funded_project_pays_proof_db.mjs
+import { createRequire } from 'node:module';
+import { strict as assert } from 'node:assert';
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+
+process.env.NODE_ENV = 'test';
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`funded_project_pays_proof_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const seams = require('../src/module-seams.js');
+const A = require('../modules/economy/project-account.js');
+if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../modules/economy/reward.js'));
+if (!seams.hasProvider('economy.account')) {
+  seams.registerProvider('economy.account', { recordMovement: A.recordMovement, lockAccount: A.lockAccount, releaseSettledHolds: A.releaseSettledHolds, readAvailable: A.readAvailable });
+}
+const db = require('../modules/lifecycle/db.js');
+const P = require('../modules/lifecycle/pay-terms.js');
+const settings = require('../src/bongos/project-settings.js');
+const approvals = require('../src/bongos/payout-approvals.js');
+const gates = require('../src/bongos/payout-gates.js');
+const payouts = require('../src/bongos/builder-payouts.js');
+const { readOutflow } = require('../modules/economy/outflow.js');
+
+const USD = 1_000_000;
+const RUN = Date.now() % 1_000_000;
+const BASE = 930_000_000 + RUN * 10;
+const OWNER = BASE, ADA = BASE + 1;
+const TASK_A = BASE, TASK_B = BASE + 1, TASK_C = BASE + 2;
+const VER = `ZZZ-M07-${RUN}`;
+const WALL_KEY = settings.SETTING_KEYS.FUNDING_WALL;
+const q = (sql, params) => pool.query(sql, params).then((r) => r.rows);
+let pass = 0;
+const ok = (c, m) => { assert.ok(c, m); pass++; console.log(`  ok - ${m}`); };
+const available = async () => (await A.readAvailable(pool)).available_micro;
+const claim = async (taskId) => {
+  try { return { claim: await db.claimTask({ taskId: String(taskId), builderId: String(ADA), worktreeName: `m07-${RUN}-${taskId}` }) }; } catch (e) { return { err: e }; }
+};
+const cash = (taskId, amount) => P.setPayTerms({ taskId, terms: [{ pay_type: 'cash', amount, unit: 'USD', note: null }], builderId: OWNER }, { db: pool });
+
+// The test rail: a processor that keeps one transfer per idempotency key, and declines the first.
+const rail = {
+  transfers: new Map(), calls: 0, declineNext: true,
+  async transfer(req) {
+    this.calls += 1;
+    if (this.declineNext) { this.declineNext = false; throw Object.assign(new Error('the bank declined the transfer'), { code: 'declined' }); }
+    if (!this.transfers.has(req.idempotencyKey)) this.transfers.set(req.idempotencyKey, { ref: `tr_m07_${RUN}`, amountCents: req.amountCents });
+    return { ref: this.transfers.get(req.idempotencyKey).ref };
+  },
+};
+
+const priorWall = await settings.getSetting(WALL_KEY);
+try {
+  await q(`INSERT INTO versions (id,name,status,track) VALUES ($1,'m07 proof','building','internal') ON CONFLICT (id) DO NOTHING`, [VER]);
+  await q(`INSERT INTO builders (id,github_id,github_login,display_name,rank) VALUES ($1,$2,$3,'M07 Owner','archon'), ($4,$5,$6,'Ada','archon')`,
+    [OWNER, `m07-o-${RUN}`, `m07-owner-${RUN}`, ADA, `m07-a-${RUN}`, `m07-ada-${RUN}`]);
+  for (const [id, title] of [[TASK_A, 'Build the paid thing'], [TASK_B, 'Build the second thing'], [TASK_C, 'Build the last thing']]) {
+    await q(`INSERT INTO tasks (id,version_id,title,status,credits_reward,kind,discipline) VALUES ($1,$2,$3,'ready',10,'feature','engineer')`, [id, VER, title]);
+  }
+  await cash(TASK_A, '100'); await cash(TASK_B, '80'); await cash(TASK_C, '40');
+  await settings.setSetting(WALL_KEY, 'hold_at_claim', OWNER);
+
+  // 1. fund the project so $150 is available (relative to whatever the database already holds)
+  const before = await available();
+  if (before < 150 * USD) await A.recordMovement(pool, { kind: 'funding', amountMicro: 150 * USD - before, processorRef: `ch_m07_${RUN}` });
+  if (before > 150 * USD) await A.recordMovement(pool, { kind: 'fee', amountMicro: before - 150 * USD, processorRef: `fee_m07_${RUN}`, note: 'M07 proof: start from $150' });
+  ok(await available() === 150 * USD, 'the project is funded: $150 available');
+  const out0 = await readOutflow(pool, { months: 1 });
+  const otherCommitted = out0.balance.available_micro - out0.balance.after_commitments_micro;
+
+  // 2. a funded claim passes and holds the task's pay
+  const a = await claim(TASK_A);
+  ok(a.claim && !a.err, `Ada claims the $100 task (${a.err ? a.err.code : 'claimed'})`);
+  ok(await available() === 50 * USD, 'its $100 pay is held: $50 left to promise');
+
+  // 3. an underfunded claim is refused, with the reason and the shortfall
+  const b = await claim(TASK_B);
+  ok(b.err && b.err.code === 'FUNDING_SHORTFALL', `the $80 task is refused (${b.err && b.err.code})`);
+  ok(/\$30\.00 short/.test(b.err.message), `and the refusal says by how much: "${b.err.message}"`);
+  ok((await q('SELECT status FROM tasks WHERE id = $1', [TASK_B]))[0].status === 'ready', 'the refused task stays in the queue, unclaimed');
+
+  // 4. the task ships through the real state machine, and its pay stays held until it is paid
+  await db.resolveClaim({ claimId: a.claim.id, builderId: String(ADA), outcome: 'shipped', notesMd: 'M07 proof', force: true });
+  await db.confirmTask({ taskId: String(TASK_A), builderId: String(OWNER) });
+  await db.shipTask({ taskId: String(TASK_A), builderId: String(ADA), landAssurance: { kind: 'proof', reason: 'test fixture: land proven' } });
+  ok((await q('SELECT status FROM tasks WHERE id = $1', [TASK_A]))[0].status === 'shipped', 'the task shipped');
+  ok(await available() === 50 * USD, 'shipped but not yet paid, its $100 is still held');
+  const b2 = await claim(TASK_B);
+  ok(b2.err && b2.err.code === 'FUNDING_SHORTFALL', 'so the $80 task is still refused: money owed to Ada cannot be promised again');
+
+  // 5. the owner approves; Ada clears the gates; the first transfer is declined
+  const person = { id: OWNER, rank: 'archon', session_id: 1, session_source: 'web' };
+  const approval = await approvals.insertEvent({ kind: 'payout_approved', actor: person, recipient_id: ADA, amount_cents: 10000, currency: 'USD' }, { pool });
+  const o = { pool };
+  await gates.recordAge({ builderId: ADA, tier: 'adult', basis: 'verified_by_person', recordedBy: OWNER }, o);
+  await gates.recordScreening({ builderId: ADA, result: 'clear', screenedBy: 'person:owner', validUntil: new Date(Date.now() + 86_400_000).toISOString(), recordedBy: OWNER }, o);
+  await gates.recordNda({ builderId: ADA, status: 'on_file', ndaVersion: 'beta-v1', reference: `m07-${RUN}`, recordedBy: OWNER }, o);
+  await gates.recordTaxDetails({ builderId: ADA, status: 'collected', collectedBy: 'person:owner', reference: `onb-m07-${RUN}`, recordedBy: OWNER }, o);
+  const press = () => payouts.payForTask({ approvalId: approval.id, taskId: String(TASK_A), actorId: String(OWNER) }, { pool, processor: rail });
+  const first = await press();
+  ok(first.status === 'failed' && /declined/.test(first.reason), `a declined transfer is recorded, not lost (${first.status}: ${first.reason})`);
+  ok(await available() === 50 * USD, 'nothing left the account, and the pay is still held');
+
+  // 6. the owner sees the debt as owed but unpaid, and the balance after it
+  const out1 = await readOutflow(pool, { months: 1 });
+  const owedRow = out1.committed.owed.find((r) => r.task_id === String(TASK_A));
+  ok(owedRow && owedRow.amount_micro === 100 * USD && /declined/.test(owedRow.last_reason), 'the owner sees $100 owed to Ada, and why it is unpaid');
+  ok(owedRow.held_micro === 100 * USD, 'already covered by the hold');
+  ok(out1.balance.after_commitments_micro === 50 * USD - otherCommitted, 'so the balance after commitments counts it once, not twice');
+
+  // 7. pressed again, twice at once: paid exactly once; a third press sends nothing
+  const [p1, p2] = await Promise.all([press(), press()]);
+  ok([p1, p2].every((p) => p.status === 'paid' && p.processor_ref === `tr_m07_${RUN}`), 'both presses answer paid, with one transfer reference');
+  ok(rail.transfers.size === 1, 'the rail made one transfer');
+  const third = await press();
+  ok(third.status === 'paid' && third.already === true, 'a third press finds it paid and sends nothing');
+  const moved = await q("SELECT amount_micro FROM economy_project_account_movements WHERE kind = 'payout' AND task_id = $1", [TASK_A]);
+  ok(moved.length === 1 && Number(moved[0].amount_micro) === 100 * USD, 'one $100 payout left the account');
+  ok(await available() === 50 * USD, 'the balance fell by $100 and the hold went with it: still $50 to promise');
+
+  // 8. the owner sees the burn, the per-builder total, nothing owed
+  const out2 = await readOutflow(pool, { months: 1 });
+  const ada = out2.by_builder.find((r) => r.builder_id === String(ADA));
+  ok(ada && ada.paid_micro === 100 * USD && ada.owed_micro === 0, 'Ada reads $100 paid, nothing owed');
+  ok(!out2.committed.owed.some((r) => r.task_id === String(TASK_A)), 'nothing is left owed for the task');
+  ok(out2.burn.months[0].payouts_micro - out0.burn.months[0].payouts_micro === 100 * USD, 'this month\'s burn carries the $100 payout');
+
+  // 9. drain the balance: one more claim fits, the next is refused with its shortfall
+  const c = await claim(TASK_C);
+  ok(c.claim && !c.err, 'the $40 task fits and is claimed');
+  ok(await available() === 10 * USD, '$10 left');
+  const b3 = await claim(TASK_B);
+  ok(b3.err && b3.err.code === 'FUNDING_SHORTFALL' && b3.err.shortfall_micro === 70 * USD, `the $80 task is refused, $70 short (${b3.err && b3.err.message})`);
+
+  console.log(`funded_project_pays_proof_db.mjs: ${pass} passed`);
+} catch (e) {
+  console.error('funded_project_pays_proof_db.mjs FAILED:', e.stack || e.message);
+  process.exitCode = 1;
+} finally {
+  if (priorWall) await settings.setSetting(WALL_KEY, priorWall.value, priorWall.updated_by).catch(() => {});
+  else await q('DELETE FROM project_settings WHERE key = $1', [WALL_KEY]).catch(() => {});
+  await q('UPDATE claims SET released_at = now() WHERE task_id = ANY($1::bigint[]) AND released_at IS NULL', [[TASK_A, TASK_B, TASK_C]]).catch(() => {});
+  await q("UPDATE tasks SET status = 'abandoned' WHERE id = ANY($1::bigint[]) AND status <> 'shipped'", [[TASK_B, TASK_C]]).catch(() => {});
+  await pool.end();
+  const { pool: corePool } = require('../src/bongos/pool.js');
+  await corePool.end().catch(() => {});
+}

package/tests/funding_wall.mjs

@@ -0,0 +1,205 @@
+// tests/funding_wall.mjs — the funding wall (task 1003185, goal 1000092 M06; ADR 0386).
+// Behaviour of modules/lifecycle/funding-wall.js, with the account port and the pay-terms
+// read stubbed:
+//   - a task that pays no cash is never walled, and the rule and account are not even read;
+//   - under hold_at_claim a short project refuses with the REASON and the SHORTFALL, and a
+//     funded one holds the task's cash pay; a batch is judged cumulatively;
+//   - the dry run never locks or holds; an unreadable price and a switched-off account
+//     refuse rather than guess;
+//   - refuse_at_completion lets the claim through and refuses the "done" instead;
+//     carry_on refuses nothing;
+//   - the three claim surfaces, the resolve path and the routes are wired to it.
+// The SQL is proven against real Postgres in tests/funding_wall_db.mjs.
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+
+const require = createRequire(import.meta.url);
+const W = require('../modules/lifecycle/funding-wall.js');
+const { cardFor } = require('../scripts/bongos/plain-cards.js');
+const read = (rel) => readFileSync(new URL(`../${rel}`, import.meta.url), 'utf8').replace(/\r\n/g, '\n');
+
+const USD = 1_000_000;
+const cash = (amount, unit = null) => ({ source: 'task', terms: [{ pay_type: 'cash', amount, unit }] });
+const terms = (byId) => async (ids) => new Map(ids.map((id) => [id, byId[id] || { source: 'none', terms: [] }]));
+const mode = (m) => async () => ({ mode: m, chosen: true });
+
+function fakeAccount({ balance = 0, held = 0 } = {}) {
+  const calls = [];
+  return {
+    calls,
+    async lockAccount() { calls.push('lock'); },
+    async releaseSettledHolds() { calls.push('release'); return []; },
+    async readAvailable(_db, opts = {}) { calls.push(['read', opts]); return { balance_micro: balance, held_micro: held, available_micro: balance - held }; },
+    async recordMovement(_db, m) { calls.push(['hold', m]); return { recorded: true, row: m }; },
+  };
+}
+const failNow = () => { throw new Error('must not be read'); };
+
+test('the rule parses three modes and nothing else', () => {
+  assert.deepEqual(W.FUNDING_WALL_MODES, ['hold_at_claim', 'refuse_at_completion', 'carry_on']);
+  assert.equal(W.DEFAULT_FUNDING_WALL, 'hold_at_claim', 'a project that sets nothing is protected at claim (ADR 0386)');
+  assert.equal(W.parseFundingWall(' Carry_On ').mode, 'carry_on');
+  assert.ok(W.parseFundingWall('halt').reason);
+  assert.ok(W.parseFundingWall('').reason);
+});
+
+test('only a plain dollar figure is read as a price; nothing is guessed', () => {
+  assert.equal(W.dollarsMicro('250', null), 250 * USD);
+  assert.equal(W.dollarsMicro('$1,250.50', null), 1250.5 * USD);
+  assert.equal(W.dollarsMicro('40', 'USD'), 40 * USD);
+  assert.equal(W.dollarsMicro('USD 40', null), 40 * USD);
+  assert.equal(W.dollarsMicro('0.05', 'dollars'), 50_000);
+  for (const [a, u] of [['250', 'EUR'], ['negotiable', null], ['about 200', null], ['1.234', null], ['-5', null], [null, null], ['12,34', null]]) {
+    assert.equal(W.dollarsMicro(a, u), null, `${a} ${u} is not a dollar figure`);
+  }
+  assert.equal(W.usd(1250.5 * USD), '$1,250.50');
+  assert.equal(W.usd(-3 * USD), '-$3.00');
+});
+
+test('a task whose pay is not cash is never walled', () => {
+  assert.deepEqual(W.cashPrice({ terms: [{ pay_type: 'credit_pool', amount: '5' }, { pay_type: 'self_managed', amount: '900' }] }), { cash: false });
+  assert.deepEqual(W.cashPrice({ terms: [{ pay_type: 'cash', amount: '10' }, { pay_type: 'cash', amount: '5', unit: 'usd' }] }), { cash: true, micro: 15 * USD });
+  assert.equal(W.cashPrice({ terms: [{ pay_type: 'cash', amount: 'a lot' }] }).unreadable, 'a lot');
+});
+
+test('no cash pay: the rule and the account are not even read', async () => {
+  const out = await W.fundingWallFailures({
+    client: {}, tasks: [{ id: 7 }], place: true,
+    deps: { readPayTerms: terms({}), resolveFundingWall: failNow, account: { lockAccount: failNow } },
+  });
+  assert.deepEqual(out, []);
+});
+
+test('hold at claim: a short project refuses, naming the price, the balance, what is held and the shortfall', async () => {
+  const account = fakeAccount({ balance: 180 * USD, held: 80 * USD });
+  const out = await W.fundingWallFailures({
+    client: {}, tasks: [{ id: 7 }], place: true,
+    deps: { readPayTerms: terms({ 7: cash('250') }), resolveFundingWall: mode('hold_at_claim'), account },
+  });
+  assert.equal(out.length, 1);
+  const r = out[0].refusal;
+  assert.equal(r.code, 'FUNDING_SHORTFALL');
+  assert.equal(r.price_micro, 250 * USD);
+  assert.equal(r.available_micro, 100 * USD);
+  assert.equal(r.shortfall_micro, 150 * USD);
+  for (const figure of ['$250.00', '$100.00', '$180.00', '$80.00', '$150.00 short']) assert.ok(r.message.includes(figure), `the message names ${figure}`);
+  assert.ok(r.hint, 'the refusal names the way forward');
+  assert.ok(!account.calls.some((c) => c[0] === 'hold'), 'nothing is held when the claim is refused');
+});
+
+test('hold at claim: a funded project takes the lock, lets go of settled holds, then holds the pay', async () => {
+  const account = fakeAccount({ balance: 300 * USD });
+  const out = await W.fundingWallFailures({
+    client: {}, tasks: [{ id: 7 }], place: true,
+    deps: { readPayTerms: terms({ 7: cash('250') }), resolveFundingWall: mode('hold_at_claim'), account },
+  });
+  assert.deepEqual(out, []);
+  assert.deepEqual(account.calls.slice(0, 2), ['lock', 'release'], 'the lock comes first, so two claims cannot read the same balance');
+  const hold = account.calls.find((c) => c[0] === 'hold')[1];
+  assert.equal(hold.kind, 'hold');
+  assert.equal(hold.amountMicro, 250 * USD);
+  assert.equal(hold.taskId, '7');
+});
+
+test('a batch is judged cumulatively, so it cannot over-commit one balance', async () => {
+  const account = fakeAccount({ balance: 100 * USD });
+  const out = await W.fundingWallFailures({
+    client: {}, tasks: [{ id: 1 }, { id: 2 }], place: true,
+    deps: { readPayTerms: terms({ 1: cash('60'), 2: cash('60') }), resolveFundingWall: mode('hold_at_claim'), account },
+  });
+  assert.equal(out.length, 1);
+  assert.equal(out[0].task_id, 2);
+  assert.equal(out[0].refusal.held_micro, 60 * USD, 'the second task sees the first one held');
+  assert.equal(out[0].refusal.shortfall_micro, 20 * USD);
+  assert.ok(!account.calls.some((c) => c[0] === 'hold'), 'a refused batch holds nothing');
+});
+
+test('the dry run reads only: no lock, no release, no hold', async () => {
+  const account = fakeAccount({ balance: 300 * USD });
+  await W.fundingWallFailures({
+    client: {}, tasks: [{ id: 7 }],
+    deps: { readPayTerms: terms({ 7: cash('250') }), resolveFundingWall: mode('hold_at_claim'), account },
+  });
+  assert.deepEqual(account.calls.map((c) => (Array.isArray(c) ? c[0] : c)), ['read']);
+});
+
+test('an unreadable price and a switched-off account refuse rather than guess', async () => {
+  const unreadable = await W.fundingWallFailures({
+    client: {}, tasks: [{ id: 7 }], place: true,
+    deps: { readPayTerms: terms({ 7: cash('negotiable') }), resolveFundingWall: mode('hold_at_claim'), account: fakeAccount({ balance: 1e12 }) },
+  });
+  assert.equal(unreadable[0].refusal.code, 'FUNDING_PRICE_UNREADABLE');
+  assert.ok(unreadable[0].refusal.message.includes('"negotiable"'), 'it says what it read');
+  const noAccount = await W.fundingWallFailures({
+    client: {}, tasks: [{ id: 7 }], place: true,
+    deps: { readPayTerms: terms({ 7: cash('5') }), resolveFundingWall: mode('hold_at_claim'), account: null },
+  });
+  assert.equal(noAccount[0].refusal.code, 'FUNDING_NO_ACCOUNT');
+});
+
+test('refuse at completion and carry on let the claim through and hold nothing', async () => {
+  for (const m of ['refuse_at_completion', 'carry_on']) {
+    const account = fakeAccount({ balance: 0 });
+    const out = await W.fundingWallFailures({
+      client: {}, tasks: [{ id: 7 }], place: true,
+      deps: { readPayTerms: terms({ 7: cash('250') }), resolveFundingWall: mode(m), account },
+    });
+    assert.deepEqual(out, [], `${m} never refuses a claim`);
+    assert.deepEqual(account.calls, [], `${m} never touches the account at claim`);
+  }
+});
+
+test('refuse at completion: declaring a short task done is refused with the shortfall; its own hold counts for it', async () => {
+  const account = fakeAccount({ balance: 100 * USD });
+  const deps = { readPayTerms: terms({ 7: cash('250') }), resolveFundingWall: mode('refuse_at_completion'), account };
+  await assert.rejects(W.fundingWallOnResolve({}, 7, 'shipped', deps), (e) => {
+    assert.equal(e.code, 'FUNDING_SHORTFALL_AT_COMPLETION');
+    assert.equal(e.shortfall_micro, 150 * USD);
+    assert.ok(e.message.includes('marked done'));
+    return true;
+  });
+  assert.deepEqual(account.calls.find((c) => c[0] === 'read')[1], { exceptTaskId: 7 });
+  await W.fundingWallOnResolve({}, 7, 'shipped', { ...deps, account: fakeAccount({ balance: 250 * USD }) });
+});
+
+test('at completion, the other rules refuse nothing; a let-go task releases its hold', async () => {
+  for (const m of ['hold_at_claim', 'carry_on']) {
+    await W.fundingWallOnResolve({}, 7, 'shipped', { readPayTerms: terms({ 7: cash('250') }), resolveFundingWall: mode(m), account: fakeAccount() });
+  }
+  const account = fakeAccount();
+  await W.fundingWallOnResolve({}, 7, 'abandoned', { readPayTerms: failNow, resolveFundingWall: failNow, account });
+  assert.deepEqual(account.calls, ['release']);
+  await W.fundingWallOnResolve({}, 7, 'abandoned', { account: null }); // no account: nothing to release, no throw
+});
+
+test('the rule is read from the project setting; a bad or unreadable value falls to the protective default', async () => {
+  assert.equal((await W.resolveFundingWall({ getSetting: async () => ({ value: 'carry_on' }) })).mode, 'carry_on');
+  const bad = await W.resolveFundingWall({ getSetting: async () => ({ value: 'never' }) });
+  assert.equal(bad.mode, 'hold_at_claim');
+  assert.ok(bad.invalid && bad.invalid.raw === 'never');
+  assert.equal((await W.resolveFundingWall({ getSetting: async () => { throw new Error('db down'); } })).mode, 'hold_at_claim');
+  const none = await W.resolveFundingWall({ getSetting: async () => null });
+  assert.equal(none.chosen, false);
+  assert.ok(/has not chosen/.test(W.describeFundingWall(none)));
+});
+
+test('wiring: all three claim surfaces, the resolve path, the routes and the cards', () => {
+  const claims = read('modules/lifecycle/db-claims.js');
+  assert.equal((claims.match(/await fundingWallFailures\(/g) || []).length, 3, 'claimTask, claimTasksBatch and validateClaimBatch each ask the wall');
+  assert.equal((claims.match(/fundingWallFailures\(\{ client, tasks: [^}]*place: true \}\)/g) || []).length, 2, 'both real claim paths place the hold');
+  assert.match(claims, /fundingWallFailures\(\{ client: pool, tasks: taskRows \}\)/, 'the dry run only reads');
+  assert.match(read('modules/lifecycle/db-ship.js'), /fundingWallOnResolve\(client, claim\.task_id, outcome\)/);
+  const routes = read('modules/lifecycle/routes/claims.js');
+  for (const code of ['FUNDING_SHORTFALL', 'FUNDING_SHORTFALL_AT_COMPLETION', 'FUNDING_PRICE_UNREADABLE', 'FUNDING_NO_ACCOUNT']) {
+    assert.match(routes, new RegExp(`'${code}' \\? 409`), `${code} answers 409`);
+    assert.ok(cardFor(code), `${code} has a plain card`);
+  }
+  const settings = read('modules/lifecycle/routes/project-settings.js');
+  assert.match(settings, /router\.patch\('\/project-settings\/funding-wall', api\.requireBuilder, api\.requirePermission\('project\.settings\.manage'\)/);
+  assert.match(settings, /insertAuditLog\(/, 'a change to the rule is audited');
+  assert.match(settings, /funding_wall: \{ mode: wall\.mode/, 'the rule rides beside a task\'s pay terms');
+  assert.match(read('modules/economy/routes/project-account.js'), /lockAccount, releaseSettledHolds, readAvailable[,} ]/);
+});