@bongos/core 1.23.21 → 1.24.1

package/src/bongos/payout-approvals.js

@@ -0,0 +1,342 @@
+'use strict';
+
+// src/bongos/payout-approvals.js — every payout needs a logged, personal approval
+// (task 1004913, goal 1000092 N9; ADR 0385 decisions 4 and 8, ADR 0387 decision 3).
+//
+// WHY. The owner's legal framework (Art. I, cited by Article only) holds that a
+// payout, an equity grant or a contract is never executed by the platform or an AI
+// on its own: each needs a distinct step by the project's authorised person, and an
+// append-only log of who approved what and when. If we cannot prove the person
+// pressed the button, we were the actor. This file is that step and that log; the
+// money-moving tasks (M04 pays a builder, N6 module sales, N7 cash-out) call
+// checkRun / checkApproval before they instruct the processor, and never move a
+// cent on anything else.
+//
+// THE SHAPE (migrations/core_283_payout_approvals.sql). One append-only table of
+// events. A standing payout rule is its `rule_signed` row; it is narrowed or
+// revoked by later rows, never edited. Runs under a rule are `run_noticed` (the
+// one kind a runner may file: it authorises nothing) and become payable only after
+// the rule's pause window, unless a person files `run_held`. One-off payouts,
+// equity grants and contracts are one row and one signature each — there is no
+// batch form, on purpose.
+//
+// WHO. The routes gate on the `payout.approve` permission (rank read fresh per
+// request, ADR 0016) and then demand a PERSONAL session: the person's own web
+// session, never a CLI token (that is what an AI session runs on), never a machine
+// principal. The database repeats both rules (a CHECK on session_source and a
+// trigger on builders.system_role), so a route that forgot cannot write a
+// signature an AI made. An AI may never create or widen a rule: creating needs a
+// personal session, and widening does not exist — a narrowing that would widen is
+// refused here AND by the trigger, so the only way to a bigger rule is a person
+// signing a new one.
+//
+// Nothing here moves money (ADR 0385 D1): this is the authority a processor
+// transfer must cite. Pure validators first, then the db half (pool injectable).
+
+const MAX_CENTS = 100_000_000_00; // $100M: a sanity ceiling, not a policy
+const MAX_PAUSE_HOURS = 720;
+const FORMULA_KINDS = Object.freeze(['task_pay_terms', 'fixed_per_task', 'credit_share']);
+const SCHEDULES = Object.freeze(['on_ship', 'weekly', 'monthly']);
+const CAP_KEYS = Object.freeze(['per_payout_cents', 'per_run_cents', 'per_month_cents']);
+const SIGNED_KINDS = Object.freeze(['rule_signed', 'rule_narrowed', 'rule_revoked', 'run_held', 'payout_approved', 'grant_signed', 'contract_signed']);
+const RUN_KEY_RE = /^[A-Za-z0-9._:-]{1,80}$/;
+const CURRENCY_RE = /^[A-Z]{3}$/;
+const NOTE_MAX = 500;
+
+const isCents = (v) => Number.isSafeInteger(v) && v > 0 && v <= MAX_CENTS;
+const isId = (v) => (typeof v === 'number' && Number.isSafeInteger(v) && v > 0) || (typeof v === 'string' && /^[1-9][0-9]{0,18}$/.test(v));
+
+function cleanNote(raw) {
+  if (raw === undefined || raw === null || raw === '') return { value: null };
+  if (typeof raw !== 'string') return { error: 'note must be text' };
+  const v = raw.replace(/\s+/g, ' ').trim();
+  if (v.length > NOTE_MAX) return { error: `note must be ${NOTE_MAX} characters or fewer` };
+  return { value: v || null };
+}
+
+// A standing payout rule's terms, strictly: every field required that a run is
+// checked against, nothing unknown accepted (a person signs exactly what is stored).
+function validateRuleTerms(raw) {
+  const errors = [];
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { errors: ['terms must be an object'] };
+  const known = new Set(['caps', 'currency', 'formula', 'schedule', 'pause_hours']);
+  for (const k of Object.keys(raw)) if (!known.has(k)) errors.push(`unknown term: ${k}`);
+
+  const caps = raw.caps;
+  const outCaps = {};
+  if (!caps || typeof caps !== 'object' || Array.isArray(caps)) {
+    errors.push('caps must be an object');
+  } else {
+    for (const k of Object.keys(caps)) if (!CAP_KEYS.includes(k)) errors.push(`unknown cap: ${k}`);
+    for (const k of ['per_payout_cents', 'per_run_cents']) {
+      if (!isCents(caps[k])) errors.push(`caps.${k} must be a whole number of cents above zero`);
+      else outCaps[k] = caps[k];
+    }
+    if (caps.per_month_cents !== undefined && caps.per_month_cents !== null) {
+      if (!isCents(caps.per_month_cents)) errors.push('caps.per_month_cents must be a whole number of cents above zero, or left out');
+      else outCaps.per_month_cents = caps.per_month_cents;
+    }
+    if (outCaps.per_payout_cents && outCaps.per_run_cents && outCaps.per_payout_cents > outCaps.per_run_cents) {
+      errors.push('caps.per_payout_cents may not be above caps.per_run_cents');
+    }
+    if (outCaps.per_run_cents && outCaps.per_month_cents && outCaps.per_run_cents > outCaps.per_month_cents) {
+      errors.push('caps.per_run_cents may not be above caps.per_month_cents');
+    }
+  }
+
+  if (typeof raw.currency !== 'string' || !CURRENCY_RE.test(raw.currency)) errors.push('currency must be a three-letter code such as USD');
+
+  const f = raw.formula;
+  let formula = null;
+  if (!f || typeof f !== 'object' || Array.isArray(f) || !FORMULA_KINDS.includes(f.kind)) {
+    errors.push(`formula.kind must be one of ${FORMULA_KINDS.join(', ')}`);
+  } else if (f.kind === 'fixed_per_task') {
+    if (!isCents(f.amount_cents)) errors.push('formula.amount_cents must be a whole number of cents above zero');
+    else formula = { kind: f.kind, amount_cents: f.amount_cents };
+    for (const k of Object.keys(f)) if (k !== 'kind' && k !== 'amount_cents') errors.push(`unknown formula field: ${k}`);
+  } else if (f.kind === 'credit_share') {
+    // ADR 0387 D5: a pool run names the credit row kinds it counts.
+    const kinds = f.credit_row_kinds;
+    if (!Array.isArray(kinds) || kinds.length === 0 || kinds.some((k) => typeof k !== 'string' || !/^[a-z_.]{1,40}$/.test(k))) {
+      errors.push('formula.credit_row_kinds must name the credit row kinds the pool counts');
+    } else {
+      formula = { kind: f.kind, credit_row_kinds: [...new Set(kinds)].sort() };
+    }
+    for (const k of Object.keys(f)) if (k !== 'kind' && k !== 'credit_row_kinds') errors.push(`unknown formula field: ${k}`);
+  } else {
+    formula = { kind: f.kind };
+    for (const k of Object.keys(f)) if (k !== 'kind') errors.push(`unknown formula field: ${k}`);
+  }
+
+  if (!SCHEDULES.includes(raw.schedule)) errors.push(`schedule must be one of ${SCHEDULES.join(', ')}`);
+  if (!Number.isSafeInteger(raw.pause_hours) || raw.pause_hours < 1 || raw.pause_hours > MAX_PAUSE_HOURS) {
+    errors.push(`pause_hours must be a whole number from 1 to ${MAX_PAUSE_HOURS}`);
+  }
+
+  if (errors.length) return { errors };
+  return { terms: { caps: outCaps, currency: raw.currency, formula, schedule: raw.schedule, pause_hours: raw.pause_hours } };
+}
+
+// The narrowing rule, the same one the trigger enforces: caps only go down (and a
+// set cap is never removed), the pause only gets longer, and the formula,
+// schedule and currency do not move. Returns the reasons a change would widen.
+function wideningReasons(current, next) {
+  const out = [];
+  if (JSON.stringify(current.formula) !== JSON.stringify(next.formula)) out.push('the formula would change');
+  if (current.schedule !== next.schedule) out.push('the schedule would change');
+  if (current.currency !== next.currency) out.push('the currency would change');
+  if (next.pause_hours < current.pause_hours) out.push('the pause window would get shorter');
+  for (const k of CAP_KEYS) {
+    const was = current.caps[k];
+    const now = next.caps[k];
+    if (was !== undefined && was !== null && (now === undefined || now === null)) out.push(`the ${k} cap would be removed`);
+    else if (was !== undefined && was !== null && now > was) out.push(`the ${k} cap would go up`);
+  }
+  return out;
+}
+
+// One personal act: the person's own web session, a human builder. Everything a
+// route needs to refuse an AI, in one place (the DB repeats it).
+function personalSession(req) {
+  const s = req && req.gdsSession;
+  const b = req && req.builder;
+  if (!b || !s) return { ok: false, reason: 'no_session' };
+  if (b.system_role) return { ok: false, reason: 'machine_principal' };
+  if (s.source !== 'web') return { ok: false, reason: 'not_a_web_session' };
+  if (s.session_id === undefined || s.session_id === null) return { ok: false, reason: 'no_session' };
+  return { ok: true, actor: { id: b.id, rank: b.rank || null, session_id: s.session_id, session_source: 'web' } };
+}
+
+// Fold a rule's events into its current state. events: its rows, oldest first,
+// the signing row included.
+function foldRule(events) {
+  const signed = events.find((e) => e.kind === 'rule_signed');
+  if (!signed) return null;
+  let terms = signed.terms;
+  let revoked = null;
+  for (const e of events) {
+    if (e.kind === 'rule_narrowed') terms = e.terms;
+    if (e.kind === 'rule_revoked') revoked = { by: e.actor_id, at: e.created_at };
+  }
+  return { id: signed.id, signed_by: signed.actor_id, signed_at: signed.created_at, terms, revoked, active: !revoked };
+}
+
+const MONTH = (d) => new Date(d).toISOString().slice(0, 7);
+
+// May this run pay now? rule: foldRule's state; ruleEvents: the rule's rows;
+// payouts: [{ recipient_id, amount_cents }]. Pure; checkRun reads the rows.
+function judgeRun({ rule, ruleEvents, runKey, payouts, now = new Date() }) {
+  if (!rule) return { ok: false, reason: 'no_such_rule' };
+  if (!rule.active) return { ok: false, reason: 'rule_revoked' };
+  const notice = ruleEvents.find((e) => e.kind === 'run_noticed' && e.run_key === runKey);
+  if (!notice) return { ok: false, reason: 'run_not_noticed' };
+  if (ruleEvents.some((e) => e.kind === 'run_held' && e.run_key === runKey)) return { ok: false, reason: 'run_held' };
+  const opensAt = new Date(new Date(notice.created_at).getTime() + rule.terms.pause_hours * 3600_000);
+  if (now < opensAt) return { ok: false, reason: 'in_pause_window', opens_at: opensAt.toISOString() };
+  const noticed = notice.terms && Array.isArray(notice.terms.payouts) ? notice.terms.payouts : [];
+  const key = (list) => JSON.stringify(list.map((p) => [String(p.recipient_id), Number(p.amount_cents)]).sort());
+  if (!Array.isArray(payouts) || key(payouts) !== key(noticed)) return { ok: false, reason: 'run_differs_from_notice' };
+  const caps = rule.terms.caps;
+  if (noticed.some((p) => Number(p.amount_cents) > caps.per_payout_cents)) return { ok: false, reason: 'over_per_payout_cap' };
+  if (Number(notice.amount_cents) > caps.per_run_cents) return { ok: false, reason: 'over_per_run_cap' };
+  if (caps.per_month_cents) {
+    const month = MONTH(notice.created_at);
+    const held = new Set(ruleEvents.filter((e) => e.kind === 'run_held').map((e) => e.run_key));
+    const total = ruleEvents
+      .filter((e) => e.kind === 'run_noticed' && !held.has(e.run_key) && MONTH(e.created_at) === month && e.id <= notice.id)
+      .reduce((s, e) => s + Number(e.amount_cents), 0);
+    if (total > caps.per_month_cents) return { ok: false, reason: 'over_per_month_cap' };
+  }
+  return { ok: true, rule_id: rule.id, notice_id: notice.id, currency: notice.currency, payouts: noticed };
+}
+
+// ── db half ────────────────────────────────────────────────────────────────
+
+function defaultPool() { return require('./pool').pool; }
+
+const COLS = 'id, kind, rule_id, run_key, actor_id, actor_rank, session_id, session_source, recipient_id, amount_cents, currency, terms, note, created_at';
+
+function shapeRow(r) {
+  if (!r) return null;
+  return {
+    ...r,
+    id: String(r.id),
+    rule_id: r.rule_id == null ? null : String(r.rule_id),
+    actor_id: String(r.actor_id),
+    recipient_id: r.recipient_id == null ? null : String(r.recipient_id),
+    session_id: r.session_id == null ? null : String(r.session_id),
+    amount_cents: r.amount_cents == null ? null : Number(r.amount_cents),
+  };
+}
+
+async function insertEvent(e, { pool = defaultPool() } = {}) {
+  const { rows } = await pool.query(
+    `INSERT INTO payout_approvals (kind, rule_id, run_key, actor_id, actor_rank, session_id, session_source,
+                                   recipient_id, amount_cents, currency, terms, note)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11::jsonb,$12)
+     RETURNING ${COLS}`,
+    [e.kind, e.rule_id ?? null, e.run_key ?? null, e.actor.id, e.actor.rank ?? null, e.actor.session_id ?? null,
+      e.actor.session_source ?? null, e.recipient_id ?? null, e.amount_cents ?? null, e.currency ?? null,
+      JSON.stringify(e.terms || {}), e.note ?? null],
+  );
+  return shapeRow(rows[0]);
+}
+
+async function ruleEvents(ruleId, { pool = defaultPool() } = {}) {
+  const { rows } = await pool.query(
+    `SELECT ${COLS} FROM payout_approvals WHERE id = $1 OR rule_id = $1 ORDER BY id`,
+    [ruleId],
+  );
+  return rows.map(shapeRow);
+}
+
+async function readRule(ruleId, opts = {}) {
+  const events = await ruleEvents(ruleId, opts);
+  return { rule: foldRule(events), events };
+}
+
+async function listRules({ pool = defaultPool() } = {}) {
+  const { rows } = await pool.query(
+    `SELECT ${COLS} FROM payout_approvals
+      WHERE kind IN ('rule_signed', 'rule_narrowed', 'rule_revoked')
+      ORDER BY id`,
+  );
+  const byRule = new Map();
+  for (const r of rows.map(shapeRow)) {
+    const id = r.kind === 'rule_signed' ? r.id : r.rule_id;
+    if (!byRule.has(id)) byRule.set(id, []);
+    byRule.get(id).push(r);
+  }
+  return [...byRule.values()].map(foldRule).filter(Boolean);
+}
+
+async function listLog({ ruleId = null, limit = 100, pool = defaultPool() } = {}) {
+  const lim = Math.min(Math.max(Number(limit) || 100, 1), 500);
+  const { rows } = ruleId
+    ? await pool.query(`SELECT ${COLS} FROM payout_approvals WHERE id = $1 OR rule_id = $1 ORDER BY id DESC LIMIT $2`, [ruleId, lim])
+    : await pool.query(`SELECT ${COLS} FROM payout_approvals ORDER BY id DESC LIMIT $1`, [lim]);
+  return rows.map(shapeRow);
+}
+
+// For M04 and friends: may this run under this rule pay now?
+// The N10 gates (age tier, sanctions, open holds) are checked again at pay time,
+// because a recipient's standing can change inside a pause window. Injectable so
+// a test can stand in for the database; production reads ./payout-gates.
+function gatesOf(opts) { return opts.gates || require('./payout-gates'); }
+
+// Returns { ok, payouts, held }: `payouts` are the lines that may be paid now
+// (each with pay_to — the guardian's account for a 16-17 recipient), `held` the
+// lines that may not, each already notified with a hold the person can appeal.
+// A run is never stopped whole for one recipient; their line waits, the rest pay.
+async function checkRun({ ruleId, runKey, payouts, now = new Date() }, opts = {}) {
+  const { rule, events } = await readRule(ruleId, opts);
+  const v = judgeRun({ rule, ruleEvents: events, runKey, payouts, now });
+  if (!v.ok) return v;
+  const gates = gatesOf(opts);
+  // One batched read for the whole run, not a round of reads per recipient.
+  const owed = new Map();
+  for (const p of v.payouts) owed.set(String(p.recipient_id), (owed.get(String(p.recipient_id)) || 0) + Number(p.amount_cents));
+  const verdicts = await gates.gateOwedPayMany(owed, { now, pool: opts.pool });
+  const minors = [...verdicts].filter(([, g]) => g.ok && g.needs_guardian_cosign).map(([rid]) => rid);
+  const cosigned = minors.length ? await gates.cosignedInRun({ ruleId: v.rule_id, runKey, builderIds: minors }, { pool: opts.pool }) : new Set();
+  const pay = [];
+  const held = [];
+  for (const p of v.payouts) {
+    const g = verdicts.get(String(p.recipient_id));
+    if (!g.ok) { held.push({ ...p, reason: g.reason, freeze_id: g.freeze_id }); continue; }
+    if (g.needs_guardian_cosign && !cosigned.has(String(p.recipient_id))) { held.push({ ...p, reason: 'guardian_cosign_missing', freeze_id: null }); continue; }
+    pay.push({ ...p, pay_to: g.pay_to });
+  }
+  return { ...v, payouts: pay, held };
+}
+
+// For a one-off: does approval `id` cover exactly this payout, grant or contract?
+// It answers whether the authority EXISTS; it does not spend it. The paying task
+// must make the transfer idempotent on the approval id (one approval, one
+// transfer: the processor idempotency key and its own money record, ADR 0387 D2),
+// or a second call would pay twice. checkRun is the same, keyed on rule + run_key.
+async function checkApproval({ id, kind = 'payout_approved', recipientId, amountCents = null, currency = null, now = new Date() }, opts = {}) {
+  const pool = opts.pool || defaultPool();
+  if (!isId(id)) return { ok: false, reason: 'no_such_approval' };
+  const { rows } = await pool.query(`SELECT ${COLS} FROM payout_approvals WHERE id = $1`, [id]);
+  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)) {
+    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'
+    ? 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 } };
+  if (g.needs_guardian_cosign && !(await gates.hasCosign({ builderId: row.recipient_id, approvalId: row.id }, { pool }))) {
+    return { ok: false, reason: 'guardian_cosign_missing' };
+  }
+  return { ok: true, approval: row, pay_to: g.pay_to };
+}
+
+module.exports = {
+  FORMULA_KINDS,
+  SCHEDULES,
+  CAP_KEYS,
+  SIGNED_KINDS,
+  RUN_KEY_RE,
+  MAX_PAUSE_HOURS,
+  isCents,
+  isId,
+  cleanNote,
+  validateRuleTerms,
+  wideningReasons,
+  personalSession,
+  foldRule,
+  judgeRun,
+  insertEvent,
+  readRule,
+  listRules,
+  listLog,
+  checkRun,
+  checkApproval,
+};