@bongos/core 1.24.23 → 1.24.24

package/src/bongos/module-payouts.js

@@ -0,0 +1,432 @@
+'use strict';
+
+// src/bongos/module-payouts.js — A MODULE SALE IS SPLIT BY THE PROJECT'S RULE, AND EACH
+// CONTRIBUTOR AND THE SELLER IS PAID THEIR SHARE, EXACTLY ONCE (task 1004910, goal 1000092
+// N6; ADR 0388, ADR 0385 D4, ADR 0387 D5, ADR 0397 D7).
+//
+// THE MONEY PATH (ADR 0388 D5). The buyer pays the price plus the platform fee on top; the
+// fee goes to the platform as the processor's application fee and is never in the split
+// (D1). The price lands in the project's processor-held account, and from there each share
+// is a processor transfer to one person, under that person's own logged approval, through
+// the same steps as a task payout (builder-payouts.js, M04): the debt first, then the
+// authority, then the send under a lock with an idempotency key derived from the debt.
+//
+// THREE STEPS, EACH ITS OWN CALL:
+//   1. setSplitRule — the project's authorised person records the seller and the shares, in
+//      basis points of the price (they add to 10000), and which credit row kinds weigh the
+//      contributors' pool (default: the session cost-plus rows, ADR 0387 D5). Refused until
+//      the module_share pay-type gate is cleared: the standard module licence, the takedown
+//      contact and payee onboarding (ADR 0388 D7). The seller must pass the payout gates
+//      (age, sanctions) when the listing is set up, not first at payday.
+//   2. recordSale — the processor's reported sale (read through the processor port, never a
+//      figure from a screen) is recorded with the rule it sold under, and every share is
+//      written as owed in the same transaction. One sale per processor reference, so a
+//      repeated report finds the sale already there.
+//   3. payShare — one share, one approval. The approval must name exactly this person and
+//      amount; it is bound to the share once, and the database refuses an approval already
+//      spent on a task or another share (core_292). Then the gates are read again and the
+//      processor is asked to transfer.
+//
+// WEIGHT (ADR 0388 D3). A contributor's weight is the credit they earned on the module's
+// own SHIPPED tasks (tasks.module_key), counting only the rule's row kinds. A session
+// reward row carries no task, so it counts in the share of its session's shipped tasks that
+// are on the module. Weight is kept in milli-credits so that apportioning stays whole. Every
+// input is on the share row, so a person can check their amount.
+//
+// WHAT THIS IS NOT. It holds no money, names no processor and suggests no percentage. With
+// no processor connected nothing is read or sent: a sale cannot be recorded, and a share is
+// held `no_processor` and stays owed. Refunds (ADR 0388 D6) are not handled here yet.
+
+const seams = require('../module-seams');
+const payouts = require('./builder-payouts');
+
+const { PayoutRefusal, inTx, withTimeout, clip, MICRO_PER_CENT, CURRENCY, TRANSFER_TIMEOUT_MS } = payouts;
+const LOCK_SPACE = 1004910;
+const BPS = 10_000;
+const MILLI = 1000;
+const DEFAULT_ROW_KINDS = Object.freeze(['session.token_reward']);
+const ROW_KIND_RE = /^[a-z_.]{1,40}$/;
+const MODULE_KEY_RE = /^[a-z][a-z0-9-]{0,63}$/;
+
+const isId = (v) => (typeof v === 'number' && Number.isSafeInteger(v) && v > 0) || (typeof v === 'string' && /^[1-9][0-9]{0,18}$/.test(v));
+const isBps = (v) => Number.isSafeInteger(v) && v >= 0 && v <= BPS;
+
+// Plain words for the reasons a share waits, beside M04's own.
+const HELD_WORDS = Object.freeze({
+  ...payouts.HELD_WORDS,
+  module_share_gate: 'Module sales are not switched on yet: the standard module licence, the takedown contact or payee onboarding is not recorded. The share stays owed.',
+});
+
+const shareKey = (shareId) => `bongos-module-share-${shareId}`;
+
+// ── pure half ────────────────────────────────────────────────────────────────
+
+// A split rule's body, strictly. Returns { rule } or { errors }.
+function validateSplitRule(raw) {
+  const errors = [];
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { errors: ['the rule must be an object'] };
+  for (const k of Object.keys(raw)) {
+    if (!['seller_id', 'seller_bps', 'contributors_bps', 'credit_row_kinds'].includes(k)) errors.push(`unknown field: ${k}`);
+  }
+  if (!isId(raw.seller_id)) errors.push('seller_id must be a builder id');
+  if (!isBps(raw.seller_bps)) errors.push('seller_bps must be a whole number from 0 to 10000');
+  if (!isBps(raw.contributors_bps)) errors.push('contributors_bps must be a whole number from 0 to 10000');
+  if (isBps(raw.seller_bps) && isBps(raw.contributors_bps) && raw.seller_bps + raw.contributors_bps !== BPS) {
+    errors.push('seller_bps and contributors_bps must add up to 10000 (the whole price; the platform fee is paid on top)');
+  }
+  let kinds = DEFAULT_ROW_KINDS.slice();
+  if (raw.credit_row_kinds !== undefined) {
+    const k = raw.credit_row_kinds;
+    if (!Array.isArray(k) || k.length < 1 || k.length > 10 || k.some((x) => typeof x !== 'string' || !ROW_KIND_RE.test(x))) {
+      errors.push('credit_row_kinds must name 1 to 10 credit row kinds');
+    } else {
+      kinds = [...new Set(k)].sort();
+    }
+  }
+  if (errors.length) return { errors };
+  return { rule: { seller_id: String(raw.seller_id), seller_bps: raw.seller_bps, contributors_bps: raw.contributors_bps, credit_row_kinds: kinds } };
+}
+
+// splitSale({ priceCents, rule, weights }) → { shares, pool_unassigned_cents }. The seller
+// gets their basis points of the price rounded down; the pool is the rest, so nothing is
+// lost to rounding. The pool is divided by weight with largest remainders (ties to the
+// lower builder id). A pool with no weighted contributor is left unassigned in the
+// project's account, never handed to anyone by default. Zero-cent shares are dropped.
+function splitSale({ priceCents, rule, weights }) {
+  const sellerCents = Math.floor((priceCents * rule.seller_bps) / BPS);
+  const poolCents = priceCents - sellerCents;
+  const shares = [];
+  if (sellerCents > 0) {
+    shares.push({ recipient_id: String(rule.seller_id), role: 'seller', amount_cents: sellerCents, weight: null, weight_total: null });
+  }
+  const ws = (weights || [])
+    .map((w) => ({ id: String(w.builder_id), weight: Number(w.weight) }))
+    .filter((w) => Number.isSafeInteger(w.weight) && w.weight > 0)
+    .sort((a, b) => (BigInt(a.id) < BigInt(b.id) ? -1 : 1));
+  const total = ws.reduce((s, w) => s + w.weight, 0);
+  if (poolCents === 0 || total === 0) return { shares, pool_unassigned_cents: poolCents };
+
+  const parts = ws.map((w) => {
+    const exact = (poolCents * w.weight) / total;
+    return { ...w, cents: Math.floor(exact), rem: exact - Math.floor(exact) };
+  });
+  let left = poolCents - parts.reduce((s, p) => s + p.cents, 0);
+  for (const p of [...parts].sort((a, b) => b.rem - a.rem)) {
+    if (left <= 0) break;
+    p.cents += 1;
+    left -= 1;
+  }
+  for (const p of parts) {
+    if (p.cents > 0) shares.push({ recipient_id: p.id, role: 'contributor', amount_cents: p.cents, weight: p.weight, weight_total: total });
+  }
+  return { shares, pool_unassigned_cents: 0 };
+}
+
+// ── db half (pool and ports injectable; tests hand in stand-ins) ─────────────
+
+function defaultPool() { return require('./pool').pool; }
+function defaultAuthority() { return require('./payout-approvals'); }
+function defaultGates() { return require('./payout-gates'); }
+function defaultAccount() { return seams.resolveOptional('economy.account'); }
+function defaultPayTypeGates() { return seams.resolveOptional('lifecycle.payTypeGates'); }
+
+// null when module_share is cleared, else the reason it is not. With the lifecycle module
+// off there is no gate to read, and that is a no.
+async function moduleShareGate(payTypeGates, db) {
+  if (!payTypeGates || typeof payTypeGates.refuseUnclearedGates !== 'function') {
+    return { code: 'pay_type_gate_not_cleared', missing: ['unknown'], message: 'The pay-type gates cannot be read, so module sales stay off.' };
+  }
+  return payTypeGates.refuseUnclearedGates([{ pay_type: 'module_share' }], { db });
+}
+
+// Weight per builder for one module, in milli-credits, from the rule's row kinds. Every
+// step is an index lookup (core_292 adds the two that were missing): the module's shipped
+// tasks by idx_tasks_shipped_module, their task rows by idx_credit_log_task, the sessions
+// that shipped any of them by the GIN index on session_records.task_ids, and those
+// sessions' rows by idx_credit_log_session. Nothing scans the whole ledger.
+const WEIGHTS_SQL = `
+  WITH mt AS (SELECT id FROM tasks WHERE module_key = $1 AND status = 'shipped'),
+  direct AS (
+    SELECT builder_id, SUM(delta)::numeric * $3 AS w
+      FROM credit_log WHERE task_id IN (SELECT id FROM mt) AND reason = ANY($2::text[])
+     GROUP BY builder_id),
+  ss AS (
+    SELECT sr.session_id,
+           (SELECT count(*) FROM unnest(sr.task_ids) t WHERE t IN (SELECT id FROM mt))::numeric
+             / cardinality(sr.task_ids) AS part
+      FROM session_records sr
+     WHERE sr.task_ids && (SELECT array_agg(id) FROM mt)),
+  sess AS (
+    SELECT cl.builder_id, SUM(cl.delta::numeric * $3 * ss.part) AS w
+      FROM ss JOIN credit_log cl ON cl.session_id = ss.session_id
+     WHERE cl.task_id IS NULL AND cl.reason = ANY($2::text[])
+     GROUP BY cl.builder_id)
+  SELECT builder_id, floor(SUM(w))::bigint AS weight
+    FROM (SELECT * FROM direct UNION ALL SELECT * FROM sess) x
+   GROUP BY builder_id
+  HAVING floor(SUM(w)) > 0`;
+
+async function readWeights(db, moduleKey, kinds) {
+  const { rows } = await db.query(WEIGHTS_SQL, [moduleKey, kinds, MILLI]);
+  return rows.map((r) => ({ builder_id: String(r.builder_id), weight: Number(r.weight) }));
+}
+
+const RULE_COLS = 'id, module_key, seller_id, seller_bps, contributors_bps, credit_row_kinds, set_by, created_at';
+
+async function readSplitRule(moduleKey, { pool = defaultPool() } = {}) {
+  const { rows } = await pool.query(
+    `SELECT ${RULE_COLS} FROM module_split_rules WHERE module_key = $1 ORDER BY created_at DESC, id DESC LIMIT 1`, [moduleKey]);
+  const r = rows[0];
+  return r ? { ...r, id: String(r.id), seller_id: String(r.seller_id), set_by: String(r.set_by) } : null;
+}
+
+// The rule and the contributors' shares it would give now, for the people they affect to
+// see before any money moves (ADR 0388 D3, Art. VIII).
+async function previewSplit(moduleKey, { pool = defaultPool() } = {}) {
+  if (typeof moduleKey !== 'string' || !MODULE_KEY_RE.test(moduleKey)) throw new PayoutRefusal('bad_module_key', 'That is not a module key.');
+  const rule = await readSplitRule(moduleKey, { pool });
+  const kinds = rule ? rule.credit_row_kinds : DEFAULT_ROW_KINDS.slice();
+  const weights = await readWeights(pool, moduleKey, kinds);
+  const total = weights.reduce((s, w) => s + w.weight, 0);
+  return {
+    module_key: moduleKey,
+    rule,
+    credit_row_kinds: kinds,
+    weight_unit: 'milli-credits',
+    contributors: weights.map((w) => ({ ...w, pool_share: total ? w.weight / total : 0 })),
+  };
+}
+
+async function setSplitRule({ moduleKey, body, actorId }, {
+  pool = defaultPool(), gates = defaultGates(), payTypeGates = defaultPayTypeGates(),
+} = {}) {
+  if (typeof moduleKey !== 'string' || !MODULE_KEY_RE.test(moduleKey)) throw new PayoutRefusal('bad_module_key', 'That is not a module key.');
+  if (!isId(actorId)) throw new PayoutRefusal('no_actor', 'A split rule is recorded by a signed-in person.', 403);
+  const v = validateSplitRule(body);
+  if (v.errors) throw new PayoutRefusal('bad_split_rule', v.errors.join('; '));
+  const mod = (await pool.query('SELECT module_key, status FROM store_modules WHERE module_key = $1', [moduleKey])).rows[0];
+  if (!mod) throw new PayoutRefusal('no_such_module', 'The store has no module with that key.', 404);
+  if (mod.status !== 'listed') throw new PayoutRefusal('module_delisted', 'This module is delisted, so it takes no new split rule.', 409);
+  const gate = await moduleShareGate(payTypeGates, pool);
+  if (gate) throw new PayoutRefusal('module_share_gate', gate.message, 409);
+  const seller = await gates.gateRecipient(v.rule.seller_id, { pool });
+  if (!seller || !seller.ok) {
+    throw new PayoutRefusal('seller_gated', 'The seller cannot be paid right now (age or sanctions check), so the listing cannot take this rule.', 409);
+  }
+  const { rows } = await pool.query(
+    `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) RETURNING ${RULE_COLS}`,
+    [moduleKey, v.rule.seller_id, v.rule.seller_bps, v.rule.contributors_bps, v.rule.credit_row_kinds, actorId]);
+  return { ...rows[0], id: String(rows[0].id), seller_id: String(rows[0].seller_id), set_by: String(rows[0].set_by) };
+}
+
+// The sale as the processor reports it. Only the fields used are taken, and each is checked.
+function checkReportedSale(out, ref) {
+  const s = out || {};
+  const price = Number(s.priceCents);
+  const fee = s.platformFeeCents === undefined ? 0 : Number(s.platformFeeCents);
+  if (typeof s.moduleKey !== 'string' || !MODULE_KEY_RE.test(s.moduleKey)) throw new PayoutRefusal('bad_reported_sale', `The processor's sale ${ref} names no module.`, 502);
+  if (!Number.isSafeInteger(price) || price <= 0) throw new PayoutRefusal('bad_reported_sale', `The processor's sale ${ref} has no price.`, 502);
+  if (!Number.isSafeInteger(fee) || fee < 0) throw new PayoutRefusal('bad_reported_sale', `The processor's sale ${ref} has a bad fee.`, 502);
+  if (s.currency !== CURRENCY) throw new PayoutRefusal('currency_not_supported', 'The project account is kept in US dollars; this sale is in another currency.', 409);
+  return { moduleKey: s.moduleKey, priceCents: price, platformFeeCents: fee, currency: s.currency };
+}
+
+async function readSale(db, ref) {
+  const { rows } = await db.query('SELECT * FROM module_sales WHERE processor_sale_ref = $1', [ref]);
+  if (!rows[0]) return null;
+  const shares = await db.query('SELECT * FROM module_sale_shares_owed WHERE sale_id = $1 ORDER BY id', [rows[0].id]);
+  return { sale: rows[0], shares: shares.rows };
+}
+
+// recordSale({ processorSaleRef, actorId }) → { sale, shares, already }.
+async function recordSale({ processorSaleRef, actorId }, {
+  pool = defaultPool(), processor = null, account = defaultAccount(), payTypeGates = defaultPayTypeGates(),
+  timeoutMs = TRANSFER_TIMEOUT_MS,
+} = {}) {
+  const ref = typeof processorSaleRef === 'string' ? processorSaleRef.trim() : '';
+  if (!ref || ref.length > 200) throw new PayoutRefusal('bad_sale_ref', 'processor_sale_ref is the processor\'s id for the sale.');
+  if (!isId(actorId)) throw new PayoutRefusal('no_actor', 'A sale is recorded by a signed-in person.', 403);
+  const had = await readSale(pool, ref);
+  if (had) return { ...had, already: true };
+
+  const gate = await moduleShareGate(payTypeGates, pool);
+  if (gate) throw new PayoutRefusal('module_share_gate', gate.message, 409);
+  if (!processor || typeof processor.readSale !== 'function') {
+    throw new PayoutRefusal('no_processor', 'No payment processor is connected, so there is no sale to read.', 503);
+  }
+  if (!account || typeof account.recordMovement !== 'function') {
+    throw new PayoutRefusal('no_account_record', 'The project account record is switched off, so the sale cannot be booked.', 503);
+  }
+  const sale = checkReportedSale(await withTimeout(Promise.resolve(processor.readSale({ ref })), timeoutMs), ref);
+  const rule = await readSplitRule(sale.moduleKey, { pool });
+  if (!rule) throw new PayoutRefusal('no_split_rule', 'This module has no split rule, so its sale cannot be divided. The project sets one first.', 409);
+
+  return inTx(pool, async (db) => {
+    await db.query('SELECT pg_advisory_xact_lock($1::int, hashtext($2::text))', [LOCK_SPACE, ref]);
+    const again = await readSale(db, ref);
+    if (again) return { ...again, already: true };
+    const weights = await readWeights(db, sale.moduleKey, rule.credit_row_kinds);
+    const split = splitSale({ priceCents: sale.priceCents, rule, weights });
+    const ins = await db.query(
+      `INSERT INTO module_sales (module_key, processor_sale_ref, price_cents, platform_fee_cents, currency, rule_id, pool_unassigned_cents, recorded_by)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8) RETURNING *`,
+      [sale.moduleKey, ref, sale.priceCents, sale.platformFeeCents, sale.currency, rule.id, split.pool_unassigned_cents, actorId]);
+    const saleRow = ins.rows[0];
+    const shares = [];
+    for (const s of split.shares) {
+      const r = await db.query(
+        `INSERT INTO module_sale_shares_owed (sale_id, recipient_id, role, amount_cents, currency, weight, weight_total)
+         VALUES ($1,$2,$3,$4,$5,$6,$7) RETURNING *`,
+        [saleRow.id, s.recipient_id, s.role, s.amount_cents, sale.currency, s.weight, s.weight_total]);
+      shares.push(r.rows[0]);
+    }
+    // The price came into the project's account; the platform fee did not (it went to the
+    // platform as the application fee), so only the price is booked.
+    await account.recordMovement(db, { kind: 'funding', amountMicro: sale.priceCents * MICRO_PER_CENT, processorRef: ref });
+    return { sale: saleRow, shares, already: false };
+  });
+}
+
+async function readShare(db, shareId) {
+  const { rows } = await db.query('SELECT * FROM module_sale_shares_owed WHERE id = $1', [shareId]);
+  const r = rows[0];
+  return r ? { ...r, id: String(r.id), recipient_id: String(r.recipient_id), amount_cents: Number(r.amount_cents) } : null;
+}
+
+async function insertAttempt(db, shareId, { outcome, processorRef = null, reason = null, actorId = null }) {
+  const { rows } = await db.query(
+    `INSERT INTO module_share_attempts (share_id, outcome, processor_ref, reason, actor_id)
+     VALUES ($1,$2,$3,$4,$5) RETURNING id, share_id, outcome, processor_ref, reason, created_at`,
+    [shareId, outcome, processorRef, reason === null ? null : clip(reason), actorId]);
+  return rows[0];
+}
+
+async function sentAttempt(db, shareId) {
+  const { rows } = await db.query(
+    "SELECT id, processor_ref FROM module_share_attempts WHERE share_id = $1 AND outcome = 'sent'", [shareId]);
+  return rows[0] || null;
+}
+
+// The approval is checked against the share BEFORE it is bound, so a wrong approval can
+// never lock a share; then it is bound once. A share already bound keeps its approval.
+async function bindApproval(db, share, approvalId, actorId) {
+  const a = (await db.query('SELECT id, kind, recipient_id, amount_cents, currency FROM payout_approvals WHERE id = $1', [approvalId])).rows[0];
+  if (!a || a.kind !== 'payout_approved') throw new PayoutRefusal('no_such_approval', 'There is no payout approval with that id.', 404);
+  if (String(a.recipient_id) !== share.recipient_id) throw new PayoutRefusal('different_recipient', 'The approval is for a different person.', 409);
+  if (Number(a.amount_cents) !== share.amount_cents || a.currency !== share.currency) {
+    throw new PayoutRefusal('different_amount', 'The approval is for a different amount or currency than this share.', 409);
+  }
+  try {
+    await db.query(
+      'INSERT INTO module_share_approvals (share_id, approval_id, bound_by) VALUES ($1,$2,$3) ON CONFLICT DO NOTHING',
+      [share.id, a.id, actorId]);
+  } catch (err) {
+    if (err && err.code === 'P0001') throw new PayoutRefusal('approval_already_used', 'This approval already pays a task. One approval pays one thing.', 409);
+    throw err;
+  }
+  // ON CONFLICT DO NOTHING absorbs both unique rules (one approval per share, one share per
+  // approval), including the same approval pressed for two shares at once; what is bound
+  // now says which happened.
+  const bound = (await db.query('SELECT approval_id FROM module_share_approvals WHERE share_id = $1', [share.id])).rows[0];
+  if (!bound) throw new PayoutRefusal('approval_already_used', 'This approval already pays another share. One approval pays one thing.', 409);
+  if (String(bound.approval_id) !== String(a.id)) {
+    throw new PayoutRefusal('share_already_approved', `This share is paid under approval ${bound.approval_id}.`, 409);
+  }
+  return String(a.id);
+}
+
+// payShare({ shareId, approvalId, actorId }) → { share, status: 'paid'|'held'|'failed', ... }.
+// The shape and the guarantees are payForTask's (builder-payouts.js).
+async function payShare({ shareId, approvalId, actorId }, {
+  pool = defaultPool(), authority = defaultAuthority(), account = defaultAccount(),
+  payTypeGates = defaultPayTypeGates(), processor = null, timeoutMs = TRANSFER_TIMEOUT_MS,
+} = {}) {
+  if (!isId(shareId)) throw new PayoutRefusal('bad_share_id', 'share id must be a number.');
+  if (!isId(approvalId)) throw new PayoutRefusal('bad_approval_id', 'approval_id must be a number.');
+  if (!isId(actorId)) throw new PayoutRefusal('no_actor', 'A payout is pressed by a signed-in person.', 403);
+  const share = await readShare(pool, shareId);
+  if (!share) throw new PayoutRefusal('no_such_share', 'There is no module-sale share with that id.', 404);
+  const paid = await sentAttempt(pool, share.id);
+  if (paid) return { share, status: 'paid', already: true, processor_ref: paid.processor_ref };
+  const boundId = await bindApproval(pool, share, approvalId, actorId);
+
+  const held = async (reason) => {
+    await insertAttempt(pool, share.id, { outcome: 'held', reason, actorId });
+    return { share, status: 'held', reason, words: HELD_WORDS[reason] || null };
+  };
+  if (share.currency !== CURRENCY) return held('currency_not_supported');
+  if (await moduleShareGate(payTypeGates, pool)) return held('module_share_gate');
+  const auth = await authority.checkApproval({
+    id: boundId, kind: 'payout_approved', recipientId: share.recipient_id,
+    amountCents: share.amount_cents, currency: share.currency,
+  }, { pool });
+  if (!auth || !auth.ok) return held((auth && auth.reason) || 'no_such_approval');
+  if (!account || typeof account.recordMovement !== 'function') return held('no_account_record');
+  if (!processor || typeof processor.transfer !== 'function') return held('no_processor');
+
+  return inTx(pool, async (db) => {
+    await db.query('SELECT pg_advisory_xact_lock($1::int, hashtext($2::text))', [LOCK_SPACE, share.id]);
+    const already = await sentAttempt(db, share.id);
+    if (already) return { share, status: 'paid', already: true, processor_ref: already.processor_ref };
+    let ref;
+    try {
+      const out = await withTimeout(Promise.resolve(processor.transfer({
+        idempotencyKey: shareKey(share.id),
+        amountCents: share.amount_cents,
+        currency: share.currency,
+        builderId: share.recipient_id,
+        moduleShareId: share.id,
+        payTo: auth.pay_to,
+      })), timeoutMs);
+      ref = out && typeof out.ref === 'string' && out.ref.trim() ? out.ref.trim() : null;
+      if (!ref) throw Object.assign(new Error('the processor gave no transfer reference'), { code: 'no_reference' });
+    } catch (err) {
+      const reason = clip(`${err && err.code ? err.code + ': ' : ''}${err && err.message ? err.message : 'transfer failed'}`);
+      await insertAttempt(db, share.id, { outcome: 'failed', reason, actorId });
+      return { share, status: 'failed', reason };
+    }
+    await insertAttempt(db, share.id, { outcome: 'sent', processorRef: ref, actorId });
+    await account.recordMovement(db, {
+      kind: 'payout', amountMicro: share.amount_cents * MICRO_PER_CENT,
+      builderId: share.recipient_id, moduleShareId: share.id, processorRef: ref,
+    });
+    return { share, status: 'paid', already: false, processor_ref: ref };
+  });
+}
+
+// listShares(db, { recipientId, limit, offset }) — shares with where each stands, newest
+// first; recipientId narrows it to one person's own.
+async function listShares(db = defaultPool(), { recipientId = null, limit = 50, offset = 0 } = {}) {
+  const lim = Math.min(Math.max(parseInt(limit, 10) || 50, 1), 200);
+  const off = Math.max(parseInt(offset, 10) || 0, 0);
+  const { rows } = await db.query(
+    `SELECT o.id, o.sale_id, s.module_key, s.processor_sale_ref, s.price_cents, o.recipient_id,
+            b.display_name AS recipient_name, o.role, o.amount_cents, o.currency, o.weight, o.weight_total,
+            o.created_at, ap.approval_id, st.processor_ref AS sent_ref, st.created_at AS paid_at,
+            l.outcome AS last_outcome, l.reason AS last_reason, l.created_at AS last_try_at
+       FROM module_sale_shares_owed o
+       JOIN module_sales s ON s.id = o.sale_id
+       LEFT JOIN builders b ON b.id = o.recipient_id
+       LEFT JOIN module_share_approvals ap ON ap.share_id = o.id
+       LEFT JOIN module_share_attempts st ON st.share_id = o.id AND st.outcome = 'sent'
+       LEFT JOIN LATERAL (
+         SELECT outcome, reason, created_at FROM module_share_attempts a
+          WHERE a.share_id = o.id ORDER BY a.id DESC LIMIT 1) l ON true
+      WHERE ($1::bigint IS NULL OR o.recipient_id = $1)
+      ORDER BY o.created_at DESC, o.id DESC
+      LIMIT $2 OFFSET $3`, [recipientId, lim, off]);
+  return rows.map((r) => ({
+    id: String(r.id), sale_id: String(r.sale_id), module_key: r.module_key, processor_sale_ref: r.processor_sale_ref,
+    price_cents: Number(r.price_cents), recipient_id: String(r.recipient_id), recipient_name: r.recipient_name,
+    role: r.role, amount_cents: Number(r.amount_cents), currency: r.currency,
+    weight: r.weight === null ? null : Number(r.weight), weight_total: r.weight_total === null ? null : Number(r.weight_total),
+    created_at: r.created_at, approval_id: r.approval_id ? String(r.approval_id) : null,
+    status: r.sent_ref ? 'paid' : 'owed', processor_ref: r.sent_ref || null, paid_at: r.paid_at || null,
+    last_try: r.last_outcome ? { outcome: r.last_outcome, reason: r.last_reason, at: r.last_try_at, words: HELD_WORDS[r.last_reason] || null } : null,
+  }));
+}
+
+// One object, as builder-payouts.js does: the router reaches it through an injectable default.
+const api = { PayoutRefusal, validateSplitRule, splitSale, previewSplit, setSplitRule, recordSale, payShare, listShares };
+module.exports = api;

package/src/bongos/payout-approvals.js

@@ -302,13 +302,16 @@ async function checkApproval({ id, kind = 'payout_approved', recipientId, amount
   const row = shapeRow(rows[0]);
   if (!row || row.kind !== kind) return { ok: false, reason: 'no_such_approval' };
   if (String(row.recipient_id) !== String(recipientId)) return { ok: false, reason: 'different_recipient' };
-  if (kind === 'payout_approved' && (row.amount_cents !== Number(amountCents) || row.currency !== currency)) {
+  // Money kinds: a payout the project approved, or a person's own cash-out (N7,
+  // task 1004911: approver and recipient are the same person, by core_293's CHECK).
+  const money = kind === 'payout_approved' || kind === 'cashout_approved';
+  if (money && (row.amount_cents !== Number(amountCents) || row.currency !== currency)) {
     return { ok: false, reason: 'different_amount' };
   }
   // N10: the recipient must still pass the gates when it pays. Money owed and
   // refused files a hold that tells them; a grant or contract refuses without one.
   const gates = gatesOf(opts);
-  const g = kind === 'payout_approved'
+  const g = money
     ? await gates.gateOwedPay(row.recipient_id, { owedCents: row.amount_cents, now, pool })
     : await gates.gateRecipient(row.recipient_id, { now, pool });
   if (!g.ok) return { ok: false, reason: 'recipient_gated', gate: { reason: g.reason, freeze_id: g.freeze_id || null } };

package/src/bongos/payout-gates.js

@@ -24,6 +24,14 @@
 // person with payout.approve recorded counts. PROCESSOR_SCREENING_CONFIRMED is the
 // one switch N2 flips, with a reference to that written confirmation.
 //
+// CONTRACTOR PAPERS (task 1004908, N4). Our own contractors are paid only once an
+// NDA is on file for them (the beta overlay, Art. XI) and the processor's
+// onboarding has collected their identity and tax details. Bongos records THAT
+// the papers exist, never their contents: no NDA text, no tax id. Nothing here
+// sets a rate or a schedule (Art. IV); a missing paper only holds the money, with
+// a notice. Internal only in this version, so every payout this instance makes
+// is contractor pay and both papers apply to all of them.
+//
 // Pure first (decide), then the db half (pool injectable).
 
 const PROCESSOR_SCREENING_CONFIRMED = null; // e.g. { processor: 'x', scope: 'OFAC+EU+UN', confirmed_in: 'ADR NNNN' }
@@ -31,7 +39,9 @@ const PROCESSOR_SCREENING_CONFIRMED = null; // e.g. { processor: 'x', scope: 'OF
 const AGE_TIERS = Object.freeze(['under_13', '13_15', '16_17', 'adult']);
 const AGE_BASES = Object.freeze(['self_declared', 'verified_by_processor', 'verified_by_person']);
 const SCREEN_RESULTS = Object.freeze(['clear', 'match', 'error']);
-const FREEZE_REASONS = Object.freeze(['sanctions_match', 'sanctions_unscreened', 'age_no_money', 'age_needs_guardian', 'age_unknown', 'manual']);
+const NDA_STATUSES = Object.freeze(['on_file', 'withdrawn']);
+const TAX_STATUSES = Object.freeze(['collected', 'incomplete']);
+const FREEZE_REASONS = Object.freeze(['sanctions_match', 'sanctions_unscreened', 'age_no_money', 'age_needs_guardian', 'age_unknown', 'nda_missing', 'tax_details_missing', 'manual']);
 const APPEAL_ROUTE = 'POST /api/bongos/me/payout-freezes/:id/appeal';
 const MAX_SCREEN_DAYS = 365;
 
@@ -42,8 +52,14 @@ const NOTICES = Object.freeze({
   age_no_money: 'A payout to you cannot be paid in money because of the age recorded on your account. If the age is wrong, you can appeal and have it corrected.',
   age_needs_guardian: 'A payout to you needs a parent or guardian to co-sign it and an account they control before it can be paid. You can appeal if this is wrong.',
   age_unknown: 'A payout to you is waiting because your account has no age recorded yet. Record your age to continue, or appeal if you think this is wrong.',
+  nda_missing: 'A payout to you is waiting because no signed confidentiality agreement (NDA) is on file for you yet. Nothing is lost; it is paid once the signed agreement is recorded. You can appeal if you have already signed one.',
+  tax_details_missing: 'A payout to you is waiting because your identity and tax details have not been collected yet. You give these to the payment processor, never to us, and it is paid once they are in. You can appeal if you have already done this.',
 });
 
+// Nine digits in a row, dashes and spaces ignored: the shape of a US tax id. A
+// reference that looks like one is refused here and by core_291's CHECK.
+const looksLikeTaxId = (s) => /[0-9]{9}/.test(String(s).replace(/[\s-]/g, ''));
+
 const latest = (rows) => (rows && rows.length ? rows[rows.length - 1] : null);
 
 function screeningCounts(row) {
@@ -54,7 +70,7 @@ function screeningCounts(row) {
 
 // Is this recipient payable in money right now? facts: their rows, oldest first.
 // Returns { ok: true, pay_to } or { ok: false, reason, freeze_id? }.
-function decide({ ageRecords = [], guardians = [], screenings = [], freezes = [], freezeEvents = [], now = new Date() }) {
+function decide({ ageRecords = [], guardians = [], screenings = [], ndas = [], taxDetails = [], freezes = [], freezeEvents = [], now = new Date() }) {
   const lifted = new Set(freezeEvents.filter((e) => e.kind === 'lifted').map((e) => String(e.freeze_id)));
   const open = freezes.filter((f) => !lifted.has(String(f.id)));
   if (open.length) return { ok: false, reason: 'frozen', freeze_id: String(open[open.length - 1].id), frozen_for: open[open.length - 1].reason };
@@ -74,6 +90,11 @@ function decide({ ageRecords = [], guardians = [], screenings = [], freezes = []
   if (s && s.result === 'match') return { ok: false, reason: 'sanctions_match' };
   if (!s || s.result !== 'clear' || !s.valid_until || new Date(s.valid_until) < now) return { ok: false, reason: 'sanctions_unscreened' };
 
+  const nda = latest(ndas);
+  if (!nda || nda.status !== 'on_file') return { ok: false, reason: 'nda_missing' };
+  const tax = latest(taxDetails);
+  if (!tax || tax.status !== 'collected') return { ok: false, reason: 'tax_details_missing' };
+
   return { ok: true, pay_to: payTo, needs_guardian_cosign: payTo !== 'self' };
 }
 
@@ -90,23 +111,25 @@ const ids = (rows) => rows.map((r) => {
 });
 
 // Everything the gate reads about one builder, oldest first per table.
-// Everything the gate reads about a SET of builders: five queries however many
+// Everything the gate reads about a SET of builders: seven queries however many
 // recipients a run has (one per table, then the holds' events), never one round
 // of reads per person. Returns Map<builderId, facts>, each table oldest first.
 async function readFactsMany(builderIds, { pool = defaultPool() } = {}) {
   const want = [...new Set(builderIds.map(String))];
-  const out = new Map(want.map((id) => [id, { ageRecords: [], guardians: [], screenings: [], freezes: [], freezeEvents: [] }]));
+  const out = new Map(want.map((id) => [id, { ageRecords: [], guardians: [], screenings: [], ndas: [], taxDetails: [], freezes: [], freezeEvents: [] }]));
   if (!want.length) return out;
   // One recipient: every row is theirs. Many: rows carry builder_id.
   const owner = (r) => (want.length === 1 ? want[0] : String(r.builder_id));
   const q = (sql) => pool.query(sql, [want]).then((r) => ids(r.rows));
-  const [ageRecords, guardians, screenings, freezes] = await Promise.all([
+  const [ageRecords, guardians, screenings, ndas, taxDetails, freezes] = await Promise.all([
     q('SELECT id, builder_id, tier, basis, recorded_by, recorded_at FROM payout_age_records WHERE builder_id = ANY($1::bigint[]) ORDER BY id'),
     q('SELECT id, builder_id, guardian_id, guardian_account, active, recorded_by, recorded_at FROM payout_guardians WHERE builder_id = ANY($1::bigint[]) ORDER BY id'),
     q('SELECT id, builder_id, result, screened_by, reference, valid_until, recorded_by, screened_at FROM payout_screenings WHERE builder_id = ANY($1::bigint[]) ORDER BY id'),
+    q('SELECT id, builder_id, status, nda_version, reference, recorded_by, recorded_at FROM payout_ndas WHERE builder_id = ANY($1::bigint[]) ORDER BY id'),
+    q('SELECT id, builder_id, status, collected_by, reference, recorded_by, recorded_at FROM payout_tax_details WHERE builder_id = ANY($1::bigint[]) ORDER BY id'),
     q('SELECT id, builder_id, reason, notice_text, appeal_route, owed_cents, frozen_by, frozen_at FROM payout_freezes WHERE builder_id = ANY($1::bigint[]) ORDER BY id'),
   ]);
-  for (const [key, rows] of [['ageRecords', ageRecords], ['guardians', guardians], ['screenings', screenings], ['freezes', freezes]]) {
+  for (const [key, rows] of [['ageRecords', ageRecords], ['guardians', guardians], ['screenings', screenings], ['ndas', ndas], ['taxDetails', taxDetails], ['freezes', freezes]]) {
     for (const r of rows) { const b = out.get(owner(r)); if (b) b[key].push(r); }
   }
   if (freezes.length) {
@@ -223,6 +246,11 @@ async function insertRow(table, cols, vals, { pool = defaultPool() } = {}) {
 const recordAge = ({ builderId, tier, basis, recordedBy }, o) => insertRow('payout_age_records', ['builder_id', 'tier', 'basis', 'recorded_by'], [builderId, tier, basis, recordedBy], o);
 const recordGuardian = ({ builderId, guardianId, guardianAccount, active, recordedBy }, o) => insertRow('payout_guardians', ['builder_id', 'guardian_id', 'guardian_account', 'active', 'recorded_by'], [builderId, guardianId, guardianAccount, active, recordedBy], o);
 const recordScreening = ({ builderId, result, screenedBy, reference, validUntil, recordedBy }, o) => insertRow('payout_screenings', ['builder_id', 'result', 'screened_by', 'reference', 'valid_until', 'recorded_by'], [builderId, result, screenedBy, reference, validUntil, recordedBy], o);
+const recordNda = ({ builderId, status, ndaVersion, reference, recordedBy }, o) => insertRow('payout_ndas', ['builder_id', 'status', 'nda_version', 'reference', 'recorded_by'], [builderId, status, ndaVersion, reference, recordedBy], o);
+const recordTaxDetails = ({ builderId, status, collectedBy, reference, recordedBy }, o) => {
+  if (reference != null && looksLikeTaxId(reference)) throw new Error('recordTaxDetails: the reference looks like a tax id; record the processor onboarding reference, never the id itself');
+  return insertRow('payout_tax_details', ['builder_id', 'status', 'collected_by', 'reference', 'recorded_by'], [builderId, status, collectedBy, reference, recordedBy], o);
+};
 const freezeManually = ({ builderId, noticeText, owedCents, frozenBy }, o) => insertRow('payout_freezes', ['builder_id', 'reason', 'notice_text', 'appeal_route', 'owed_cents', 'frozen_by'], [builderId, 'manual', noticeText, APPEAL_ROUTE, owedCents, frozenBy], o);
 const addFreezeEvent = ({ freezeId, kind, actorId, statement }, o) => insertRow('payout_freeze_events', ['freeze_id', 'kind', 'actor_id', 'statement'], [freezeId, kind, actorId, statement], o);
 
@@ -243,7 +271,7 @@ const recordCosign = ({ builderId, guardianId, approvalId, ruleId, runKey, sessi
 async function cosignAsGuardian({ guardianId, sessionId, approvalId = null, ruleId = null, runKey = null }, { pool = defaultPool() } = {}) {
   let recipients = [];
   if (approvalId) {
-    const { rows } = await pool.query("SELECT recipient_id FROM payout_approvals WHERE id = $1 AND kind = 'payout_approved'", [approvalId]);
+    const { rows } = await pool.query("SELECT recipient_id FROM payout_approvals WHERE id = $1 AND kind IN ('payout_approved', 'cashout_approved')", [approvalId]);
     recipients = rows.map((r) => String(r.recipient_id));
   } else {
     const { rows } = await pool.query("SELECT terms FROM payout_approvals WHERE rule_id = $1 AND run_key = $2 AND kind = 'run_noticed'", [ruleId, runKey]);
@@ -290,6 +318,8 @@ function presentOwn(v) {
   const age = latest(f.ageRecords || []);
   const g = latest(f.guardians || []);
   const s = latest((f.screenings || []).filter(screeningCounts));
+  const nda = latest(f.ndas || []);
+  const tax = latest(f.taxDetails || []);
   const events = f.freezeEvents || [];
   return {
     payable: Boolean(v.ok),
@@ -297,6 +327,8 @@ function presentOwn(v) {
     age_tier: age ? age.tier : null,
     guardian: g ? { guardian_id: g.guardian_id, active: g.active } : null,
     screening: s ? { result: s.result, valid_until: s.valid_until || null } : null,
+    nda_on_file: Boolean(nda && nda.status === 'on_file'),
+    tax_details_collected: Boolean(tax && tax.status === 'collected'),
     holds: (f.freezes || []).map((fr) => {
       const mine = events.filter((e) => String(e.freeze_id) === String(fr.id));
       return {
@@ -334,8 +366,11 @@ const api = {
   AGE_TIERS,
   AGE_BASES,
   SCREEN_RESULTS,
+  NDA_STATUSES,
+  TAX_STATUSES,
   FREEZE_REASONS,
   NOTICES,
+  looksLikeTaxId,
   APPEAL_ROUTE,
   MAX_SCREEN_DAYS,
   screeningCounts,
@@ -352,6 +387,8 @@ const api = {
   recordAge,
   recordGuardian,
   recordScreening,
+  recordNda,
+  recordTaxDetails,
   recordCosign,
   cosignAsGuardian,
   hasCosign,

package/src/bongos/project-settings.js

@@ -56,6 +56,8 @@ const SETTING_KEYS = {
   // (rankCapKey). A rank cap is a PER-PERSON monthly allowance (task 1005019); an empty value means the rank has none of its own.
   TWEAK_AUTOPICKUP_RANK_CAP_PREFIX: 'tweak.autopickup_rank_cap.',
   SPEND_CAP: 'treasury.spend_cap_usd',
+  // The funding wall (task 1003185, ADR 0386): modules/lifecycle/funding-wall.js.
+  FUNDING_WALL: 'funding.wall',
   // Testing new module versions first (task 1003802, ADR 0344 D1): module-testing.js.
   MODULE_TESTER: 'modules.tester',
   MODULE_GENERAL_ONLY: 'modules.general_only',