@bongos/core 1.24.16 → 1.24.18

package/src/bongos/builder-payouts.js

@@ -0,0 +1,264 @@
+'use strict';
+
+// src/bongos/builder-payouts.js — A BUILDER IS PAID FOR A TASK, EXACTLY ONCE, OUT OF THE
+// PROJECT'S ACCOUNT (task 1003183, goal 1000092 M04; ADR 0385 D1/D4, ADR 0397 D2/D5/D7).
+//
+// WHY. Two failures are worse than any other here: paying a builder twice, and a builder
+// who was never paid with no trace that anything was due. This file is built against both.
+//
+// THE ORDER IS THE DESIGN.
+//   1. The debt is written first, in its own committed step (builder_payouts_owed: one row
+//      per builder and task, citing the approval). From here on, whatever happens, the
+//      record says the money is owed.
+//   2. The authority is checked: a person's logged approval that covers exactly this
+//      recipient, amount and currency, and the payout gates (age, sanctions, holds), read
+//      again now because standing can change after the approval (core checkApproval).
+//      A no is recorded as a `held` attempt with the reason; the debt stays.
+//   3. Only then is the processor asked to transfer, under a per-debt lock, with an
+//      idempotency key derived from the debt's id. A success books the `sent` attempt and
+//      the project-account `payout` movement in ONE transaction (ADR 0185: money rides
+//      inside the transaction, never a best-effort listener). A failure, a refusal or a
+//      timeout books a `failed` attempt with the reason, and nothing is re-sent on its own
+//      (ADR 0397 D7): the next person who presses pay retries with the SAME key, so the
+//      processor answers with the transfer it already made rather than a second one.
+//
+// WHAT THIS IS NOT. It holds no money and never names a processor (ADR 0397 consequence:
+// only the adapter does). The processor is a port, { transfer(req) → { ref } }, handed in
+// by the caller. With none connected, every payout is recorded as owed and held with
+// `no_processor`, so nothing can move until the owner opens the account and the adapter
+// lands. Rule runs (checkRun) are not paid here yet: their lines carry no task, and a
+// payout without a task is refused by the project-account record.
+//
+// WHERE IT LIVES. Core, beside the approval log and the gates it must cite (a module may not
+// reach those). The project-account record is the economy module's, so the `payout` movement
+// is booked through its `economy.account` port, inside this file's transaction. With that
+// module off there is nowhere to book a payment, so nothing is sent (`no_account_record`).
+//
+// Amounts are integer cents, as the approval is; the movement is booked in micro-dollars.
+
+const seams = require('../module-seams');
+
+const LOCK_SPACE = 1003183;
+const TRANSFER_TIMEOUT_MS = 15_000;
+const MICRO_PER_CENT = 10_000;
+const CURRENCY = 'USD'; // the project account is kept in USD micro-dollars
+const REASON_MAX = 300;
+
+const isId = (v) => (typeof v === 'number' && Number.isSafeInteger(v) && v > 0) || (typeof v === 'string' && /^[1-9][0-9]{0,18}$/.test(v));
+
+class PayoutRefusal extends Error {
+  constructor(code, message, status = 400) { super(message); this.code = code; this.status = status; }
+}
+
+// Plain words for each reason a payout waits, shown to the owner beside the debt.
+const HELD_WORDS = Object.freeze({
+  no_processor: 'No payment processor is connected yet, so nothing was sent. The payment stays owed.',
+  no_account_record: 'The project account record is switched off, so the payment could not be booked and was not sent.',
+  currency_not_supported: 'The project account is kept in US dollars; this approval is in another currency.',
+  no_such_approval: 'The approval this payment cites could not be found.',
+  different_recipient: 'The approval is for a different person.',
+  different_amount: 'The approval is for a different amount or currency.',
+  recipient_gated: 'The person cannot be paid right now. They have been told why and can appeal.',
+  guardian_cosign_missing: 'The person is 16 or 17, and their guardian has not co-signed this payment yet.',
+});
+
+const clip = (s) => String(s || '').replace(/\s+/g, ' ').trim().slice(0, REASON_MAX) || 'unknown';
+const idempotencyKey = (owedId) => `bongos-payout-${owedId}`;
+
+// ── db half (pool injectable; tests hand in a stand-in) ─────────────────────
+
+function defaultPool() { return require('./pool').pool; }
+function defaultAuthority() { return require('./payout-approvals'); }
+function defaultAccount() { return seams.resolveOptional('economy.account'); }
+
+const OWED_COLS = 'id, builder_id, task_id, approval_id, amount_cents, currency, recorded_by, created_at';
+
+function shapeOwed(r) {
+  if (!r) return null;
+  return {
+    ...r,
+    id: String(r.id), builder_id: String(r.builder_id), task_id: String(r.task_id),
+    approval_id: String(r.approval_id), recorded_by: String(r.recorded_by), amount_cents: Number(r.amount_cents),
+  };
+}
+
+async function insertAttempt(db, owedId, { outcome, processorRef = null, reason = null, actorId = null }) {
+  const { rows } = await db.query(
+    `INSERT INTO builder_payout_attempts (owed_id, outcome, processor_ref, reason, actor_id)
+     VALUES ($1,$2,$3,$4,$5) RETURNING id, owed_id, outcome, processor_ref, reason, created_at`,
+    [owedId, outcome, processorRef, reason === null ? null : clip(reason), actorId]);
+  return rows[0];
+}
+
+async function sentAttempt(db, owedId) {
+  const { rows } = await db.query(
+    "SELECT id, processor_ref, created_at FROM builder_payout_attempts WHERE owed_id = $1 AND outcome = 'sent'", [owedId]);
+  return rows[0] || null;
+}
+
+// Step 1: the debt. Reads the approval for who and how much (never the caller's word),
+// then records the debt once. A second call for the same approval and task finds the row
+// already there; an approval already spent on another task, or a task already owed under
+// another approval, is refused.
+async function recordOwed(db, { approvalId, taskId, actorId }) {
+  const ap = await db.query(
+    'SELECT id, kind, recipient_id, amount_cents, currency FROM payout_approvals WHERE id = $1', [approvalId]);
+  const a = ap.rows[0];
+  if (!a || a.kind !== 'payout_approved') throw new PayoutRefusal('no_such_approval', 'There is no payout approval with that id.', 404);
+  const task = await db.query('SELECT id FROM tasks WHERE id = $1', [taskId]);
+  if (!task.rows[0]) throw new PayoutRefusal('no_such_task', 'There is no task with that id.', 404);
+
+  await db.query(
+    `INSERT INTO builder_payouts_owed (builder_id, task_id, approval_id, amount_cents, currency, recorded_by)
+     VALUES ($1,$2,$3,$4,$5,$6) ON CONFLICT DO NOTHING`,
+    [a.recipient_id, taskId, a.id, a.amount_cents, a.currency, actorId]);
+  const byApproval = shapeOwed((await db.query(`SELECT ${OWED_COLS} FROM builder_payouts_owed WHERE approval_id = $1`, [a.id])).rows[0]);
+  if (byApproval) {
+    if (byApproval.task_id !== String(taskId)) {
+      throw new PayoutRefusal('approval_already_used', `This approval already pays task ${byApproval.task_id}. One approval pays one task.`, 409);
+    }
+    return byApproval;
+  }
+  const byTask = shapeOwed((await db.query(
+    `SELECT ${OWED_COLS} FROM builder_payouts_owed WHERE builder_id = $1 AND task_id = $2`, [a.recipient_id, taskId])).rows[0]);
+  throw new PayoutRefusal('task_already_owed',
+    `This person is already owed for this task under approval ${byTask ? byTask.approval_id : 'another'}. A task is paid once.`, 409);
+}
+
+function withTimeout(promise, ms) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, rej) => { timer = setTimeout(() => rej(Object.assign(new Error('the processor did not answer in time'), { code: 'timeout' })), ms); }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+// A transaction on a checked-out client when the pool can give one; a stand-in that is
+// already a single connection runs the statements as they are (the payout-gates idiom).
+async function inTx(pool, fn) {
+  if (typeof pool.connect !== 'function' || typeof pool.release === 'function') return fn(pool);
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    const out = await fn(client);
+    await client.query('COMMIT');
+    return out;
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// Step 3: the send, under a lock on the debt so two presses at once cannot both send.
+async function send(pool, owed, { processor, account, payTo, actorId, timeoutMs }) {
+  return inTx(pool, async (db) => {
+    await db.query('SELECT pg_advisory_xact_lock($1::int, hashtext($2::text))', [LOCK_SPACE, owed.id]);
+    const already = await sentAttempt(db, owed.id);
+    if (already) return { status: 'paid', already: true, processor_ref: already.processor_ref };
+    let ref;
+    try {
+      const out = await withTimeout(Promise.resolve(processor.transfer({
+        idempotencyKey: idempotencyKey(owed.id),
+        amountCents: owed.amount_cents,
+        currency: owed.currency,
+        builderId: owed.builder_id,
+        taskId: owed.task_id,
+        payTo,
+      })), timeoutMs);
+      ref = out && typeof out.ref === 'string' && out.ref.trim() ? out.ref.trim() : null;
+      if (!ref) throw Object.assign(new Error('the processor gave no transfer reference'), { code: 'no_reference' });
+    } catch (err) {
+      const reason = clip(`${err && err.code ? err.code + ': ' : ''}${err && err.message ? err.message : 'transfer failed'}`);
+      await insertAttempt(db, owed.id, { outcome: 'failed', reason, actorId });
+      return { status: 'failed', reason };
+    }
+    // If the database fails from here the transfer happened and nothing says so; the
+    // transaction rolls back, the debt still reads owed, and the next press sends the same
+    // idempotency key, so the processor hands back this transfer and it is booked then.
+    await insertAttempt(db, owed.id, { outcome: 'sent', processorRef: ref, actorId });
+    await account.recordMovement(db, {
+      kind: 'payout', amountMicro: owed.amount_cents * MICRO_PER_CENT,
+      builderId: owed.builder_id, taskId: owed.task_id, processorRef: ref,
+    });
+    return { status: 'paid', already: false, processor_ref: ref };
+  });
+}
+
+// payForTask({ approvalId, taskId, actorId }, { pool, authority, account, processor }) →
+//   { owed, status: 'paid' | 'held' | 'failed', reason?, words?, processor_ref?, already? }
+// Throws PayoutRefusal only BEFORE a debt exists (bad ids, no such approval or task, an
+// approval or task already spoken for). Once the debt is recorded every outcome is a
+// returned status, and the debt stays until a `sent` attempt settles it. authority and
+// account default to core's approval log and the `economy.account` port; tests inject both.
+async function payForTask({ approvalId, taskId, actorId }, {
+  pool = defaultPool(), authority = defaultAuthority(), account = defaultAccount(),
+  processor = null, timeoutMs = TRANSFER_TIMEOUT_MS,
+} = {}) {
+  if (!isId(approvalId)) throw new PayoutRefusal('bad_approval_id', 'approval_id must be a number.');
+  if (!isId(taskId)) throw new PayoutRefusal('bad_task_id', 'task_id must be a number.');
+  if (!isId(actorId)) throw new PayoutRefusal('no_actor', 'A payout is pressed by a signed-in person.', 403);
+  if (!authority || typeof authority.checkApproval !== 'function') throw new Error('payForTask: no payout authority');
+
+  const owed = await recordOwed(pool, { approvalId, taskId, actorId });
+  const paid = await sentAttempt(pool, owed.id);
+  if (paid) return { owed, status: 'paid', already: true, processor_ref: paid.processor_ref };
+
+  const held = async (reason) => {
+    await insertAttempt(pool, owed.id, { outcome: 'held', reason, actorId });
+    return { owed, status: 'held', reason, words: HELD_WORDS[reason] || null };
+  };
+  if (owed.currency !== CURRENCY) return held('currency_not_supported');
+
+  const auth = await authority.checkApproval({
+    id: owed.approval_id, kind: 'payout_approved', recipientId: owed.builder_id,
+    amountCents: owed.amount_cents, currency: owed.currency,
+  }, { pool });
+  if (!auth || !auth.ok) return held((auth && auth.reason) || 'no_such_approval');
+
+  if (!account || typeof account.recordMovement !== 'function') return held('no_account_record');
+  if (!processor || typeof processor.transfer !== 'function') return held('no_processor');
+
+  const out = await send(pool, owed, { processor, account, payTo: auth.pay_to, actorId, timeoutMs });
+  return { owed, ...out };
+}
+
+// listPayouts(db, { limit, offset }) — every debt with where it stands, newest first. A
+// debt is `paid` once it has a sent attempt; otherwise `owed`, with its latest try.
+async function listPayouts(db = defaultPool(), { limit = 50, offset = 0 } = {}) {
+  const lim = Math.min(Math.max(parseInt(limit, 10) || 50, 1), 200);
+  const off = Math.max(parseInt(offset, 10) || 0, 0);
+  const [rows, count] = await Promise.all([
+    db.query(
+      `SELECT o.id, o.builder_id, b.display_name AS builder_name, o.task_id, t.title AS task_title,
+              o.approval_id, o.amount_cents, o.currency, o.created_at,
+              s.processor_ref AS sent_ref, s.created_at AS paid_at,
+              l.outcome AS last_outcome, l.reason AS last_reason, l.created_at AS last_try_at
+         FROM builder_payouts_owed o
+         LEFT JOIN builders b ON b.id = o.builder_id
+         LEFT JOIN tasks t ON t.id = o.task_id
+         LEFT JOIN builder_payout_attempts s ON s.owed_id = o.id AND s.outcome = 'sent'
+         LEFT JOIN LATERAL (
+           SELECT outcome, reason, created_at FROM builder_payout_attempts a
+            WHERE a.owed_id = o.id ORDER BY a.id DESC LIMIT 1) l ON true
+        ORDER BY o.created_at DESC, o.id DESC
+        LIMIT $1 OFFSET $2`, [lim, off]),
+    db.query('SELECT count(*) AS n FROM builder_payouts_owed'),
+  ]);
+  return {
+    total: Number(count.rows[0].n),
+    payouts: rows.rows.map((r) => ({
+      id: String(r.id), builder_id: String(r.builder_id), builder_name: r.builder_name,
+      task_id: String(r.task_id), task_title: r.task_title, approval_id: String(r.approval_id),
+      amount_cents: Number(r.amount_cents), currency: r.currency, created_at: r.created_at,
+      status: r.sent_ref ? 'paid' : 'owed',
+      processor_ref: r.sent_ref || null, paid_at: r.paid_at || null,
+      last_try: r.last_outcome ? { outcome: r.last_outcome, reason: r.last_reason, at: r.last_try_at, words: HELD_WORDS[r.last_reason] || null } : null,
+    })),
+  };
+}
+
+// One object, as payout-gates.js does: the router reaches it through an injectable default.
+const api = { PayoutRefusal, idempotencyKey, payForTask, listPayouts };
+module.exports = api;

package/src/bongos/routes/payout-approvals.js

@@ -26,7 +26,8 @@
 
 const express = require('express');
 const auth = require('../auth');
-const { validateOrRespond } = require('./_helpers');
+const { validateOrRespond, parsePagination, pageMeta } = require('./_helpers');
+const builderPayouts = require('../builder-payouts');
 const log = require('../logger').logger.child({ src: 'payout-approvals' });
 
 const PERSONAL_REFUSALS = {
@@ -57,6 +58,10 @@ function cleanDoc(raw) {
 module.exports = function buildPayoutApprovalsRouter({
   store = require('../payout-approvals'),
   gates = require('../payout-gates'),
+  payouts = builderPayouts,
+  // The processor adapter (ADR 0397: the only code that may name the rail) does not exist
+  // yet, so nothing is sent: every builder payout is recorded as owed and held.
+  processor = null,
   requireBuilder = auth.requireBuilder,
   requirePermission = auth.requirePermission,
 } = {}) {
@@ -308,5 +313,40 @@ module.exports = function buildPayoutApprovalsRouter({
   // POST /api/bongos/payouts/contracts — sign ONE contract. Body as for grants.
   router.post('/payouts/contracts', requireBuilder, requirePermission('payout.approve'), (req, res) => signDoc(req, res, '/payouts/contracts', 'contract_signed'));
 
+  // GET /api/bongos/payouts/builder-payouts — every builder payout and where it stands
+  // (task 1003183, M04): paid, or owed with its latest try and the reason in words.
+  router.get('/payouts/builder-payouts', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    try {
+      const { limit, offset } = parsePagination(req, { defaultLimit: 50, maxLimit: 200 });
+      const out = await payouts.listPayouts(undefined, { limit, offset });
+      res.set('Cache-Control', 'no-store');
+      res.json({ payouts: out.payouts, page: pageMeta(limit, offset, out.total) });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'GET /payouts/builder-payouts failed');
+      if (!res.headersSent) res.fail('payouts_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /api/bongos/payouts/builder-payouts — send ONE approved payout for ONE task
+  // (task 1003183, M04). Body: { approval_id, task_id }. The person and the amount come
+  // from the approval, never the body. A person presses it on the website: the approval
+  // says what may be paid, and this is the person sending it (Art. I). Pressing again is
+  // safe: a paid task answers paid, an owed one retries with the same processor key.
+  router.post('/payouts/builder-payouts', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { approval_id: { required: true }, task_id: { required: true } })) return;
+    const body = req.body || {};
+    try {
+      const out = await payouts.payForTask({ approvalId: body.approval_id, taskId: body.task_id, actorId: actor.id }, { processor });
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) {
+      if (err instanceof payouts.PayoutRefusal) return res.fail(err.code, { status: err.status, message: err.message });
+      log.error({ err: err && err.message }, 'POST /payouts/builder-payouts failed');
+      if (!res.headersSent) res.fail('payout_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   return router;
 };

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.24.16'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.24.18'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/ai_studio_generate.mjs

@@ -246,6 +246,8 @@ test('which key runs: theirs whenever they have one, unless they ask for ours',
   assert.deepEqual(K.chooseKey(['openrouter'], 'ours'), { source: 'ours' });
   assert.deepEqual(K.chooseKey([], 'own'), { error: 'no_own_key' });
   assert.deepEqual(K.chooseKey(['openrouter'], 'free'), { error: 'bad_pay_with' });
+  assert.deepEqual(K.chooseKey(['gemini', 'openrouter'], 'gemini'), { source: 'own', provider: 'gemini' }, 'a named key wins over the default');
+  assert.deepEqual(K.chooseKey(['openrouter'], 'gemini'), { error: 'no_own_key' });
 });
 
 test('on their own key no money moves: one own_key row, price 0, cost noted', async () => {

package/tests/builder_payouts.mjs

@@ -0,0 +1,295 @@
+// tests/builder_payouts.mjs — a builder is paid for a task, exactly once (task 1003183,
+// goal 1000092 M04; ADR 0385 D4, ADR 0397 D7). Behaviour of src/bongos/builder-payouts.js:
+//   - the debt is recorded before anything is sent, and stays when nothing is sent;
+//   - nothing is sent without the approval and the gates saying yes, or with no processor;
+//   - pressing pay again, or twice at once, sends once and books one movement;
+//   - a failed or timed-out transfer leaves the debt owed, and the retry reuses the same
+//     idempotency key so the processor cannot make a second transfer;
+//   - an approval pays one task, and a task is paid once.
+// The stand-in below enforces the same unique rules the migration does, and holds the
+// advisory lock until COMMIT, so the concurrency case is real. The SQL itself is proven
+// against Postgres in tests/builder_payouts_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 P = require('../src/bongos/builder-payouts.js');
+const ACCOUNT = require('../modules/economy/project-account.js');
+
+function fakeDb({ approvals = [], tasks = [1, 2] } = {}) {
+  const s = { owed: [], attempts: [], movements: [], approvals, tasks: tasks.map(String) };
+  let lockTail = Promise.resolve();
+  const unique = (msg) => Object.assign(new Error(msg), { code: '23505' });
+
+  async function run(sql, p = []) {
+    const q = sql.replace(/\s+/g, ' ').trim();
+    if (/FROM payout_approvals WHERE id = \$1/.test(q)) return { rows: s.approvals.filter((a) => String(a.id) === String(p[0])) };
+    if (/^SELECT id FROM tasks/.test(q)) return { rows: s.tasks.includes(String(p[0])) ? [{ id: p[0] }] : [] };
+    if (/^INSERT INTO builder_payouts_owed/.test(q)) {
+      const [builder_id, task_id, approval_id, amount_cents, currency, recorded_by] = p.map((v) => v);
+      const clash = s.owed.some((o) => String(o.approval_id) === String(approval_id)
+        || (String(o.builder_id) === String(builder_id) && String(o.task_id) === String(task_id)));
+      if (!clash) s.owed.push({ id: s.owed.length + 1, builder_id, task_id, approval_id, amount_cents, currency, recorded_by, created_at: new Date() });
+      return { rows: [] };
+    }
+    if (/FROM builder_payouts_owed WHERE approval_id = \$1/.test(q)) return { rows: s.owed.filter((o) => String(o.approval_id) === String(p[0])) };
+    if (/FROM builder_payouts_owed WHERE builder_id = \$1 AND task_id = \$2/.test(q)) {
+      return { rows: s.owed.filter((o) => String(o.builder_id) === String(p[0]) && String(o.task_id) === String(p[1])) };
+    }
+    if (/^INSERT INTO builder_payout_attempts/.test(q)) {
+      const [owed_id, outcome, processor_ref, reason] = p;
+      if (outcome === 'sent' && s.attempts.some((a) => String(a.owed_id) === String(owed_id) && a.outcome === 'sent')) throw unique('one sent per debt');
+      const row = { id: s.attempts.length + 1, owed_id, outcome, processor_ref, reason, created_at: new Date() };
+      s.attempts.push(row);
+      return { rows: [row] };
+    }
+    if (/FROM builder_payout_attempts WHERE owed_id = \$1 AND outcome = 'sent'/.test(q)) {
+      return { rows: s.attempts.filter((a) => String(a.owed_id) === String(p[0]) && a.outcome === 'sent') };
+    }
+    if (/^INSERT INTO economy_project_account_movements/.test(q)) {
+      const [kind, direction, amount_micro, builder_id, task_id, , processor_ref] = p;
+      if (s.movements.some((m) => m.kind === kind && m.processor_ref === processor_ref)) return { rows: [] };
+      const row = { id: s.movements.length + 1, kind, direction, amount_micro, builder_id, task_id, processor_ref };
+      s.movements.push(row);
+      return { rows: [row] };
+    }
+    if (/FROM economy_project_account_movements WHERE kind = \$1/.test(q)) return { rows: s.movements.filter((m) => m.kind === p[0] && m.processor_ref === p[1]) };
+    throw new Error(`fakeDb: unexpected SQL: ${q}`);
+  }
+
+  const pool = {
+    s,
+    query: run,
+    async connect() {
+      let release = null;
+      const client = {
+        async query(sql, p) {
+          const q = sql.trim();
+          if (q === 'BEGIN') return { rows: [] };
+          if (q === 'COMMIT' || q === 'ROLLBACK') { if (release) { release(); release = null; } return { rows: [] }; }
+          if (/pg_advisory_xact_lock/.test(q)) {
+            const prev = lockTail;
+            let done;
+            lockTail = new Promise((r) => { done = r; });
+            await prev;
+            release = done;
+            return { rows: [] };
+          }
+          return run(sql, p);
+        },
+        release() {},
+      };
+      return client;
+    },
+  };
+  return pool;
+}
+
+const APPROVAL = { id: 50, kind: 'payout_approved', recipient_id: 7, amount_cents: 12_500, currency: 'USD' };
+const allow = { checkApproval: async () => ({ ok: true, pay_to: 'self' }), personalSession: () => ({ ok: true }) };
+
+function fakeProcessor(behaviour = () => ({ ref: 'tr_1' })) {
+  const calls = [];
+  return { calls, async transfer(req) { calls.push(req); return behaviour(req, calls.length); } };
+}
+
+const press = (pool, extra = {}) => P.payForTask({ approvalId: 50, taskId: 1, actorId: 1 }, { pool, account: ACCOUNT, authority: allow, ...extra });
+
+test('with no processor connected, the debt is recorded and held, and nothing moves', async () => {
+  const pool = fakeDb({ approvals: [APPROVAL] });
+  const out = await press(pool);
+  assert.equal(out.status, 'held');
+  assert.equal(out.reason, 'no_processor');
+  assert.ok(out.words, 'the owner is told why in plain words');
+  assert.equal(pool.s.owed.length, 1);
+  assert.equal(pool.s.owed[0].amount_cents, 12_500, 'the amount is the approval\'s, never the caller\'s');
+  assert.equal(pool.s.movements.length, 0);
+});
+
+test('an approved payout is sent once, booked as a payout movement in micro-dollars', async () => {
+  const pool = fakeDb({ approvals: [APPROVAL] });
+  const proc = fakeProcessor();
+  const out = await press(pool, { processor: proc });
+  assert.equal(out.status, 'paid');
+  assert.equal(out.processor_ref, 'tr_1');
+  assert.equal(proc.calls.length, 1);
+  assert.equal(proc.calls[0].idempotencyKey, P.idempotencyKey(pool.s.owed[0].id));
+  assert.equal(proc.calls[0].amountCents, 12_500);
+  assert.equal(pool.s.movements.length, 1);
+  assert.equal(pool.s.movements[0].kind, 'payout');
+  assert.equal(pool.s.movements[0].amount_micro, 125_000_000);
+  assert.equal(String(pool.s.movements[0].task_id), '1');
+});
+
+test('pressing pay again answers paid and sends nothing', async () => {
+  const pool = fakeDb({ approvals: [APPROVAL] });
+  const proc = fakeProcessor();
+  await press(pool, { processor: proc });
+  const again = await press(pool, { processor: proc });
+  assert.equal(again.status, 'paid');
+  assert.equal(again.already, true);
+  assert.equal(proc.calls.length, 1);
+  assert.equal(pool.s.movements.length, 1);
+});
+
+test('two presses at the same moment send once', async () => {
+  const pool = fakeDb({ approvals: [APPROVAL] });
+  const proc = fakeProcessor(async () => { await new Promise((r) => setTimeout(r, 20)); return { ref: 'tr_1' }; });
+  const [a, b] = await Promise.all([press(pool, { processor: proc }), press(pool, { processor: proc })]);
+  assert.deepEqual([a.status, b.status], ['paid', 'paid']);
+  assert.equal(proc.calls.length, 1, 'the second press waited on the lock and found it paid');
+  assert.equal(pool.s.attempts.filter((x) => x.outcome === 'sent').length, 1);
+  assert.equal(pool.s.movements.length, 1);
+});
+
+test('a failed transfer leaves the debt owed, and the retry reuses the same key', async () => {
+  const pool = fakeDb({ approvals: [APPROVAL] });
+  const proc = fakeProcessor((req, n) => { if (n === 1) throw Object.assign(new Error('card declined'), { code: 'declined' }); return { ref: 'tr_9' }; });
+  const first = await press(pool, { processor: proc });
+  assert.equal(first.status, 'failed');
+  assert.match(first.reason, /declined/);
+  assert.equal(pool.s.movements.length, 0);
+  assert.equal(pool.s.owed.length, 1, 'the debt is still on record');
+  const second = await press(pool, { processor: proc });
+  assert.equal(second.status, 'paid');
+  assert.equal(proc.calls[0].idempotencyKey, proc.calls[1].idempotencyKey);
+  assert.equal(pool.s.movements.length, 1);
+});
+
+test('a processor that never answers is recorded as a failed try, not a payment', async () => {
+  const pool = fakeDb({ approvals: [APPROVAL] });
+  const proc = fakeProcessor(() => new Promise(() => {}));
+  const out = await press(pool, { processor: proc, timeoutMs: 20 });
+  assert.equal(out.status, 'failed');
+  assert.match(out.reason, /timeout/);
+  assert.equal(pool.s.movements.length, 0);
+});
+
+test('a transfer with no reference is not booked as paid', async () => {
+  const pool = fakeDb({ approvals: [APPROVAL] });
+  const out = await press(pool, { processor: fakeProcessor(() => ({})) });
+  assert.equal(out.status, 'failed');
+  assert.equal(pool.s.attempts.filter((x) => x.outcome === 'sent').length, 0);
+});
+
+test('when the approval or the gates say no, the debt is held and the processor is never asked', async () => {
+  const pool = fakeDb({ approvals: [APPROVAL] });
+  const proc = fakeProcessor();
+  const gated = { checkApproval: async () => ({ ok: false, reason: 'recipient_gated' }) };
+  const out = await press(pool, { processor: proc, authority: gated });
+  assert.equal(out.status, 'held');
+  assert.equal(out.reason, 'recipient_gated');
+  assert.equal(proc.calls.length, 0);
+  assert.equal(pool.s.owed.length, 1);
+});
+
+test('the authority is asked about exactly the approval, person, amount and currency on record', async () => {
+  const pool = fakeDb({ approvals: [APPROVAL] });
+  let asked = null;
+  const spy = { checkApproval: async (q) => { asked = q; return { ok: true, pay_to: 'self' }; } };
+  await press(pool, { authority: spy });
+  assert.deepEqual(
+    { id: asked.id, kind: asked.kind, recipientId: asked.recipientId, amountCents: asked.amountCents, currency: asked.currency },
+    { id: '50', kind: 'payout_approved', recipientId: '7', amountCents: 12_500, currency: 'USD' });
+});
+
+test('a non-dollar approval is held, never converted', async () => {
+  const pool = fakeDb({ approvals: [{ ...APPROVAL, currency: 'EUR' }] });
+  const proc = fakeProcessor();
+  const out = await press(pool, { processor: proc });
+  assert.equal(out.reason, 'currency_not_supported');
+  assert.equal(proc.calls.length, 0);
+});
+
+test('one approval pays one task, and one task is paid once', async () => {
+  const pool = fakeDb({ approvals: [APPROVAL, { ...APPROVAL, id: 51 }] });
+  await press(pool);
+  await assert.rejects(() => P.payForTask({ approvalId: 50, taskId: 2, actorId: 1 }, { pool, account: ACCOUNT, authority: allow }),
+    (e) => e.code === 'approval_already_used' && e.status === 409);
+  await assert.rejects(() => P.payForTask({ approvalId: 51, taskId: 1, actorId: 1 }, { pool, account: ACCOUNT, authority: allow }),
+    (e) => e.code === 'task_already_owed' && e.status === 409);
+  assert.equal(pool.s.owed.length, 1);
+});
+
+test('a missing approval, a missing task or a bad id records nothing', async () => {
+  const pool = fakeDb({ approvals: [APPROVAL, { id: 60, kind: 'grant_signed', recipient_id: 7 }] });
+  const tries = [
+    [{ approvalId: 99, taskId: 1, actorId: 1 }, 'no_such_approval'],
+    [{ approvalId: 60, taskId: 1, actorId: 1 }, 'no_such_approval'],
+    [{ approvalId: 50, taskId: 9, actorId: 1 }, 'no_such_task'],
+    [{ approvalId: 'x', taskId: 1, actorId: 1 }, 'bad_approval_id'],
+    [{ approvalId: 50, taskId: 1, actorId: null }, 'no_actor'],
+  ];
+  for (const [input, code] of tries) {
+    await assert.rejects(() => P.payForTask(input, { pool, account: ACCOUNT, authority: allow }), (e) => e instanceof P.PayoutRefusal && e.code === code, code);
+  }
+  assert.equal(pool.s.owed.length, 0);
+});
+
+test('with no project-account record to book into, nothing is sent', async () => {
+  const pool = fakeDb({ approvals: [APPROVAL] });
+  const proc = fakeProcessor();
+  const out = await P.payForTask({ approvalId: 50, taskId: 1, actorId: 1 }, { pool, account: null, authority: allow, processor: proc });
+  assert.equal(out.status, 'held');
+  assert.equal(out.reason, 'no_account_record');
+  assert.equal(proc.calls.length, 0, 'a payment that could not be booked is never sent');
+  assert.equal(pool.s.owed.length, 1);
+});
+
+// ---- the routes, over real HTTP -------------------------------------------------
+
+test('the pay route: a person on the website only, ids from the body, refusals in words', async () => {
+  const express = require('express');
+  const http = require('node:http');
+  const build = require('../src/bongos/routes/payout-approvals');
+  const asked = [];
+  const stubPayouts = {
+    PayoutRefusal: P.PayoutRefusal,
+    payForTask: async (input) => {
+      asked.push(input);
+      if (String(input.taskId) === '9') throw new P.PayoutRefusal('no_such_task', 'There is no task with that id.', 404);
+      return { status: 'held', reason: 'no_processor' };
+    },
+    listPayouts: async () => ({ total: 1, payouts: [{ id: '1', status: 'owed' }] }),
+  };
+  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({ payouts: stubPayouts, 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();
+  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', () => resolve({ status: res.statusCode, body: JSON.parse(d || 'null') }));
+    });
+    if (body) r.write(JSON.stringify(body));
+    r.end();
+  });
+  try {
+    assert.ok(gated.every((g) => g === 'payout.approve'), 'every payouts route gates on payout.approve');
+    let r = await call('POST', '/payouts/builder-payouts', { approval_id: 50, task_id: 1 });
+    assert.equal(r.status, 200);
+    assert.equal(r.body.status, 'held');
+    assert.deepEqual(asked[0], { approvalId: 50, taskId: 1, actorId: '7' }, 'the actor is the signed-in person, never the body');
+
+    r = await call('POST', '/payouts/builder-payouts', { approval_id: 50, task_id: 9 });
+    assert.equal(r.status, 404);
+    assert.equal(r.body.error, 'no_such_task');
+
+    r = await call('GET', '/payouts/builder-payouts');
+    assert.equal(r.status, 200);
+    assert.equal(r.body.payouts.length, 1);
+
+    who = { ...who, gdsSession: { source: 'cli', session_id: '92' } };
+    const before = asked.length;
+    r = await call('POST', '/payouts/builder-payouts', { approval_id: 50, task_id: 1 });
+    assert.equal(r.status, 403);
+    assert.equal(r.body.error, 'personal_approval_required');
+    assert.equal(asked.length, before, 'an AI (CLI) session cannot send a payment');
+  } finally { server.close(); }
+});