@bongos/core 1.24.23 → 1.24.25

package/tests/module_payouts.mjs

@@ -0,0 +1,295 @@
+// tests/module_payouts.mjs — a module sale is split by the project's rule and each share
+// is paid exactly once (task 1004910, goal 1000092 N6; ADR 0388). Behaviour of
+// src/bongos/module-payouts.js:
+//   - the split adds up to the price exactly, the seller rounds down, the pool takes the
+//     rest by weight with largest remainders, and a pool nobody weighs stays unassigned;
+//   - a rule is refused until module_share's gate (licence, takedown, onboarding) is
+//     cleared, and while the seller fails the payout gates;
+//   - a sale's price is read from the processor, its shares are owed in the same step, the
+//     price is booked as funding, and a repeated report records nothing new;
+//   - a share is paid only under an approval for exactly that person and amount, an
+//     approval binds to one share, a gate or a missing processor holds it, and paying
+//     again sends once.
+// The migration's own rules are pinned from its text at the end.
+
+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 M = require('../src/bongos/module-payouts.js');
+const ACCOUNT = require('../modules/economy/project-account.js');
+
+const RULE = { seller_id: '7', seller_bps: 3000, contributors_bps: 7000, credit_row_kinds: ['session.token_reward'] };
+const sum = (shares) => shares.reduce((s, x) => s + x.amount_cents, 0);
+
+test('splitSale: the shares add up to the price, seller rounds down, pool by largest remainder', () => {
+  const out = M.splitSale({ priceCents: 1001, rule: RULE, weights: [
+    { builder_id: '3', weight: 1000 }, { builder_id: '2', weight: 1000 }, { builder_id: '1', weight: 1000 },
+  ] });
+  assert.equal(out.pool_unassigned_cents, 0);
+  assert.equal(sum(out.shares), 1001);
+  const seller = out.shares.find((s) => s.role === 'seller');
+  assert.equal(seller.amount_cents, 300); // floor(1001 * 0.3)
+  const c = out.shares.filter((s) => s.role === 'contributor');
+  // 701 over three equal weights: 234, 234, 233 — the extra cents go to the lower ids
+  assert.deepEqual(c.map((s) => [s.recipient_id, s.amount_cents]), [['1', 234], ['2', 234], ['3', 233]]);
+  assert.ok(c.every((s) => s.weight === 1000 && s.weight_total === 3000));
+});
+
+test('splitSale: weight decides the pool, and a zero-cent share is dropped', () => {
+  const out = M.splitSale({ priceCents: 100, rule: { ...RULE, seller_bps: 0, contributors_bps: 10000 }, weights: [
+    { builder_id: '1', weight: 999000 }, { builder_id: '2', weight: 1 }, { builder_id: '3', weight: 0 },
+  ] });
+  assert.equal(sum(out.shares), 100);
+  assert.deepEqual(out.shares.map((s) => [s.recipient_id, s.amount_cents]), [['1', 100]]);
+});
+
+test('splitSale: a pool with no weighted contributor stays unassigned, never handed out', () => {
+  const out = M.splitSale({ priceCents: 500, rule: RULE, weights: [] });
+  assert.deepEqual(out.shares.map((s) => [s.role, s.amount_cents]), [['seller', 150]]);
+  assert.equal(out.pool_unassigned_cents, 350);
+});
+
+test('validateSplitRule: shares must add to 10000, nothing unknown, kinds default to session rows', () => {
+  assert.deepEqual(M.validateSplitRule({ seller_id: 7, seller_bps: 4000, contributors_bps: 6000 }).rule.credit_row_kinds, ['session.token_reward']);
+  assert.ok(M.validateSplitRule({ seller_id: 7, seller_bps: 4000, contributors_bps: 5000 }).errors[0].includes('10000'));
+  assert.ok(M.validateSplitRule({ seller_id: 7, seller_bps: 4000, contributors_bps: 6000, fee_bps: 100 }).errors.some((e) => e.includes('fee_bps')));
+  assert.ok(M.validateSplitRule({ seller_id: 'x', seller_bps: 1.5, contributors_bps: 6000 }).errors.length >= 2);
+  assert.ok(M.validateSplitRule({ seller_id: 7, seller_bps: 0, contributors_bps: 10000, credit_row_kinds: [] }).errors.length === 1);
+});
+
+// ── a stand-in pool that understands the statements module-payouts.js sends ─────────
+
+function fakeDb({ approvals = [], weights = [], rule = { id: '1', module_key: 'chess', ...RULE } } = {}) {
+  const s = { sales: [], shares: [], bindings: [], attempts: [], movements: [], rules: rule ? [rule] : [], approvals, taskApprovals: [] };
+  async function query(sql, p = []) {
+    const q = sql.replace(/\s+/g, ' ').trim();
+    if (/pg_advisory_xact_lock/.test(q)) return { rows: [] };
+    if (/^SELECT module_key, status FROM store_modules/.test(q)) {
+      return { rows: p[0] === 'chess' ? [{ module_key: 'chess', status: 'listed' }] : p[0] === 'old' ? [{ module_key: 'old', status: 'delisted' }] : [] };
+    }
+    if (/FROM module_sale_shares_owed o JOIN module_sales s/.test(q)) {
+      s.listParams = p;
+      return { rows: s.shares.filter((x) => p[0] === null || x.recipient_id === String(p[0])).map((x) => {
+        const sent = s.attempts.find((a) => a.share_id === x.id && a.outcome === 'sent');
+        const last = [...s.attempts].reverse().find((a) => a.share_id === x.id);
+        const bound = s.bindings.find((b) => b.share_id === x.id);
+        return { ...x, module_key: 'chess', processor_sale_ref: 'ch_1', price_cents: '1000', recipient_name: null, created_at: null,
+          approval_id: bound ? bound.approval_id : null, sent_ref: sent ? sent.processor_ref : null, paid_at: null,
+          last_outcome: last ? last.outcome : null, last_reason: last ? last.reason : null, last_try_at: null };
+      }) };
+    }
+    if (/FROM module_split_rules WHERE module_key/.test(q)) return { rows: s.rules.filter((r) => r.module_key === p[0]).slice(-1) };
+    if (/^INSERT INTO module_split_rules/.test(q)) {
+      const row = { id: String(s.rules.length + 1), module_key: p[0], seller_id: p[1], seller_bps: p[2], contributors_bps: p[3], credit_row_kinds: p[4], set_by: p[5] };
+      s.rules.push(row);
+      return { rows: [row] };
+    }
+    if (/WITH mt AS/.test(q)) return { rows: weights };
+    if (/FROM module_sales WHERE processor_sale_ref/.test(q)) return { rows: s.sales.filter((x) => x.processor_sale_ref === p[0]) };
+    if (/FROM module_sale_shares_owed WHERE sale_id/.test(q)) return { rows: s.shares.filter((x) => x.sale_id === p[0]) };
+    if (/^INSERT INTO module_sales/.test(q)) {
+      const row = { id: String(s.sales.length + 1), module_key: p[0], processor_sale_ref: p[1], price_cents: p[2], platform_fee_cents: p[3], currency: p[4], rule_id: p[5], pool_unassigned_cents: p[6] };
+      s.sales.push(row);
+      return { rows: [row] };
+    }
+    if (/^INSERT INTO module_sale_shares_owed/.test(q)) {
+      const row = { id: String(s.shares.length + 1), sale_id: p[0], recipient_id: p[1], role: p[2], amount_cents: p[3], currency: p[4], weight: p[5], weight_total: p[6] };
+      s.shares.push(row);
+      return { rows: [row] };
+    }
+    if (/FROM module_sale_shares_owed WHERE id/.test(q)) return { rows: s.shares.filter((x) => x.id === String(p[0])) };
+    if (/FROM payout_approvals WHERE id/.test(q)) return { rows: s.approvals.filter((a) => String(a.id) === String(p[0])) };
+    if (/^INSERT INTO module_share_approvals/.test(q)) {
+      if (s.taskApprovals.includes(String(p[1]))) throw Object.assign(new Error('already pays a task'), { code: 'P0001' });
+      const clash = s.bindings.some((b) => b.share_id === String(p[0]) || b.approval_id === String(p[1]));
+      if (!clash) s.bindings.push({ share_id: String(p[0]), approval_id: String(p[1]) });
+      return { rows: [] };
+    }
+    if (/FROM module_share_approvals WHERE share_id/.test(q)) return { rows: s.bindings.filter((b) => b.share_id === String(p[0])) };
+    if (/^INSERT INTO module_share_attempts/.test(q)) {
+      const [share_id, outcome, processor_ref, reason] = p;
+      if (outcome === 'sent' && s.attempts.some((a) => a.share_id === share_id && a.outcome === 'sent')) throw Object.assign(new Error('one sent'), { code: '23505' });
+      const row = { id: s.attempts.length + 1, share_id, outcome, processor_ref, reason };
+      s.attempts.push(row);
+      return { rows: [row] };
+    }
+    if (/FROM module_share_attempts WHERE share_id = \$1 AND outcome = 'sent'/.test(q)) return { rows: s.attempts.filter((a) => a.share_id === String(p[0]) && a.outcome === 'sent') };
+    if (/^INSERT INTO economy_project_account_movements/.test(q)) {
+      const [kind, , amount_micro, builder_id, , , processor_ref, , , module_share_id] = p;
+      if (s.movements.some((m) => m.kind === kind && m.processor_ref === processor_ref)) return { rows: [] };
+      const row = { kind, amount_micro, builder_id, processor_ref, module_share_id };
+      s.movements.push(row);
+      return { rows: [row] };
+    }
+    if (/FROM economy_project_account_movements WHERE kind/.test(q)) return { rows: s.movements.filter((m) => m.kind === p[0] && m.processor_ref === p[1]) };
+    throw new Error(`fakeDb: unexpected SQL: ${q}`);
+  }
+  return { s, query };
+}
+
+const cleared = { refuseUnclearedGates: async () => null };
+const uncleared = { refuseUnclearedGates: async () => ({ code: 'pay_type_gate_not_cleared', missing: ['standard_module_licence'], message: 'not cleared' }) };
+const okGates = { gateRecipient: async () => ({ ok: true }) };
+const account = { recordMovement: ACCOUNT.recordMovement };
+const saleProcessor = (sale) => ({ readSale: async () => sale });
+
+async function refusal(p) {
+  try { await p; } catch (e) { return e; }
+  assert.fail('expected a refusal');
+}
+
+test('setSplitRule: refused until the licence and takedown gate is cleared, or while the seller is gated', async () => {
+  const pool = fakeDb({ rule: null });
+  const body = { seller_id: 7, seller_bps: 3000, contributors_bps: 7000 };
+  assert.equal((await refusal(M.setSplitRule({ moduleKey: 'chess', body, actorId: 1 }, { pool, gates: okGates, payTypeGates: uncleared }))).code, 'module_share_gate');
+  assert.equal((await refusal(M.setSplitRule({ moduleKey: 'chess', body, actorId: 1 }, { pool, gates: okGates, payTypeGates: null }))).code, 'module_share_gate');
+  assert.equal((await refusal(M.setSplitRule({ moduleKey: 'chess', body, actorId: 1 }, { pool, gates: { gateRecipient: async () => ({ ok: false }) }, payTypeGates: cleared }))).code, 'seller_gated');
+  assert.equal((await refusal(M.setSplitRule({ moduleKey: 'nope', body, actorId: 1 }, { pool, gates: okGates, payTypeGates: cleared }))).code, 'no_such_module');
+  assert.equal((await refusal(M.setSplitRule({ moduleKey: 'old', body, actorId: 1 }, { pool, gates: okGates, payTypeGates: cleared }))).code, 'module_delisted');
+  assert.equal(pool.s.rules.length, 0);
+  const rule = await M.setSplitRule({ moduleKey: 'chess', body, actorId: 1 }, { pool, gates: okGates, payTypeGates: cleared });
+  assert.equal(rule.seller_bps, 3000);
+  assert.equal(pool.s.rules.length, 1);
+});
+
+test('recordSale: reads the price from the processor, owes every share, books the price once', async () => {
+  const pool = fakeDb({ weights: [{ builder_id: '1', weight: 3000 }, { builder_id: '2', weight: 1000 }] });
+  const processor = saleProcessor({ moduleKey: 'chess', priceCents: 1000, platformFeeCents: 40, currency: 'USD' });
+  const out = await M.recordSale({ processorSaleRef: 'ch_1', actorId: 9 }, { pool, processor, account, payTypeGates: cleared });
+  assert.equal(out.already, false);
+  assert.deepEqual(pool.s.shares.map((x) => [x.recipient_id, x.role, x.amount_cents]), [['7', 'seller', 300], ['1', 'contributor', 525], ['2', 'contributor', 175]]);
+  assert.deepEqual(pool.s.movements.map((m) => [m.kind, m.amount_micro]), [['funding', 1000 * 10_000]]);
+  assert.equal(pool.s.sales[0].platform_fee_cents, 40); // kept apart, never split
+
+  const again = await M.recordSale({ processorSaleRef: 'ch_1', actorId: 9 }, { pool, processor, account, payTypeGates: cleared });
+  assert.equal(again.already, true);
+  assert.equal(pool.s.sales.length, 1);
+  assert.equal(pool.s.shares.length, 3);
+});
+
+test('recordSale: refused with no processor, an uncleared gate, no rule, or a foreign currency', async () => {
+  const sale = { moduleKey: 'chess', priceCents: 1000, currency: 'USD' };
+  assert.equal((await refusal(M.recordSale({ processorSaleRef: 'ch_1', actorId: 9 }, { pool: fakeDb(), processor: null, account, payTypeGates: cleared }))).code, 'no_processor');
+  assert.equal((await refusal(M.recordSale({ processorSaleRef: 'ch_1', actorId: 9 }, { pool: fakeDb(), processor: saleProcessor(sale), account, payTypeGates: uncleared }))).code, 'module_share_gate');
+  assert.equal((await refusal(M.recordSale({ processorSaleRef: 'ch_1', actorId: 9 }, { pool: fakeDb({ rule: null }), processor: saleProcessor(sale), account, payTypeGates: cleared }))).code, 'no_split_rule');
+  assert.equal((await refusal(M.recordSale({ processorSaleRef: 'ch_1', actorId: 9 }, { pool: fakeDb(), processor: saleProcessor({ ...sale, currency: 'EUR' }), account, payTypeGates: cleared }))).code, 'currency_not_supported');
+});
+
+async function soldPool(extra = {}) {
+  const pool = fakeDb({ weights: [{ builder_id: '1', weight: 1 }], ...extra });
+  await M.recordSale({ processorSaleRef: 'ch_1', actorId: 9 },
+    { pool, processor: saleProcessor({ moduleKey: 'chess', priceCents: 1000, currency: 'USD' }), account, payTypeGates: cleared });
+  return pool; // share 1: seller 7, 300c; share 2: contributor 1, 700c
+}
+const approval = (id, recipient_id, amount_cents) => ({ id, kind: 'payout_approved', recipient_id, amount_cents, currency: 'USD' });
+const yes = { checkApproval: async () => ({ ok: true, pay_to: 'self' }) };
+
+test('payShare: pays under a matching approval, once, and books one payout naming the share', async () => {
+  const pool = await soldPool({ approvals: [approval(50, '1', 700)] });
+  const calls = [];
+  const processor = { transfer: async (req) => { calls.push(req); return { ref: 'tr_1' }; } };
+  const first = await M.payShare({ shareId: 2, approvalId: 50, actorId: 9 }, { pool, authority: yes, account, payTypeGates: cleared, processor });
+  assert.equal(first.status, 'paid');
+  assert.equal(calls[0].idempotencyKey, 'bongos-module-share-2');
+  assert.equal(calls[0].amountCents, 700);
+  const again = await M.payShare({ shareId: 2, approvalId: 50, actorId: 9 }, { pool, authority: yes, account, payTypeGates: cleared, processor });
+  assert.equal(again.already, true);
+  assert.equal(calls.length, 1);
+  const payouts = pool.s.movements.filter((m) => m.kind === 'payout');
+  assert.deepEqual(payouts.map((m) => [m.builder_id, m.module_share_id, m.amount_micro]), [['1', '2', 700 * 10_000]]);
+});
+
+test('payShare: an approval for another person or amount is refused and never binds the share', async () => {
+  const pool = await soldPool({ approvals: [approval(50, '1', 699), approval(51, '8', 700), approval(52, '1', 700)] });
+  const deps = { pool, authority: yes, account, payTypeGates: cleared, processor: null };
+  assert.equal((await refusal(M.payShare({ shareId: 2, approvalId: 50, actorId: 9 }, deps))).code, 'different_amount');
+  assert.equal((await refusal(M.payShare({ shareId: 2, approvalId: 51, actorId: 9 }, deps))).code, 'different_recipient');
+  assert.equal(pool.s.bindings.length, 0);
+  const held = await M.payShare({ shareId: 2, approvalId: 52, actorId: 9 }, deps);
+  assert.equal(held.status, 'held');
+  assert.equal(held.reason, 'no_processor');
+  assert.deepEqual(pool.s.bindings, [{ share_id: '2', approval_id: '52' }]);
+});
+
+test('payShare: one approval pays one thing — not two shares, not a task and a share', async () => {
+  const pool = await soldPool({ approvals: [approval(60, '7', 300), approval(61, '7', 300)] });
+  pool.s.shares.push({ id: '3', sale_id: '1', recipient_id: '7', role: 'seller', amount_cents: 300, currency: 'USD' });
+  const deps = { pool, authority: yes, account, payTypeGates: cleared, processor: null };
+  await M.payShare({ shareId: 1, approvalId: 60, actorId: 9 }, deps);
+  assert.equal((await refusal(M.payShare({ shareId: 3, approvalId: 60, actorId: 9 }, deps))).code, 'approval_already_used');
+  assert.equal((await refusal(M.payShare({ shareId: 1, approvalId: 61, actorId: 9 }, deps))).code, 'share_already_approved');
+  pool.s.taskApprovals.push('61');
+  assert.equal((await refusal(M.payShare({ shareId: 3, approvalId: 61, actorId: 9 }, deps))).code, 'approval_already_used');
+});
+
+test('payShare: the same approval raced onto two shares — the loser gets a refusal, not a fault', async () => {
+  const pool = await soldPool({ approvals: [approval(80, '1', 700)] });
+  // the other press won: its binding is there, so this insert does nothing (ON CONFLICT)
+  pool.s.bindings.push({ share_id: '9', approval_id: '80' });
+  const e = await refusal(M.payShare({ shareId: 2, approvalId: 80, actorId: 9 }, { pool, authority: yes, account, payTypeGates: cleared, processor: null }));
+  assert.equal(e.code, 'approval_already_used');
+  assert.equal(e.status, 409);
+});
+
+test('listShares: each share with where it stands, and a person sees only their own', async () => {
+  const pool = await soldPool({ approvals: [approval(90, '1', 700)] });
+  await M.payShare({ shareId: 2, approvalId: 90, actorId: 9 }, { pool, authority: yes, account, payTypeGates: cleared, processor: { transfer: async () => ({ ref: 'tr_l' }) } });
+  await M.payShare({ shareId: 1, approvalId: 90, actorId: 9 }, { pool, authority: yes, account, payTypeGates: cleared, processor: null }).catch(() => {});
+  const all = await M.listShares(pool, {});
+  assert.equal(pool.s.listParams[0], null);
+  const byId = Object.fromEntries(all.map((x) => [x.id, x]));
+  assert.equal(byId['2'].status, 'paid');
+  assert.equal(byId['2'].processor_ref, 'tr_l');
+  assert.equal(byId['2'].approval_id, '90');
+  assert.equal(byId['2'].weight, 1);
+  assert.equal(byId['1'].status, 'owed');
+  assert.equal(byId['1'].weight, null);
+  const mine = await M.listShares(pool, { recipientId: '1', limit: 9999 });
+  assert.equal(pool.s.listParams[1], 200); // the page is capped
+  assert.deepEqual(mine.map((x) => x.id), ['2']);
+});
+
+test('payShare: the module gate, the payout gates and a failed transfer each leave the share owed', async () => {
+  const pool = await soldPool({ approvals: [approval(70, '1', 700)] });
+  const send = { transfer: async () => ({ ref: 'tr_9' }) };
+  const gated = await M.payShare({ shareId: 2, approvalId: 70, actorId: 9 }, { pool, authority: yes, account, payTypeGates: uncleared, processor: send });
+  assert.equal(gated.reason, 'module_share_gate');
+  assert.ok(gated.words.includes('licence'));
+  const no = { checkApproval: async () => ({ ok: false, reason: 'recipient_gated' }) };
+  assert.equal((await M.payShare({ shareId: 2, approvalId: 70, actorId: 9 }, { pool, authority: no, account, payTypeGates: cleared, processor: send })).reason, 'recipient_gated');
+  const boom = { transfer: async () => { throw Object.assign(new Error('card declined'), { code: 'declined' }); } };
+  const failed = await M.payShare({ shareId: 2, approvalId: 70, actorId: 9 }, { pool, authority: yes, account, payTypeGates: cleared, processor: boom });
+  assert.equal(failed.status, 'failed');
+  assert.match(failed.reason, /declined/);
+  assert.equal(pool.s.movements.filter((m) => m.kind === 'payout').length, 0);
+  assert.equal((await M.payShare({ shareId: 2, approvalId: 70, actorId: 9 }, { pool, authority: yes, account, payTypeGates: cleared, processor: send })).status, 'paid');
+});
+
+test('the project account takes a payout that names a module share instead of a task', () => {
+  const row = ACCOUNT.checkMovement({ kind: 'payout', amountMicro: 1, builderId: 1, moduleShareId: 2, processorRef: 'tr_1' });
+  assert.equal(row.module_share_id, '2');
+  assert.throws(() => ACCOUNT.checkMovement({ kind: 'payout', amountMicro: 1, builderId: 1, processorRef: 'tr_1' }), /task or module-sale share/);
+});
+
+test('the migrations hold the rules the code relies on', () => {
+  const core = readFileSync(new URL('../migrations/core_292_module_sale_payouts.sql', import.meta.url), 'utf8');
+  assert.match(core, /seller_bps \+ contributors_bps = 10000/);
+  assert.match(core, /module_share_attempts_one_sent ON module_share_attempts \(share_id\) WHERE outcome = 'sent'/);
+  assert.match(core, /module_share_approvals_one_per_approval ON module_share_approvals \(approval_id\)/);
+  assert.match(core, /module_sales_one_per_ref ON module_sales \(processor_sale_ref\)/);
+  assert.match(core, /BEFORE INSERT ON builder_payouts_owed/);
+  // the cross-table check is serialised per approval, or two inserts at once both pass it
+  assert.match(core, /PERFORM pg_advisory_xact_lock\(1004910, hashtext\(NEW\.approval_id::text\)\);\s+IF TG_TABLE_NAME/);
+  // the weight read is index-served end to end (the grader's efficiency finding)
+  assert.match(core, /idx_tasks_shipped_module ON tasks \(module_key\)\s+WHERE module_key IS NOT NULL AND status = 'shipped'/);
+  assert.match(core, /idx_session_records_task_ids ON session_records USING gin \(task_ids\)/);
+  assert.match(core, /idx_credit_log_session ON credit_log \(session_id\)/);
+  for (const t of ['module_split_rules', 'module_sales', 'module_sale_shares_owed', 'module_share_approvals', 'module_share_attempts']) {
+    assert.match(core, new RegExp(`BEFORE UPDATE OR DELETE ON ${t}\\b`), `${t} is append-only`);
+  }
+  const econ = readFileSync(new URL('../modules/economy/migrations/economy_004_module_share_payouts.sql', import.meta.url), 'utf8');
+  assert.match(econ, /task_id IS NOT NULL OR module_share_id IS NOT NULL/);
+});

package/tests/module_payouts_db.mjs

@@ -0,0 +1,140 @@
+// tests/module_payouts_db.mjs — task 1004910 (goal 1000092 N6). Real DB.
+//
+// Applies the REAL economy_002/003 and core_290/291 migrations and proves what Postgres
+// itself refuses: a split rule whose shares do not add to the whole price, a second sale
+// for one processor reference, a second `sent` attempt for one share, one approval paying
+// two shares or a task and a share, and any rewrite. Then drives the real previewSplit,
+// recordSale and payShare over the real tables: the weights query (task rows and session
+// rows apportioned by the session's tasks on the module), the shares owed, the funding
+// and payout movements.
+//
+// store_modules, credit_log, session_records, tasks and payout_approvals are minimal
+// stand-ins with the columns these statements read. The gates and authority are stubbed.
+//
+// Self-skips without a reachable Postgres.
+// Run:  DATABASE_URL=... node tests/module_payouts_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 M = require('../src/bongos/module-payouts.js');
+const ACCOUNT = require('../modules/economy/project-account.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(`module_payouts_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pgPool.end().catch(() => {});
+  process.exit(0);
+}
+const SCHEMA = `t1004910_${process.pid}`;
+let pass = 0;
+const ok = (c, m) => { assert.ok(c, m); pass++; console.log(`  ok - ${m}`); };
+const rejects = async (sql, params) => {
+  await client.query('SAVEPOINT s');
+  let err = null;
+  try { await client.query(sql, params); } catch (e) { err = e; }
+  await client.query('ROLLBACK TO SAVEPOINT s');
+  return err;
+};
+const code = (e) => e && e.code;
+const RULE = 'INSERT INTO module_split_rules (module_key, seller_id, seller_bps, contributors_bps, credit_row_kinds, set_by) VALUES ($1,$2,$3,$4,$5,$6)';
+
+try {
+  await client.query(`CREATE SCHEMA ${SCHEMA}`);
+  await client.query(`SET search_path TO ${SCHEMA}`);
+  await client.query('CREATE TABLE builders (id bigserial PRIMARY KEY, display_name text)');
+  await client.query("CREATE TABLE tasks (id bigserial PRIMARY KEY, title text, module_key text, status text NOT NULL DEFAULT 'shipped')");
+  await client.query('CREATE TABLE schema_migrations (version text PRIMARY KEY)');
+  await client.query("CREATE TABLE store_modules (module_key text PRIMARY KEY, status text NOT NULL DEFAULT 'listed')");
+  await client.query('CREATE TABLE credit_log (id bigserial PRIMARY KEY, builder_id bigint, task_id bigint, delta integer, reason text, session_id text)');
+  await client.query("CREATE TABLE session_records (session_id text PRIMARY KEY, task_ids bigint[] NOT NULL DEFAULT '{}')");
+  await client.query(`CREATE TABLE payout_approvals (id bigserial PRIMARY KEY, kind text NOT NULL, recipient_id bigint,
+                       amount_cents bigint, currency text)`);
+  await client.query("INSERT INTO builders (display_name) VALUES ('Ada'), ('Bo'), ('Seller'), ('Owner')");
+  // tasks 1,2 on chess and shipped; 3 on chess but not shipped; 4 on another module
+  await client.query(`INSERT INTO tasks (title, module_key, status) VALUES
+    ('a', 'chess', 'shipped'), ('b', 'chess', 'shipped'), ('c', 'chess', 'active'), ('d', 'go', 'shipped')`);
+  await client.query("INSERT INTO store_modules (module_key) VALUES ('chess'), ('go')");
+  // Ada: 30 on task 1 (task row). Bo: a session that shipped tasks 2 and 4 → half of 20 = 10.
+  // Bo's estimate row on task 2 is a kind the rule does not count; Ada's row on task 3 is unshipped work.
+  await client.query(`INSERT INTO credit_log (builder_id, task_id, delta, reason, session_id) VALUES
+    (1, 1, 30, 'session.token_reward', NULL), (2, NULL, 20, 'session.token_reward', 's-bo'),
+    (2, 2, 500, 'task.shipped', NULL), (1, 3, 99, 'session.token_reward', NULL)`);
+  await client.query("INSERT INTO session_records (session_id, task_ids) VALUES ('s-bo', '{2,4}')");
+  await client.query(`INSERT INTO payout_approvals (kind, recipient_id, amount_cents, currency) VALUES
+    ('payout_approved', 1, 525, 'USD'), ('payout_approved', 3, 300, 'USD'), ('payout_approved', 2, 175, '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(mig('migrations', 'core_292_module_sale_payouts.sql'));
+  await client.query('BEGIN');
+
+  // ── what the database refuses ──
+  ok(code(await rejects(RULE, ['chess', 3, 3000, 6000, ['session.token_reward'], 4])) === '23514', 'a rule whose shares do not add to the whole price is refused');
+  ok(code(await rejects(RULE, ['chess', 3, 3000, 7000, [], 4])) === '23514', 'a rule that counts no credit rows is refused');
+
+  // ── the real code over the real tables ──
+  const db = { query: (s, p) => client.query(s, p) };
+  const cleared = { refuseUnclearedGates: async () => null };
+  const okGates = { gateRecipient: async () => ({ ok: true }) };
+  await M.setSplitRule({ moduleKey: 'chess', body: { seller_id: 3, seller_bps: 3000, contributors_bps: 7000 }, actorId: 4 },
+    { pool: db, gates: okGates, payTypeGates: cleared });
+  ok(code(await rejects('UPDATE module_split_rules SET seller_bps = 0, contributors_bps = 10000')) === 'P0001', 'a split rule is never edited');
+
+  const preview = await M.previewSplit('chess', { pool: db });
+  const w = Object.fromEntries(preview.contributors.map((c) => [c.builder_id, c.weight]));
+  ok(w['1'] === 30_000 && w['2'] === 10_000 && Object.keys(w).length === 2,
+    'weight counts the rule\'s row kinds on shipped module tasks, a session row in its share of the session\'s module tasks');
+
+  const processor = {
+    async readSale() { return { moduleKey: 'chess', priceCents: 1000, platformFeeCents: 40, currency: 'USD' }; },
+    async transfer(req) { return { ref: `tr_${req.moduleShareId}` }; },
+  };
+  const sale = await M.recordSale({ processorSaleRef: 'ch_1', actorId: 4 }, { pool: db, processor, account: ACCOUNT, payTypeGates: cleared });
+  const byWho = Object.fromEntries(sale.shares.map((s) => [String(s.recipient_id), Number(s.amount_cents)]));
+  ok(byWho['3'] === 300 && byWho['1'] === 525 && byWho['2'] === 175, 'the sale owes the seller 300 and the pool 525 / 175 by weight');
+  const again = await M.recordSale({ processorSaleRef: 'ch_1', actorId: 4 }, { pool: db, processor, account: ACCOUNT, payTypeGates: cleared });
+  ok(again.already === true && (await client.query('SELECT count(*)::int AS n FROM module_sales')).rows[0].n === 1, 'a repeated report records nothing new');
+  ok(code(await rejects(`INSERT INTO module_sales (module_key, processor_sale_ref, price_cents, currency, rule_id, recorded_by)
+    VALUES ('chess', 'ch_1', 5, 'USD', 1, 4)`)) === '23505', 'a second sale for one processor reference is refused');
+  ok(code(await rejects('DELETE FROM module_sale_shares_owed')) === 'P0001', 'a share is never deleted');
+
+  const shareOf = (r) => String(sale.shares.find((s) => String(s.recipient_id) === r).id);
+  const allow = { checkApproval: async () => ({ ok: true, pay_to: 'self' }) };
+  const deps = { pool: db, authority: allow, account: ACCOUNT, payTypeGates: cleared, processor };
+  const paid = await M.payShare({ shareId: shareOf('1'), approvalId: 1, actorId: 4 }, deps);
+  ok(paid.status === 'paid', 'a share is paid under its approval');
+  const twice = await M.payShare({ shareId: shareOf('1'), approvalId: 1, actorId: 4 }, deps);
+  ok(twice.already === true, 'pressing again sends nothing');
+  ok(code(await rejects("INSERT INTO module_share_attempts (share_id, outcome, processor_ref) VALUES ($1, 'sent', 'tr_x')", [shareOf('1')])) === '23505',
+    'a second sent attempt for one share is refused');
+  ok(code(await rejects('INSERT INTO module_share_approvals (share_id, approval_id, bound_by) VALUES ($1, 1, 4)', [shareOf('2')])) === '23505',
+    'one approval cannot bind two shares');
+  ok(code(await rejects('INSERT INTO builder_payouts_owed (builder_id, task_id, approval_id, amount_cents, currency, recorded_by) VALUES (1, 1, 1, 525, \'USD\', 4)')) === 'P0001',
+    'an approval spent on a share cannot also pay a task');
+
+  const mv = await client.query("SELECT kind, amount_micro, module_share_id, task_id FROM economy_project_account_movements ORDER BY id");
+  ok(mv.rows.length === 2 && mv.rows[0].kind === 'funding' && Number(mv.rows[0].amount_micro) === 10_000_000
+    && mv.rows[1].kind === 'payout' && String(mv.rows[1].module_share_id) === shareOf('1') && mv.rows[1].task_id === null,
+  'the price is booked as funding and the share as a payout naming the share, not a task');
+  ok(code(await rejects("INSERT INTO economy_project_account_movements (kind, direction, amount_micro, builder_id, processor_ref) VALUES ('payout', 'out', 1, 1, 'tr_z')")) === '23514',
+    'a payout naming neither a task nor a share is still refused');
+
+  const mine = await M.listShares(db, { recipientId: '1' });
+  ok(mine.length === 1 && mine[0].status === 'paid' && mine[0].weight === 30_000 && mine[0].weight_total === 40_000,
+    'a person sees their own share, paid, with the weight that produced it');
+
+  await client.query('ROLLBACK');
+  console.log(`module_payouts_db.mjs: ${pass} passed`);
+} finally {
+  await client.query('ROLLBACK').catch(() => {});
+  await client.query(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`).catch(() => {});
+  client.release();
+  await pgPool.end();
+}

package/tests/own_scope_guard.mjs

@@ -94,6 +94,11 @@ const OWN_SCOPED_SURFACES = [
     why: "the CALLER's own side of the payout gates (task 1004914, ADR 0385 D8): their payout standing and holds, declaring their own age tier, appealing a hold on their own pay (anyone else's answers 404, and the database refuses an appeal by anyone but the frozen person), and co-signing as themselves where the database checks they are the current guardian. Every route acts on req.builder.id. The approver's routes live apart in routes/payout-gates.js for exactly that reason.",
     crossOwner: [],
   },
+  {
+    file: 'src/bongos/routes/my-cash-outs.js',
+    why: "the CALLER's own cash-outs (task 1004911, N7): list, request, retry and cancel a withdrawal of their OWN balance to their bank. Every call passes req.builder.id as the owner; a cash-out id belonging to somebody else answers 404, and the approval it records names the caller as both approver and recipient (core_293's CHECK).",
+    crossOwner: [],
+  },
   {
     file: 'modules/specialities/routes/specialities.js',
     why: "role sub-specialities (task 1003855, ADR 0296). The own-scoped route here is GET /me/specialities — the CALLER's own adoptions, taken from req.builder.id with nothing read off the request. The rest of the router is /specialities/* rather than /me/*, and those are ownership-checked per row against req.builder.id after re-reading the speciality server-side, never from a client-supplied owner id.",

package/tests/payout_gates.mjs

@@ -26,7 +26,10 @@ const NOW = new Date('2026-10-29T12:00:00Z');
 const LATER = '2027-01-01T00:00:00Z';
 const adult = [{ id: '1', tier: 'adult' }];
 const clear = [{ id: '1', result: 'clear', screened_by: 'person:owner', valid_until: LATER }];
-const d = (f) => gates.decide({ ageRecords: adult, screenings: clear, now: NOW, ...f });
+const nda = [{ id: '1', status: 'on_file', nda_version: 'beta-v1' }];
+const tax = [{ id: '1', status: 'collected', collected_by: 'person:owner' }];
+const papers = { ndas: nda, taxDetails: tax };
+const d = (f) => gates.decide({ ageRecords: adult, screenings: clear, ...papers, now: NOW, ...f });
 
 // ── 1. the decision ──────────────────────────────────────────────────────
 {
@@ -49,7 +52,7 @@ const d = (f) => gates.decide({ ageRecords: adult, screenings: clear, now: NOW,
   assert.equal(f.reason, 'frozen'); assert.equal(f.freeze_id, '4'); ok('an open hold stops pay');
   assert.equal(d({ freezes: [{ id: '4', reason: 'manual' }], freezeEvents: [{ freeze_id: '4', kind: 'lifted' }] }).ok, true); ok('a lifted hold does not');
   assert.equal(d({ freezes: [{ id: '4' }], freezeEvents: [{ freeze_id: '4', kind: 'appealed' }] }).reason, 'frozen'); ok('an appeal alone does not lift a hold');
-  for (const r of ['sanctions_match', 'sanctions_unscreened', 'age_no_money', 'age_needs_guardian', 'age_unknown']) {
+  for (const r of ['sanctions_match', 'sanctions_unscreened', 'age_no_money', 'age_needs_guardian', 'age_unknown', 'nda_missing', 'tax_details_missing']) {
     assert.ok(gates.NOTICES[r] && gates.NOTICES[r].length >= 20 && gates.NOTICES[r].length <= 1000, r);
     assert.match(gates.NOTICES[r], /appeal/i, r);
   }
@@ -72,6 +75,8 @@ function fakeDb({ facts = {}, open = null } = {}) {
       if (/FROM payout_age_records/.test(sql)) return { rows: facts.ageRecords || [] };
       if (/FROM payout_guardians/.test(sql)) return { rows: facts.guardians || [] };
       if (/FROM payout_screenings/.test(sql)) return { rows: facts.screenings || [] };
+      if (/FROM payout_ndas/.test(sql)) return { rows: facts.ndas || [] };
+      if (/FROM payout_tax_details/.test(sql)) return { rows: facts.taxDetails || [] };
       if (/FROM payout_freezes WHERE builder_id/.test(sql)) return { rows: facts.freezes || [] };
       if (/FROM payout_freeze_events/.test(sql)) return { rows: [] };
       throw new Error('unexpected sql ' + sql);
@@ -87,10 +92,10 @@ function fakeDb({ facts = {}, open = null } = {}) {
   db = fakeDb({ facts: { ageRecords: adult, screenings: [] }, open: 55 });
   g = await gates.gateOwedPay('8', { owedCents: 500, now: NOW, pool: db.pool });
   assert.equal(g.freeze_id, '55'); ok('a second refusal for the same reason reuses the open hold');
-  db = fakeDb({ facts: { ageRecords: adult, screenings: clear } });
+  db = fakeDb({ facts: { ageRecords: adult, screenings: clear, ...papers } });
   g = await gates.gateOwedPay('8', { owedCents: 500, now: NOW, pool: db.pool });
   assert.equal(g.ok, true); assert.ok(!db.calls.some((s) => /INSERT/.test(s))); ok('payable pay files nothing');
-  db = fakeDb({ facts: { ageRecords: adult, screenings: clear, freezes: [{ id: 3, reason: 'manual' }] } });
+  db = fakeDb({ facts: { ageRecords: adult, screenings: clear, ...papers, freezes: [{ id: 3, reason: 'manual' }] } });
   g = await gates.gateOwedPay('8', { now: NOW, pool: db.pool });
   assert.equal(g.reason, 'frozen'); assert.ok(!db.calls.some((s) => /INSERT/.test(s))); ok('an existing hold is reported, not filed twice');
 }
@@ -256,7 +261,8 @@ try {
   assert.match(sql, /BEFORE UPDATE OR DELETE ON %I/); assert.match(sql, /BEFORE TRUNCATE ON %I/); ok('every gate table is append-only by trigger');
   assert.match(sql, /only the person whose pay is frozen may appeal it/); assert.match(sql, /may not decide the appeal on their own freeze/); assert.match(sql, /only the builder''s current guardian may co-sign/); ok('the database repeats who may appeal, decide and co-sign');
   for (const t of gates.AGE_TIERS) assert.ok(sql.includes(`'${t}'`), t);
-  for (const r of gates.FREEZE_REASONS) assert.ok(sql.includes(`'${r}'`), r);
+  const latestReasons = readFileSync(new URL('../migrations/core_291_payout_nda_tax.sql', import.meta.url), 'utf8');
+  for (const r of gates.FREEZE_REASONS) assert.ok(latestReasons.includes(`'${r}'`), r);
   ok('every tier and hold reason the code writes is one the table accepts');
 }
 
@@ -310,13 +316,68 @@ try {
     const rows = (t) => params[0].map((b, i) => ({ id: String(i + 1), builder_id: b, ...t }));
     if (/FROM payout_age_records/.test(q)) return { rows: rows({ tier: 'adult' }) };
     if (/FROM payout_screenings/.test(q)) return { rows: rows({ result: 'clear', screened_by: 'person:o', valid_until: LATER }) };
+    if (/FROM payout_ndas/.test(q)) return { rows: rows({ status: 'on_file', nda_version: 'beta-v1' }) };
+    if (/FROM payout_tax_details/.test(q)) return { rows: rows({ status: 'collected', collected_by: 'person:o' }) };
     return { rows: [] };
   } };
   const owed = new Map(Array.from({ length: 40 }, (_, i) => [String(100 + i), 10]));
   const out = await gates.gateOwedPayMany(owed, { now: NOW, pool });
   assert.equal(out.size, 40); assert.ok([...out.values()].every((v) => v.ok));
-  assert.equal(queries.length, 4); ok('forty recipients are checked with four reads, not four per person');
+  assert.equal(queries.length, 6); ok('forty recipients are checked with six reads, not six per person');
   assert.equal((await gates.readFacts('7', { pool })).ageRecords.length, 1); ok('a single recipient reads through the same batched path');
 }
 
+// ── 9. contractor papers: an NDA on file and tax details collected (task 1004908) ──
+{
+  assert.equal(d({ ndas: [] }).reason, 'nda_missing'); ok('no NDA on file: not paid');
+  assert.equal(d({ ndas: [...nda, { status: 'withdrawn', nda_version: 'beta-v1' }] }).reason, 'nda_missing'); ok('a withdrawn NDA stops pay again: the latest record wins');
+  assert.equal(d({ taxDetails: [] }).reason, 'tax_details_missing'); ok('tax details never collected: not paid');
+  assert.equal(d({ taxDetails: [{ status: 'incomplete', collected_by: 'person:o' }] }).reason, 'tax_details_missing'); ok('incomplete onboarding: not paid');
+  assert.equal(d({ ndas: [], taxDetails: [] }).reason, 'nda_missing'); ok('with both missing, the NDA is named first');
+  assert.equal(d({ screenings: [], ndas: [] }).reason, 'sanctions_unscreened'); ok('the papers come after age and sanctions');
+  let db = fakeDb({ facts: { ageRecords: adult, screenings: clear, ndas: nda } });
+  const g = await gates.gateOwedPay('8', { owedCents: 900, now: NOW, pool: db.pool });
+  assert.equal(g.reason, 'tax_details_missing'); assert.equal(g.freeze_id, '77'); assert.match(g.notice, /payment processor, never to us/);
+  ok('owed pay missing tax details is held with a notice, never silently');
+  const own = gates.presentOwn({ ok: false, reason: 'nda_missing', facts: { ndas: nda, taxDetails: [] } });
+  assert.equal(own.nda_on_file, true); assert.equal(own.tax_details_collected, false); ok('the person sees which paper is missing');
+
+  for (const t of ['123-45-6789', '12-3456789', 'ssn 123 45 6789', '123456789']) assert.equal(gates.looksLikeTaxId(t), true, t);
+  for (const t of ['acct_1Nv0FGQ9RKHg', 'onboarding-2026-11-02', 'env_ab12cd34']) assert.equal(gates.looksLikeTaxId(t), false, t);
+  assert.throws(() => gates.recordTaxDetails({ builderId: '8', status: 'collected', collectedBy: 'person:o', reference: '123-45-6789', recordedBy: '7' }, { pool: { query: async () => { throw new Error('must not reach the database'); } } }), /tax id/);
+  ok('a reference shaped like a tax id is refused before it reaches the database');
+
+  const wrote = [];
+  const g2 = { ...gates, recordNda: async (r) => { wrote.push(['nda', r]); return { id: '1' }; }, recordTaxDetails: async (r) => { wrote.push(['tax', r]); return { id: '2' }; } };
+  let as = { builder: { id: '7', github_login: 'owner' }, gdsSession: { source: 'web', session_id: '1' } };
+  const perms = [];
+  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('/', buildGates({ gates: g2, requireBuilder: (q, r, nx) => nx(), requirePermission: (...p) => { perms.push(p.join(',')); return (q, r, nx) => nx(); } }));
+  const srv = http.createServer(a).listen(0);
+  const post = (path, body) => new Promise((resolve) => { const r = http.request({ port: srv.address().port, path, method: 'POST', headers: { 'content-type': 'application/json' } }, (res) => { let t = ''; res.on('data', (c) => (t += c)); res.on('end', () => resolve({ status: res.statusCode, body: JSON.parse(t) })); }); r.write(JSON.stringify(body)); r.end(); });
+  let r = await post('/payouts/ndas', { builder_id: 8, status: 'on_file', nda_version: 'beta-v1', reference: 'envelope-test-1' });
+  assert.equal(r.status, 201); assert.deepEqual(wrote.pop(), ['nda', { builderId: 8, status: 'on_file', ndaVersion: 'beta-v1', reference: 'envelope-test-1', recordedBy: '7' }]); ok('an approver records an NDA on file, with where the signed copy lives');
+  assert.equal((await post('/payouts/ndas', { builder_id: 8, status: 'signed', nda_version: 'beta-v1' })).body.error, 'bad_status'); ok('an unknown NDA status is refused');
+  assert.equal((await post('/payouts/ndas', { builder_id: 8, status: 'on_file', nda_version: 'beta v1; drop' })).body.error, 'bad_nda_version'); ok('an NDA version is a short label, not free text');
+  assert.equal((await post('/payouts/ndas', { builder_id: 7, status: 'on_file', nda_version: 'beta-v1' })).body.error, 'own_papers'); ok('nobody records their own NDA');
+  r = await post('/payouts/tax-details', { builder_id: 8, status: 'collected', reference: 'acct_test_onboarding' });
+  assert.equal(r.status, 201); assert.deepEqual(wrote.pop(), ['tax', { builderId: 8, status: 'collected', collectedBy: 'person:owner', reference: 'acct_test_onboarding', recordedBy: '7' }]); ok('an approver records that the processor collected the tax details');
+  r = await post('/payouts/tax-details', { builder_id: 8, status: 'collected', reference: '123-45-6789' });
+  assert.equal(r.body.error, 'tax_id_refused'); assert.equal(wrote.length, 0); ok('a tax id sent as the reference is refused and nothing is written');
+  assert.equal((await post('/payouts/tax-details', { builder_id: 7, status: 'collected' })).body.error, 'own_papers'); ok('nobody records their own tax details');
+  as = { builder: { id: '7', github_login: 'owner' }, gdsSession: { source: 'cli', session_id: '1' } };
+  assert.equal((await post('/payouts/ndas', { builder_id: 8, status: 'on_file', nda_version: 'beta-v1' })).status, 403);
+  assert.equal((await post('/payouts/tax-details', { builder_id: 8, status: 'collected' })).status, 403); ok('a command-line or AI session records neither paper');
+  srv.close();
+  assert.ok(perms.length >= 2 && perms.every((p) => p === 'payout.approve')); ok('both routes need payout.approve');
+
+  const sql = readFileSync(new URL('../migrations/core_291_payout_nda_tax.sql', import.meta.url), 'utf8');
+  for (const t of ['payout_ndas', 'payout_tax_details']) assert.ok(sql.includes(`'${t}'`), t);
+  assert.match(sql, /BEFORE UPDATE OR DELETE ON %I/); ok('both paper tables are append-only by trigger');
+  assert.match(sql, /payout_tax_details_no_tax_id CHECK/); assert.doesNotMatch(sql, /(tin|ssn|ein|tax_id)s+text/i); ok('the database has no column for a tax id and refuses one in the reference');
+  for (const st of [...gates.NDA_STATUSES, ...gates.TAX_STATUSES]) assert.ok(sql.includes(`'${st}'`), st);
+  ok('every paper status the code writes is one the tables accept');
+}
+
 console.log(`\n${n} passed`);