@bongos/core 1.24.23 → 1.24.24

package/src/bongos/routes/module-payouts.js

@@ -0,0 +1,114 @@
+'use strict';
+
+// src/bongos/routes/module-payouts.js — a module sale's split rule, the sale, and paying
+// each share (task 1004910, goal 1000092 N6; ADR 0388). The rules live in
+// ../module-payouts.js; the database repeats the ones that matter (core_291).
+//
+// rank: every route needs `payout.approve` (read fresh per request, ADR 0016), except
+// GET /payouts/module-shares/mine, where any signed-in builder sees their own shares and
+// the weight behind each (Art. VIII). Every write is a PERSONAL act: the person's own web
+// session, never a CLI token or a machine principal (payout-approvals' personalSession).
+//
+// No processor adapter exists yet (ADR 0397), so `processor` is null: a sale cannot be
+// read and a share is recorded as owed and held. Dependencies are injectable for tests.
+
+const express = require('express');
+const auth = require('../auth');
+const { validateOrRespond, parsePagination } = require('./_helpers');
+const modulePayouts = require('../module-payouts');
+const log = require('../logger').logger.child({ src: 'module-payouts' });
+
+const PERSONAL_REFUSAL = 'Moving module money must be done by you, signed in on the website. A command-line or AI session cannot do it.';
+
+module.exports = function buildModulePayoutsRouter({
+  payouts = modulePayouts,
+  store = require('../payout-approvals'),
+  processor = null,
+  requireBuilder = auth.requireBuilder,
+  requirePermission = auth.requirePermission,
+} = {}) {
+  const router = express.Router();
+
+  function personal(req, res) {
+    const p = store.personalSession(req);
+    if (!p.ok) {
+      res.fail('personal_approval_required', { status: 403, message: PERSONAL_REFUSAL });
+      return null;
+    }
+    return p.actor;
+  }
+
+  function fail(res, err, what) {
+    if (err instanceof payouts.PayoutRefusal) return res.fail(err.code, { status: err.status, message: err.message });
+    log.error({ err: err && err.message }, `${what} failed`);
+    if (!res.headersSent) res.fail('module_payout_failed', { status: 500, message: 'internal error' });
+  }
+
+  // GET /api/bongos/payouts/module-splits/:moduleKey — the module's split rule and the
+  // contributors' weights it would use now.
+  router.get('/payouts/module-splits/:moduleKey', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    try {
+      res.json(await payouts.previewSplit(req.params.moduleKey));
+    } catch (err) { fail(res, err, 'GET /payouts/module-splits'); }
+  });
+
+  // POST /api/bongos/payouts/module-splits/:moduleKey — record the project's rule.
+  // Body: { seller_id, seller_bps, contributors_bps, credit_row_kinds? }.
+  router.post('/payouts/module-splits/:moduleKey', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, {
+      seller_id: { required: true }, seller_bps: { required: true }, contributors_bps: { required: true }, credit_row_kinds: {},
+    })) return;
+    try {
+      const rule = await payouts.setSplitRule({ moduleKey: req.params.moduleKey, body: req.body, actorId: actor.id });
+      res.status(201).json({ rule });
+    } catch (err) { fail(res, err, 'POST /payouts/module-splits'); }
+  });
+
+  // POST /api/bongos/payouts/module-sales — record ONE sale the processor reports, and
+  // write every share as owed. Body: { processor_sale_ref }. The price is read from the
+  // processor, never the body. Recording the same sale again answers with the one there.
+  router.post('/payouts/module-sales', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { processor_sale_ref: { required: true } })) return;
+    try {
+      const out = await payouts.recordSale({ processorSaleRef: req.body.processor_sale_ref, actorId: actor.id }, { processor });
+      res.status(out.already ? 200 : 201).json(out);
+    } catch (err) { fail(res, err, 'POST /payouts/module-sales'); }
+  });
+
+  // GET /api/bongos/payouts/module-shares — every share and where it stands.
+  router.get('/payouts/module-shares', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    try {
+      const { limit, offset } = parsePagination(req, { defaultLimit: 50, maxLimit: 200 });
+      res.json({ shares: await payouts.listShares(undefined, { limit, offset }) });
+    } catch (err) { fail(res, err, 'GET /payouts/module-shares'); }
+  });
+
+  // GET /api/bongos/payouts/module-shares/mine — the signed-in builder's own shares.
+  router.get('/payouts/module-shares/mine', requireBuilder, async (req, res) => {
+    try {
+      const { limit, offset } = parsePagination(req, { defaultLimit: 50, maxLimit: 200 });
+      res.set('Cache-Control', 'no-store');
+      res.json({ shares: await payouts.listShares(undefined, { recipientId: req.builder.id, limit, offset }) });
+    } catch (err) { fail(res, err, 'GET /payouts/module-shares/mine'); }
+  });
+
+  // POST /api/bongos/payouts/module-shares/:id/pay — send ONE share under ONE approval.
+  // Body: { approval_id }. The person and the amount come from the share; the approval
+  // must name exactly them. Pressing again is safe, as for a task payout.
+  router.post('/payouts/module-shares/:id/pay', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { approval_id: { required: true } })) return;
+    try {
+      const out = await payouts.payShare({ shareId: req.params.id, approvalId: req.body.approval_id, actorId: actor.id }, { processor });
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) { fail(res, err, 'POST /payouts/module-shares/:id/pay'); }
+  });
+
+  return router;
+};

package/src/bongos/routes/my-cash-outs.js

@@ -0,0 +1,103 @@
+'use strict';
+
+// src/bongos/routes/my-cash-outs.js — a person takes their own balance out to their bank
+// (task 1004911, goal 1000092 N7; ADR 0385 D1/D8, ADR 0397 D2/D7).
+//
+//   GET  /me/cash-outs               my withdrawals, each in plain words, the minimum, my balance
+//   POST /me/cash-outs               { amount_cents, instruction_id } → ask for one withdrawal
+//   POST /me/cash-outs/:id/retry     try an unfinished one again (never pays twice)
+//   POST /me/cash-outs/:id/cancel    withdraw a request that has not been sent
+//
+// Own-scoped (tests/own_scope_guard.mjs): every route acts on req.builder.id and nothing
+// else; someone else's withdrawal answers 404. Every write needs the person's own web
+// session: pressing it IS their logged personal approval (N9), so a CLI token, an agent or a
+// machine principal can never take a person's money out. ../cash-outs.js owns the order.
+//
+// The processor adapter (ADR 0397: the only code that may name the rail) does not exist
+// yet, so every withdrawal is recorded and held `no_processor` until it lands.
+
+const express = require('express');
+const auth = require('../auth');
+const { validateOrRespond } = require('./_helpers');
+const log = require('../logger').logger.child({ src: 'my-cash-outs' });
+
+const PERSONAL_REFUSAL = 'A cash-out is made by you, signed in on the website. A command-line or AI session cannot take money out.';
+
+function buildMyCashOutsRouter({
+  cashOuts = require('../cash-outs'),
+  approvals = require('../payout-approvals'),
+  processor = null,
+  requireBuilder = auth.requireBuilder,
+} = {}) {
+  const router = express.Router();
+
+  function personal(req, res) {
+    const p = approvals.personalSession(req);
+    if (!p.ok) {
+      res.fail('personal_approval_required', { status: 403, message: PERSONAL_REFUSAL });
+      return null;
+    }
+    return p.actor;
+  }
+
+  function fault(res, err, what) {
+    if (err instanceof cashOuts.CashOutRefusal) {
+      return res.fail(err.code, { status: err.status, message: err.message, ...(err.details ? { details: err.details } : {}) });
+    }
+    // a database rule refusing (core_293's triggers): say no in words, keep its text in the log
+    if (err && (err.code === '23514' || err.code === '42501' || err.code === '23505')) {
+      log.warn({ err: err.message }, `${what} refused by the database`);
+      return res.fail('cash_out_refused', { status: 409, message: 'The cash-out rules refused this. Nothing was sent.' });
+    }
+    log.error({ err: err && err.message }, `${what} failed`);
+    if (!res.headersSent) res.fail('cash_out_failed', { status: 500, message: 'internal error' });
+    return undefined;
+  }
+
+  const answer = (res, out) => {
+    res.set('Cache-Control', 'no-store');
+    res.status(out.status === 'sent' || out.status === 'paid' || out.status === 'cancelled' ? 200 : 202).json(out);
+  };
+
+  // GET /api/bongos/me/cash-outs — my withdrawals and where each stands.
+  router.get('/me/cash-outs', requireBuilder, async (req, res) => {
+    try {
+      const out = await cashOuts.listMyCashOuts(req.builder.id, { processor, limit: req.query.limit, log });
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) { fault(res, err, 'GET /me/cash-outs'); }
+  });
+
+  // POST /api/bongos/me/cash-outs — ask to take amount_cents of my balance to my bank.
+  router.post('/me/cash-outs', requireBuilder, async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { amount_cents: { required: true }, instruction_id: { required: true } })) return;
+    try {
+      const out = await cashOuts.requestCashOut({
+        builderId: String(req.builder.id), actor, amountCents: req.body.amount_cents, instructionId: req.body.instruction_id,
+      }, { processor, log });
+      answer(res, out);
+    } catch (err) { fault(res, err, 'POST /me/cash-outs'); }
+  });
+
+  // POST /api/bongos/me/cash-outs/:id/retry — try one of my unfinished withdrawals again.
+  router.post('/me/cash-outs/:id/retry', requireBuilder, async (req, res) => {
+    if (!personal(req, res)) return;
+    try {
+      answer(res, await cashOuts.retryCashOut({ builderId: String(req.builder.id), cashOutId: req.params.id }, { processor }));
+    } catch (err) { fault(res, err, 'POST /me/cash-outs/:id/retry'); }
+  });
+
+  // POST /api/bongos/me/cash-outs/:id/cancel — withdraw one of my requests that has not been sent.
+  router.post('/me/cash-outs/:id/cancel', requireBuilder, async (req, res) => {
+    if (!personal(req, res)) return;
+    try {
+      answer(res, await cashOuts.cancelCashOut({ builderId: String(req.builder.id), cashOutId: req.params.id }));
+    } catch (err) { fault(res, err, 'POST /me/cash-outs/:id/cancel'); }
+  });
+
+  return router;
+}
+
+module.exports = buildMyCashOutsRouter;

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

@@ -6,7 +6,8 @@
 // WHY. The gates themselves run inside every money route (../payout-gates.js,
 // called from routes/payout-approvals.js and from checkRun / checkApproval). This
 // file is where their facts are recorded — an age tier, a guardian link, a
-// sanctions screening, a hand-made hold — and where an appeal is decided. The
+// sanctions screening, a hand-made hold, and the contractor papers (an NDA on
+// file, tax details collected; task 1004908) — and where an appeal is decided. The
 // person whose pay is held reads why and appeals in routes/my-payouts.js (the
 // framework, cited by Article only, forbids withholding earned pay silently).
 //
@@ -137,6 +138,46 @@ function buildPayoutGatesRouter({
     } catch (err) { fault(res, err, 'POST /payouts/screenings'); }
   });
 
+  // POST /api/bongos/payouts/ndas — record that a builder's signed NDA is on file
+  // (or withdrawn), and where the signed copy lives. Never the NDA's text.
+  // Body: { builder_id, status: on_file|withdrawn, nda_version, reference? }.
+  router.post('/payouts/ndas', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { builder_id: { required: true }, status: { required: true }, nda_version: { required: true }, reference: {} })) return;
+    const b = req.body;
+    if (!approvals.isId(b.builder_id)) return res.fail('bad_builder_id', { status: 400, message: 'builder_id must be a number' });
+    if (String(b.builder_id) === String(actor.id)) return res.fail('own_papers', { status: 403, message: 'Someone else must record your own NDA.' });
+    if (!gates.NDA_STATUSES.includes(b.status)) return res.fail('bad_status', { status: 400, message: `status must be one of ${gates.NDA_STATUSES.join(', ')}` });
+    if (typeof b.nda_version !== 'string' || !/^[A-Za-z0-9._-]{1,40}$/.test(b.nda_version)) return res.fail('bad_nda_version', { status: 400, message: 'nda_version must be a short label (letters, digits, dot, dash, underscore), such as beta-v1.' });
+    const reference = b.reference == null ? null : statement(b.reference, 200);
+    if (reference !== null && reference.length > 200) return res.fail('bad_reference', { status: 400, message: 'reference must be up to 200 characters' });
+    try {
+      res.status(201).json({ record: await gates.recordNda({ builderId: b.builder_id, status: b.status, ndaVersion: b.nda_version, reference, recordedBy: actor.id }) });
+    } catch (err) { fault(res, err, 'POST /payouts/ndas'); }
+  });
+
+  // POST /api/bongos/payouts/tax-details — record that the processor's onboarding has
+  // (or has not) collected a builder's identity and tax details, as checked by a
+  // person. The tax id itself never comes here: a reference that looks like one is
+  // refused. Body: { builder_id, status: collected|incomplete, reference? }.
+  router.post('/payouts/tax-details', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { builder_id: { required: true }, status: { required: true }, reference: {} })) return;
+    const b = req.body;
+    if (!approvals.isId(b.builder_id)) return res.fail('bad_builder_id', { status: 400, message: 'builder_id must be a number' });
+    if (String(b.builder_id) === String(actor.id)) return res.fail('own_papers', { status: 403, message: 'Someone else must record your own tax details.' });
+    if (!gates.TAX_STATUSES.includes(b.status)) return res.fail('bad_status', { status: 400, message: `status must be one of ${gates.TAX_STATUSES.join(', ')}` });
+    const reference = b.reference == null ? null : statement(b.reference, 200);
+    if (reference !== null && reference.length > 200) return res.fail('bad_reference', { status: 400, message: 'reference must be up to 200 characters' });
+    if (reference !== null && gates.looksLikeTaxId(reference)) return res.fail('tax_id_refused', { status: 400, message: 'That looks like a tax id. Record the processor\'s onboarding reference instead; Bongos never stores tax ids.' });
+    const login = String(req.builder.github_login || actor.id).replace(/[^A-Za-z0-9._-]/g, '').slice(0, 60) || String(actor.id);
+    try {
+      res.status(201).json({ record: await gates.recordTaxDetails({ builderId: b.builder_id, status: b.status, collectedBy: `person:${login}`, reference, recordedBy: actor.id }) });
+    } catch (err) { fault(res, err, 'POST /payouts/tax-details'); }
+  });
+
   // POST /api/bongos/payouts/freezes — a person freezes a builder's payouts by hand.
   // The notice is required: there is no silent freeze. Body: { builder_id, notice_text, owed_cents? }.
   router.post('/payouts/freezes', requireBuilder, requirePermission('payout.approve'), async (req, res) => {

package/src/bongos/routes.js

@@ -37,6 +37,10 @@ const buildPayoutApprovalsRouter = require('./routes/payout-approvals');
 // Who may be paid at all: age tier, sanctions, a hold that tells the person (task 1004914).
 const buildPayoutGatesRouter = require('./routes/payout-gates');
 const buildMyPayoutsRouter = require('./routes/my-payouts');
+// A person takes their own balance out to their bank (task 1004911, N7).
+const buildMyCashOutsRouter = require('./routes/my-cash-outs');
+// A module sale's split rule, the sale and each share's payout (task 1004910, ADR 0388).
+const buildModulePayoutsRouter = require('./routes/module-payouts');
 const buildBuildersRouter = require('./routes/builders');
 // The LIFECYCLE routes (tasks · claims · versions · done-when · goals ·
 // dependencies · analytics) carved into modules/lifecycle/
@@ -179,6 +183,8 @@ function buildGdsRouter() {
   router.use(buildPayoutApprovalsRouter());
   router.use(buildPayoutGatesRouter());
   router.use(buildMyPayoutsRouter());
+  router.use(buildMyCashOutsRouter());
+  router.use(buildModulePayoutsRouter());
   router.use(buildBuildersRouter());
   // tasks · claims · versions · done-when · goals · dependencies · analytics now
   // mount via moduleLoader.mountModuleRoutes below (lifecycle module, BV1.R86) —

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.23'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.24.24'; // 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/builder_payouts_db.mjs

@@ -57,6 +57,7 @@ try {
   await client.query(`INSERT INTO payout_approvals (kind, recipient_id, amount_cents, currency)
                       VALUES ('payout_approved', 1, 12500, 'USD'), ('payout_approved', 1, 300, 'USD'), ('payout_approved', 1, 400, 'USD')`);
   await client.query(mig('modules', 'economy', 'migrations', 'economy_002_project_account.sql'));
+  await client.query(mig('modules', 'economy', 'migrations', 'economy_004_module_share_payouts.sql'));
   await client.query(mig('migrations', 'core_290_builder_payouts.sql'));
   await client.query('BEGIN');
 

package/tests/cash_outs.mjs

@@ -0,0 +1,96 @@
+// tests/cash_outs.mjs — task 1004911 (goal 1000092 N7). DB-free.
+//
+// The pure half of cash-outs: how a withdrawal's attempts fold into where it stands (and
+// which try, so which idempotency key, comes next), the refusals made before anything is
+// recorded, and the routes' own gate: only the person, signed in on the web, can take their
+// money out. The real tables and the real flow are tests/cash_outs_db.mjs.
+//
+// Run: node tests/cash_outs.mjs
+import { createRequire } from 'node:module';
+import { strict as assert } from 'node:assert';
+import http from 'node:http';
+const require = createRequire(import.meta.url);
+const express = require('express');
+const C = require('../src/bongos/cash-outs.js');
+const buildMyCashOuts = require('../src/bongos/routes/my-cash-outs.js');
+
+let pass = 0;
+const ok = (c, m) => { assert.ok(c, m); pass++; console.log(`  ok - ${m}`); };
+const refusal = async (fn) => { try { await fn(); } catch (e) { return e; } return null; };
+const at = (outcome, tryNo, ref = null) => ({ outcome, try_no: tryNo, processor_ref: ref, reason: ref ? null : 'x' });
+
+// ── standing ─────────────────────────────────────────────────────────────
+ok(C.standing([]).status === 'held' && C.standing([]).try_no === 1, 'nothing tried yet: waiting, try 1');
+ok(C.standing([at('failed', 1)]).try_no === 1, 'a failure we cannot trust keeps try 1 (the same key)');
+ok(C.standing([at('refused', 1)]).try_no === 2, 'a processor refusal moves on to try 2');
+ok(C.standing([at('sent', 1, 'po_1')]).status === 'sent', 'sent and not yet arrived');
+ok(C.standing([at('sent', 1, 'po_1'), at('paid', 1, 'po_1')]).status === 'paid', 'arrived');
+const back = C.standing([at('sent', 1, 'po_1'), at('paid', 1, 'po_1'), { outcome: 'returned', try_no: 1, processor_ref: 'po_1', reason: 'closed' }]);
+ok(back.status === 'returned' && back.try_no === 2, 'a bank return after arrival reopens it on try 2');
+ok(C.standing([at('held', 1), at('cancelled', 1)]).status === 'cancelled', 'cancelled');
+ok(C.idempotencyKey('7', 2) === 'bongos-cashout-7-2', 'the key names the withdrawal and the try');
+
+// ── refusals before anything is recorded ─────────────────────────────────
+const noDb = { query: async () => { throw new Error('the database must not be reached'); } };
+const me = { id: '5', session_id: '1', session_source: 'web' };
+let e = await refusal(() => C.requestCashOut({ builderId: '5', actor: me, amountCents: 999, instructionId: 'press-000001' }, { pool: noDb, account: { memberAccount: async () => 'acct_test' } }));
+ok(e && e.code === 'below_minimum', 'below the minimum is refused without touching the database');
+e = await refusal(() => C.requestCashOut({ builderId: '5', actor: me, amountCents: 1.5, instructionId: 'press-000001' }, { pool: noDb }));
+ok(e && e.code === 'bad_amount', 'a fractional amount is refused');
+e = await refusal(() => C.requestCashOut({ builderId: '5', actor: me, amountCents: 2000, instructionId: 'x' }, { pool: noDb }));
+ok(e && e.code === 'bad_instruction_id', 'a malformed instruction id is refused');
+e = await refusal(() => C.requestCashOut({ builderId: '5', actor: { ...me, id: '6' }, amountCents: 2000, instructionId: 'press-000001' }, { pool: noDb }));
+ok(e && e.code === 'personal_session_required', "nobody cashes out someone else's money");
+e = await refusal(() => C.requestCashOut({ builderId: '5', actor: me, amountCents: 2000, instructionId: 'press-000001' }, { pool: noDb, account: null }));
+ok(e && e.code === 'no_account_record', 'with balances switched off there is nothing to cash out');
+e = await refusal(() => C.requestCashOut({ builderId: '5', actor: me, amountCents: 2000, instructionId: 'press-000001' }, { pool: noDb, account: { memberAccount: async () => null } }));
+ok(e && e.code === 'no_account', 'no processor account here: nothing to cash out');
+e = await refusal(() => C.recordProcessorOutcome({ processorRef: 'po_1', outcome: 'returned' }, { pool: noDb }));
+ok(e && e.code === 'no_reason', 'a returned payout must say why');
+
+// ── the routes' gate ─────────────────────────────────────────────────────
+const seen = [];
+const stub = {
+  CashOutRefusal: C.CashOutRefusal,
+  listMyCashOuts: async (id) => { seen.push(['list', id]); return { cash_outs: [] }; },
+  requestCashOut: async (i) => { seen.push(['request', i.builderId, i.actor.id]); return { status: 'held' }; },
+  retryCashOut: async (i) => { seen.push(['retry', i.builderId, i.cashOutId]); throw new C.CashOutRefusal('no_such_cash_out', 'none', 404); },
+  cancelCashOut: async (i) => { seen.push(['cancel', i.builderId]); return { status: 'cancelled' }; },
+};
+function serve(as) {
+  const a = express();
+  a.use(express.json());
+  a.use((req, res, next) => { res.fail = (code, o = {}) => res.status(o.status || 400).json({ error: code, message: o.message }); req.builder = as.builder; req.gdsSession = as.gdsSession; next(); });
+  a.use('/', buildMyCashOuts({ cashOuts: stub, requireBuilder: (q, r, nx) => nx() }));
+  return http.createServer(a).listen(0);
+}
+async function call(srv, method, path, body) {
+  const r = await fetch(`http://127.0.0.1:${srv.address().port}${path}`, { method, headers: { 'content-type': 'application/json' }, body: body ? JSON.stringify(body) : undefined });
+  return { status: r.status, body: await r.json() };
+}
+const web = serve({ builder: { id: '5' }, gdsSession: { source: 'web', session_id: '3' } });
+const cli = serve({ builder: { id: '5' }, gdsSession: { source: 'cli', session_id: '4' } });
+const bot = serve({ builder: { id: '9', system_role: 'agent' }, gdsSession: { source: 'web', session_id: '5' } });
+try {
+  for (const [srv, who] of [[cli, 'a CLI session'], [bot, 'a machine principal']]) {
+    for (const [act, p] of [['request', '/me/cash-outs'], ['retry', '/me/cash-outs/1/retry'], ['cancel', '/me/cash-outs/1/cancel']]) {
+      const r = await call(srv, 'POST', p, { amount_cents: 2000, instruction_id: 'press-000001' });
+      ok(r.status === 403 && r.body.error === 'personal_approval_required', `${who} cannot ${act} a cash-out`);
+    }
+  }
+  ok(!seen.some(([k]) => k !== 'list'), 'nothing reached the cash-out code from a refused session');
+  let r = await call(cli, 'GET', '/me/cash-outs');
+  ok(r.status === 200 && seen.at(-1)[1] === '5', 'reading my own list works from any session, keyed on me');
+  r = await call(web, 'POST', '/me/cash-outs', { amount_cents: 2000, instruction_id: 'press-000001', builder_id: '6' });
+  ok(r.status === 400 && seen.at(-1)[0] === 'list', 'a body naming someone else is refused outright');
+  r = await call(web, 'POST', '/me/cash-outs', { amount_cents: 2000, instruction_id: 'press-000001' });
+  ok(r.status === 202 && seen.at(-1)[1] === '5' && seen.at(-1)[2] === '5', 'a request is mine: the signed-in person, never the body');
+  r = await call(web, 'POST', '/me/cash-outs/77/retry');
+  ok(r.status === 404 && r.body.error === 'no_such_cash_out', 'a refusal is passed on with its status');
+  r = await call(web, 'POST', '/me/cash-outs', {});
+  ok(r.status === 400, 'a request with no amount is refused');
+} finally {
+  for (const s of [web, cli, bot]) s.close();
+}
+
+console.log(`\ncash_outs.mjs: ${pass} passed`);

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