@bongos/core 1.24.23 → 1.24.24

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`);

package/tests/payout_gates_db.mjs

@@ -37,7 +37,7 @@ 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, system_role text)');
-  for (const m of ['core_283_payout_approvals.sql', 'core_284_payout_gates.sql']) {
+  for (const m of ['core_283_payout_approvals.sql', 'core_284_payout_gates.sql', 'core_291_payout_nda_tax.sql']) {
     await client.query(readFileSync(join(here, '..', 'migrations', m), 'utf8'));
   }
   // 1 owner, 2 a 16-17 builder, 3 their guardian, 4 an adult, 5 someone else
@@ -69,6 +69,20 @@ try {
   await refused("INSERT INTO payout_freeze_events (freeze_id, kind, actor_id, statement) VALUES ($1, 'lifted', 4, 'x')", [v.freeze_id], 'the frozen person cannot lift their own hold');
 
   await g.recordScreening({ builderId: 4, result: 'clear', screenedBy: 'person:owner', validUntil: new Date(Date.now() + 86_400_000).toISOString(), recordedBy: 1 }, o);
+
+  // contractor papers (task 1004908): an NDA on file and tax details collected
+  await refused("INSERT INTO payout_ndas (builder_id, status, nda_version, recorded_by) VALUES (4, 'on_file', 'beta-v1', 4)", [], 'nobody records their own NDA');
+  await refused("INSERT INTO payout_ndas (builder_id, status, nda_version, recorded_by) VALUES (4, 'signed', 'beta-v1', 1)", [], 'an unknown NDA status is refused');
+  await refused("INSERT INTO payout_tax_details (builder_id, status, collected_by, reference, recorded_by) VALUES (4, 'collected', 'person:owner', 'tin 123-45-6789', 1)", [], 'a tax id in the reference is refused by the database');
+  await refused("INSERT INTO payout_tax_details (builder_id, status, collected_by, recorded_by) VALUES (4, 'collected', 'person:owner', 4)", [], 'nobody records their own tax details');
+  const nda = await g.recordNda({ builderId: 4, status: 'on_file', ndaVersion: 'beta-v1', reference: 'envelope-test-1', recordedBy: 1 }, o);
+  await refused('UPDATE payout_ndas SET status = $1 WHERE id = $2', ['withdrawn', nda.id], 'an NDA record cannot be edited');
+  const p = await g.gateOwedPay(4, { owedCents: 300, pool: client });
+  ok(p.reason === 'frozen', 'papers do not lift an open hold either');
+  await g.recordTaxDetails({ builderId: 4, status: 'incomplete', collectedBy: 'person:owner', reference: 'acct_test_onboarding', recordedBy: 1 }, o);
+  await g.recordTaxDetails({ builderId: 4, status: 'collected', collectedBy: 'person:owner', reference: 'acct_test_onboarding', recordedBy: 1 }, o);
+  // after rows exist: the refuse-change trigger is per-row, so a DELETE on an empty table has nothing to refuse (task 1005039)
+  await refused('DELETE FROM payout_tax_details', [], 'tax-detail records cannot be deleted');
   ok((await g.gateOwedPay(4, { pool: client })).reason === 'frozen', 'a clear screening does not lift a hold by itself: a person does');
   await g.addFreezeEvent({ freezeId: v.freeze_id, kind: 'lifted', actorId: 1, statement: 'Screening came back clear.' }, o);
   await refused("INSERT INTO payout_freeze_events (freeze_id, kind, actor_id, statement) VALUES ($1, 'upheld', 1, 'x')", [v.freeze_id], 'nothing follows a lift');
@@ -82,6 +96,14 @@ try {
   await refused("INSERT INTO payout_guardians (builder_id, guardian_id, active, recorded_by) VALUES (2, 3, true, 1)", [], 'an active guardian link must name the guardian-controlled account');
   await refused("INSERT INTO payout_guardians (builder_id, guardian_id, guardian_account, active, recorded_by) VALUES (2, 2, 'acct', true, 1)", [], 'nobody is their own guardian');
   await g.recordGuardian({ builderId: 2, guardianId: 3, guardianAccount: 'acct_guardian', active: true, recordedBy: 1 }, o);
+  ok((await g.gateRecipient(2, o)).reason === 'nda_missing', 'with no NDA on file, not payable');
+  await g.recordNda({ builderId: 2, status: 'on_file', ndaVersion: 'beta-v1', reference: null, recordedBy: 1 }, o);
+  v = await g.gateOwedPay(2, { owedCents: 400, pool: client });
+  ok(v.reason === 'tax_details_missing' && v.freeze_id, 'with no tax details collected, owed pay is held and told why');
+  const paperHold = await g.readFreeze(v.freeze_id, o);
+  ok(paperHold.reason === 'tax_details_missing' && paperHold.notice_text === g.NOTICES.tax_details_missing, 'the hold table accepts the new reason, with its notice');
+  await g.addFreezeEvent({ freezeId: v.freeze_id, kind: 'lifted', actorId: 1, statement: 'Onboarding finished.' }, o);
+  await g.recordTaxDetails({ builderId: 2, status: 'collected', collectedBy: 'person:owner', reference: 'acct_test_ward', recordedBy: 1 }, o);
   v = await g.gateRecipient(2, o);
   ok(v.ok && v.needs_guardian_cosign && v.pay_to.guardian_account === 'acct_guardian', '16-17 with a guardian is paid only into the guardian\'s account, co-signed');
 

package/tests/project_account_db.mjs

@@ -18,7 +18,9 @@ const require = createRequire(import.meta.url);
 const { Pool } = require('pg');
 const A = require('../modules/economy/project-account.js');
 const here = dirname(fileURLToPath(import.meta.url));
-const MIGRATION = readFileSync(join(here, '..', 'modules', 'economy', 'migrations', 'economy_002_project_account.sql'), 'utf8');
+// economy_004 (task 1004910) adds module_share_id, which recordMovement writes.
+const MIGRATION = ['economy_002_project_account.sql', 'economy_004_module_share_payouts.sql']
+  .map((f) => readFileSync(join(here, '..', 'modules', 'economy', 'migrations', f), 'utf8')).join('\n');
 
 const pgPool = new Pool({ connectionString: process.env.DATABASE_URL || undefined, max: 1 });
 let client;
@@ -45,7 +47,8 @@ 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)');
+  // status: a hold counts only while its task is being worked (task 1003185)
+  await client.query("CREATE TABLE tasks (id bigserial PRIMARY KEY, title text, status text NOT NULL DEFAULT 'active')");
   await client.query('CREATE TABLE schema_migrations (version text PRIMARY KEY)');
   await client.query("INSERT INTO builders (display_name) VALUES ('Ada'), ('Owner')");
   await client.query("INSERT INTO tasks (title) VALUES ('Build the thing')");

package/tests/project_outflow.mjs

@@ -0,0 +1,103 @@
+// tests/project_outflow.mjs — where the money went (task 1003184, goal 1000092 M05;
+// criterion money-outflow-visible). Behaviour of modules/economy/outflow.js's shapeOutflow:
+//   - a debt with no sent attempt is committed, and so is an approval nothing was booked against;
+//   - the balance left after commitments subtracts both, and goes negative when it must;
+//   - holds are shown but never subtracted twice (available already excludes them);
+//   - a commitment in another currency is counted, never added to a dollar figure;
+//   - per-builder totals sum spend, paid, owed and approved, biggest first;
+//   - each month's burn is its spend plus money out of the account.
+// The SQL is proven against real Postgres in tests/project_outflow_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 { shapeOutflow } = require('../modules/economy/outflow.js');
+
+const account = (recorded, held = 0) => ({ recorded_balance_micro: String(recorded), held_micro: String(held) });
+const base = {
+  burn: [], payouts: [], approved: [], spendByBuilder: [], spendTotal: '0',
+  account: account(0), names: [{ id: '1', display_name: 'Ada' }, { id: '2', display_name: 'Bo' }],
+};
+const owed = (id, builder, cents, paid = false, extra = {}) => ({
+  id, builder_id: builder, task_id: 90 + id, task_title: `task ${id}`, amount_cents: String(cents),
+  currency: 'USD', created_at: `2026-10-0${id}T00:00:00Z`, paid, ...extra,
+});
+
+test('a balance that owes three payouts shows what is left after them', () => {
+  const out = shapeOutflow({
+    ...base,
+    account: account(100_000_000),
+    payouts: [owed(1, '1', 3000), owed(2, '1', 3000), owed(3, '2', 3000), owed(4, '2', 5000, true)],
+  });
+  assert.equal(out.committed.owed_count, 3);
+  assert.equal(out.committed.owed_micro, 90_000_000);
+  assert.equal(out.balance.available_micro, 100_000_000);
+  assert.equal(out.balance.after_commitments_micro, 10_000_000);
+  assert.equal(out.totals.paid_micro, 50_000_000, 'a sent payout is paid, not owed');
+  assert.deepEqual(out.committed.owed.map((r) => r.owed_id), ['1', '2', '3'], 'oldest debt first');
+  assert.equal(out.committed.owed[0].builder_name, 'Ada');
+});
+
+test('an approval with no payout booked is committed too, and can push the balance below zero', () => {
+  const out = shapeOutflow({
+    ...base,
+    account: account(10_000_000),
+    approved: [{ id: 7, builder_id: '2', amount_cents: '2500', currency: 'USD' }],
+  });
+  assert.equal(out.committed.approved_count, 1);
+  assert.equal(out.committed.approved_micro, 25_000_000);
+  assert.equal(out.committed.total_micro, 25_000_000);
+  assert.equal(out.balance.after_commitments_micro, -15_000_000);
+});
+
+test('holds are shown and already out of available, so they are not subtracted again', () => {
+  const out = shapeOutflow({ ...base, account: account(50_000_000, 20_000_000), payouts: [owed(1, '1', 1000)] });
+  assert.equal(out.committed.held_micro, 20_000_000);
+  assert.equal(out.balance.available_micro, 30_000_000);
+  assert.equal(out.balance.after_commitments_micro, 20_000_000);
+  assert.equal(out.committed.total_micro, 10_000_000, 'the committed total is owed + approved only');
+});
+
+test('another currency is counted, never added to a dollar figure', () => {
+  const out = shapeOutflow({
+    ...base,
+    payouts: [owed(1, '1', 1000, false, { currency: 'EUR' }), owed(2, '1', 1000, true, { currency: 'EUR' })],
+    approved: [{ id: 8, builder_id: '1', amount_cents: '900', currency: 'GBP' }],
+  });
+  assert.equal(out.committed.owed_micro, 0);
+  assert.equal(out.committed.approved_micro, 0);
+  assert.equal(out.committed.other_currency_count, 2, 'unpaid EUR debt and GBP approval; a paid one is not a commitment');
+  assert.deepEqual(out.by_builder, []);
+});
+
+test('per-builder totals add spend, paid, owed and approved, biggest first', () => {
+  const out = shapeOutflow({
+    ...base,
+    spendByBuilder: [{ builder_id: '1', spend_micro: '4000000' }, { builder_id: '3', spend_micro: '0' }],
+    payouts: [owed(1, '2', 1000, true), owed(2, '2', 500)],
+    approved: [{ id: 9, builder_id: '1', amount_cents: '100', currency: 'USD' }],
+  });
+  assert.deepEqual(out.by_builder.map((b) => [b.builder_id, b.total_micro]), [['2', 15_000_000], ['1', 5_000_000]]);
+  const bo = out.by_builder[0];
+  assert.equal(bo.builder_name, 'Bo');
+  assert.equal(bo.paid_micro, 10_000_000);
+  assert.equal(bo.owed_micro, 5_000_000);
+  assert.ok(!out.by_builder.some((b) => b.builder_id === '3'), 'a builder with nothing is left out');
+});
+
+test('each month burns its spend plus money out of the account', () => {
+  const out = shapeOutflow({
+    ...base,
+    burn: [
+      { month: '2026-10', spend_micro: '1500000', payouts_micro: '3000000', other_out_micro: '200000' },
+      { month: '2026-11', spend_micro: '0', payouts_micro: '0', other_out_micro: '0' },
+    ],
+    spendTotal: '9000000',
+  });
+  assert.deepEqual(out.burn.months.map((m) => m.total_micro), [4_700_000, 0]);
+  assert.equal(out.burn.window_total_micro, 4_700_000);
+  assert.equal(out.totals.spend_micro, 9_000_000);
+  assert.equal(out.holds_money, false);
+});

package/tests/project_outflow_db.mjs

@@ -0,0 +1,100 @@
+// tests/project_outflow_db.mjs — task 1003184 (goal 1000092 M05). Real DB.
+//
+// Applies the REAL project-account and builder-payout migrations (economy_002, core_290) over
+// minimal builders / tasks / cost_log / payout_approvals tables, books a small history through
+// the real recordMovement, and proves the real readOutflow's SQL: a sent payout is paid, an
+// owed one with only a failed try is committed, an approval with no payout booked is committed,
+// the months run gap-free to this month, spend lands on its month and its builder, and the
+// balance after commitments is the account less every commitment.
+//
+// Self-skips without a reachable Postgres. `seed` and `check` are exported so the same scenario
+// can be driven through any { query } client.
+// Run:  DATABASE_URL=... node tests/project_outflow_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 A = require('../modules/economy/project-account.js');
+const { readOutflow } = require('../modules/economy/outflow.js');
+const here = dirname(fileURLToPath(import.meta.url));
+const read = (...p) => readFileSync(join(here, '..', ...p), 'utf8');
+const ACCOUNT_SQL = read('modules', 'economy', 'migrations', 'economy_002_project_account.sql')
+  + read('modules', 'economy', 'migrations', 'economy_004_module_share_payouts.sql');
+const PAYOUTS_SQL = read('migrations', 'core_290_builder_payouts.sql');
+
+export async function seed(q) {
+  await q.query('CREATE TABLE builders (id bigserial PRIMARY KEY, display_name text, github_login text)');
+  // status: a hold counts only while its task is being worked (task 1003185)
+  await q.query("CREATE TABLE tasks (id bigserial PRIMARY KEY, title text, status text NOT NULL DEFAULT 'active')");
+  await q.query('CREATE TABLE schema_migrations (version text PRIMARY KEY)');
+  await q.query(`CREATE TABLE cost_log (id bigserial PRIMARY KEY, amount_usd numeric(10,4) NOT NULL,
+    builder_id bigint, recorded_at timestamptz NOT NULL DEFAULT now())`);
+  await q.query(`CREATE TABLE payout_approvals (id bigserial PRIMARY KEY, kind text NOT NULL,
+    recipient_id bigint, amount_cents bigint, currency text, created_at timestamptz NOT NULL DEFAULT now())`);
+  await q.query(ACCOUNT_SQL);
+  // core_292's binding table, which the approved read excludes (task 1004910)
+  await q.query('CREATE TABLE module_share_approvals (share_id bigint PRIMARY KEY, approval_id bigint NOT NULL UNIQUE)');
+  await q.query(PAYOUTS_SQL);
+  await q.query("INSERT INTO builders (display_name) VALUES ('Ada'), ('Bo'), ('Owner')");
+  await q.query("INSERT INTO tasks (title) VALUES ('Paid task'), ('Owed task'), ('Approved task')");
+  // approvals: 1 paid, 2 owed (failed once), 3 approved and never booked, 4 approved in EUR
+  await q.query(`INSERT INTO payout_approvals (kind, recipient_id, amount_cents, currency) VALUES
+    ('payout_approved', 1, 4000, 'USD'), ('payout_approved', 2, 3000, 'USD'),
+    ('payout_approved', 2, 2000, 'USD'), ('payout_approved', 1, 900, 'EUR'),
+    ('rule_signed', NULL, NULL, NULL)`);
+  await q.query(`INSERT INTO builder_payouts_owed (builder_id, task_id, approval_id, amount_cents, currency, recorded_by)
+    VALUES (1, 1, 1, 4000, 'USD', 3), (2, 2, 2, 3000, 'USD', 3)`);
+  await q.query(`INSERT INTO builder_payout_attempts (owed_id, outcome, processor_ref, reason) VALUES
+    (1, 'failed', NULL, 'timeout'), (1, 'sent', 'tr_1', NULL), (2, 'failed', NULL, 'card declined')`);
+  await A.recordMovement(q, { kind: 'funding', amountMicro: 100_000_000, processorRef: 'ch_1' });
+  await A.recordMovement(q, { kind: 'payout', amountMicro: 40_000_000, builderId: 1, taskId: 1, processorRef: 'tr_1' });
+  await A.recordMovement(q, { kind: 'fee', amountMicro: 1_000_000, processorRef: 'fee_1' });
+  await q.query(`INSERT INTO cost_log (amount_usd, builder_id, recorded_at) VALUES
+    (2.5, 1, now()), (1.25, NULL, now()), (7, 2, now() - interval '400 days')`);
+}
+
+export async function check(q, ok) {
+  const out = await readOutflow(q, { months: 3 });
+  ok(out.burn.months.length === 3, 'the window holds every month, quiet ones included');
+  const thisMonth = out.burn.months[2];
+  ok(thisMonth.spend_micro === 3_750_000, `this month's spend is summed from cost_log (${thisMonth.spend_micro})`);
+  ok(thisMonth.payouts_micro === 40_000_000 && thisMonth.other_out_micro === 1_000_000, 'payouts and fees out of the account land on their month');
+  ok(out.totals.spend_micro === 10_750_000, 'total spend covers all time, not just the window');
+  ok(out.totals.paid_micro === 40_000_000, 'only the debt with a sent attempt is paid');
+  ok(out.committed.owed_count === 1 && out.committed.owed[0].task_title === 'Owed task', 'a debt whose last try failed is still owed');
+  ok(out.committed.owed[0].last_reason === 'card declined', 'the owed row carries its latest try');
+  ok(out.committed.approved_count === 1 && out.committed.approved_micro === 20_000_000, 'an approval nothing was booked against is committed; a rule is not');
+  ok(out.committed.other_currency_count === 1, 'the EUR approval is counted, not added');
+  ok(out.balance.available_micro === 59_000_000, 'available is the account record');
+  ok(out.balance.after_commitments_micro === 9_000_000, 'after commitments = available − owed − approved');
+  const bo = out.by_builder.find((b) => b.builder_name === 'Bo');
+  ok(bo && bo.spend_micro === 7_000_000 && bo.owed_micro === 30_000_000 && bo.approved_micro === 20_000_000, 'per-builder totals read every record');
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const { Pool } = require('pg');
+  const pgPool = new Pool({ connectionString: process.env.DATABASE_URL || undefined, max: 1 });
+  let client;
+  try { client = await pgPool.connect(); } catch (e) {
+    console.log(`project_outflow_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+    await pgPool.end().catch(() => {});
+    process.exit(0);
+  }
+  const SCHEMA = `t1003184_${process.pid}`;
+  let pass = 0;
+  const ok = (c, m) => { assert.ok(c, m); pass++; console.log(`  ok - ${m}`); };
+  try {
+    await client.query(`CREATE SCHEMA ${SCHEMA}`);
+    await client.query(`SET search_path TO ${SCHEMA}`);
+    const q = { query: (s, p) => client.query(s, p) };
+    await seed(q);
+    await check(q, ok);
+    console.log(`project_outflow_db.mjs: ${pass} passed`);
+  } finally {
+    await client.query(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`).catch(() => {});
+    client.release();
+    await pgPool.end();
+  }
+}