@bongos/core 1.23.22 → 1.24.2

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

@@ -0,0 +1,133 @@
+'use strict';
+
+// src/bongos/routes/my-payouts.js — the person's own side of the payout gates
+// (task 1004914, goal 1000092 N10; ADR 0385 decision 8).
+//
+// WHY. When pay someone is owed is held, the owner's framework (cited by Article
+// only) requires that they are told and can appeal: earned pay is never withheld
+// silently. These are the routes for that person, kept apart from the approver's
+// routes in routes/payout-gates.js so this whole file can be held to the
+// own-scope rule (tests/own_scope_guard.mjs, the my-passkeys precedent): every
+// route acts on req.builder.id and nothing else.
+//
+//   GET  /me/payouts                     my standing, every hold, its notice, its events
+//   POST /me/payout-age                  declare my own age tier (marked self-declared)
+//   POST /me/payout-freezes/:id/appeal   appeal a hold on my own pay
+//   POST /me/guardian-cosigns            co-sign, as myself, a payout to the builder
+//                                        I am guardian for (the database checks I am)
+//
+// Every write needs the person's own web session: an AI session may not declare
+// anyone's age, appeal for them, or sign for a guardian.
+
+const express = require('express');
+const auth = require('../auth');
+const { validateOrRespond } = require('./_helpers');
+const { OUR_REFUSALS } = require('./payout-gates');
+const log = require('../logger').logger.child({ src: 'my-payouts' });
+
+const PERSONAL_REFUSAL = 'This must be done by the person themselves, signed in on the website. A command-line or AI session cannot do it.';
+
+function buildMyPayoutsRouter({
+  gates = require('../payout-gates'),
+  approvals = require('../payout-approvals'),
+  requireBuilder = auth.requireBuilder,
+} = {}) {
+  const router = express.Router();
+
+  function personal(req, res) {
+    const p = approvals.personalSession(req);
+    if (!p.ok) {
+      res.fail('personal_approval_required', { status: 403, message: PERSONAL_REFUSAL });
+      return null;
+    }
+    return p.actor;
+  }
+
+  function fault(res, err, what) {
+    // A trigger refusal is the database saying no. Its words are passed on only
+    // when they are one of core_284's own plain-language rules (OUR_REFUSALS); any
+    // other database text stays in the log, never in the response.
+    if (err && (err.code === '23514' || err.code === '42501')) {
+      const said = String(err.message || '');
+      const ours = OUR_REFUSALS.some((re) => re.test(said));
+      if (!ours) log.warn({ err: said }, `${what} refused by the database`);
+      return res.fail('payout_refused', { status: 409, message: ours ? said : 'The payout rules refused this.' });
+    }
+    if (err && err.code === '23505') return res.fail('already_recorded', { status: 409, message: 'This has already been recorded.' });
+    if (err && err.code === '23503') return res.fail('unknown_builder', { status: 400, message: 'That is not a builder on this project.' });
+    log.error({ err: err && err.message }, `${what} failed`);
+    return res.fail('payout_gate_failed', { status: 500, message: 'internal error' });
+  }
+
+  const statement = (raw, max) => (typeof raw === 'string' ? raw.replace(/\s+/g, ' ').trim() : '').slice(0, max + 1);
+
+  // GET /api/bongos/me/payouts — my payout standing: whether I can be paid, every
+  // hold on my pay with its notice and what happened since, and how to appeal.
+  router.get('/me/payouts', requireBuilder, async (req, res) => {
+    try {
+      const v = await gates.gateRecipient(req.builder.id);
+      res.json(gates.presentOwn(v));
+    } catch (err) { fault(res, err, 'GET /me/payouts'); }
+  });
+
+  // POST /api/bongos/me/payout-age — declare my own age tier. Body: { tier }.
+  router.post('/me/payout-age', requireBuilder, async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { tier: { required: true } })) return;
+    if (!gates.AGE_TIERS.includes(req.body.tier)) return res.fail('bad_tier', { status: 400, message: `tier must be one of ${gates.AGE_TIERS.join(', ')}` });
+    try {
+      res.status(201).json({ record: await gates.recordAge({ builderId: req.builder.id, tier: req.body.tier, basis: 'self_declared', recordedBy: req.builder.id }) });
+    } catch (err) { fault(res, err, 'POST /me/payout-age'); }
+  });
+
+  // POST /api/bongos/me/payout-freezes/:id/appeal — appeal a hold on my pay. Body: { statement }.
+  router.post('/me/payout-freezes/:id/appeal', requireBuilder, async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { statement: { required: true } })) return;
+    if (!approvals.isId(req.params.id)) return res.fail('bad_freeze_id', { status: 400, message: 'freeze id must be a number' });
+    const words = statement(req.body.statement, 2000);
+    if (!words || words.length > 2000) return res.fail('bad_statement', { status: 400, message: 'Say why, in up to 2000 characters.' });
+    try {
+      const f = await gates.readFreeze(req.params.id);
+      if (!f || String(f.builder_id) !== String(req.builder.id)) return res.fail('no_such_freeze', { status: 404, message: 'You have no hold with that id.' });
+      if (f.lifted) return res.fail('already_lifted', { status: 409, message: 'That hold is already lifted.' });
+      res.status(201).json({ event: await gates.addFreezeEvent({ freezeId: f.id, kind: 'appealed', actorId: req.builder.id, statement: words }) });
+    } catch (err) { fault(res, err, 'POST /me/payout-freezes/:id/appeal'); }
+  });
+
+  // POST /api/bongos/me/guardian-cosigns — as a guardian, co-sign one payout to the
+  // 16-17 builder(s) I am guardian for. Body: { approval_id } or { rule_id, run_key }.
+  // Whose payout it is comes from the payout itself (its recipient, or the run's
+  // lines), narrowed to the builders whose current guardian is req.builder — never
+  // from a builder id the caller sends. The database checks the guardianship again.
+  router.post('/me/guardian-cosigns', requireBuilder, async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { approval_id: {}, rule_id: {}, run_key: {} })) return;
+    const b = req.body;
+    const oneOff = b.approval_id != null;
+    const run = b.rule_id != null || b.run_key != null;
+    if (oneOff === run) return res.fail('bad_target', { status: 400, message: 'Co-sign either one approval_id, or one rule_id with its run_key.' });
+    if (oneOff && !approvals.isId(b.approval_id)) return res.fail('bad_target', { status: 400, message: 'approval_id must be a number' });
+    if (run && (!approvals.isId(b.rule_id) || typeof b.run_key !== 'string' || !approvals.RUN_KEY_RE.test(b.run_key))) {
+      return res.fail('bad_target', { status: 400, message: 'rule_id must be a number and run_key a run key' });
+    }
+    try {
+      const cosigns = await gates.cosignAsGuardian({
+        guardianId: req.builder.id,
+        sessionId: actor.session_id,
+        approvalId: oneOff ? b.approval_id : null,
+        ruleId: run ? b.rule_id : null,
+        runKey: run ? b.run_key : null,
+      });
+      if (!cosigns.length) return res.fail('nothing_to_cosign', { status: 404, message: 'That payout is not to anyone you are the guardian for.' });
+      res.status(201).json({ cosigns });
+    } catch (err) { fault(res, err, 'POST /me/guardian-cosigns'); }
+  });
+
+  return router;
+}
+
+module.exports = buildMyPayoutsRouter;

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

@@ -0,0 +1,312 @@
+'use strict';
+
+// src/bongos/routes/payout-approvals.js — the payout approval step and its log
+// (task 1004913, goal 1000092 N9; ADR 0385 decisions 4 and 8).
+//
+// WHY. Before any money-moving task can pay (M04, N6, N7), the project's
+// authorised person must have personally approved it, and that approval must sit
+// in an append-only log (Art. I of the owner's framework, cited by Article only).
+// These routes are the only writers of that log. The rules live in
+// ../payout-approvals.js; the database repeats the ones that matter
+// (migrations/core_283_payout_approvals.sql).
+//
+// THE GATES, in order, on every route:
+//   1. requireBuilder + requirePermission('payout.approve') — rank and grants read
+//      fresh from the DB per request (ADR 0016). Archon by default; a project may
+//      hand the atom to a treasurer rank of its own.
+//   2. on every SIGNATURE: a personal session — the person's own web session,
+//      never a CLI token and never a machine principal. A 403
+//      `personal_approval_required` says so in words. Only noticing a run (which
+//      authorises nothing) and reading the log skip it.
+//
+// No batch route exists: each payout, grant and contract is one request and one
+// row. A body carrying a list where one item is expected is refused.
+//
+// Dependencies are injectable so the router is testable without Postgres.
+
+const express = require('express');
+const auth = require('../auth');
+const { validateOrRespond } = require('./_helpers');
+const log = require('../logger').logger.child({ src: 'payout-approvals' });
+
+const PERSONAL_REFUSALS = {
+  machine_principal: 'A machine identity can never approve money. A person must do this themselves.',
+  not_a_web_session: 'Approving money must be done by you, signed in on the website. A command-line or AI session cannot sign it.',
+  no_session: 'Sign in on the website to approve this.',
+};
+
+function cleanDoc(raw) {
+  // An equity grant or a contract: what it is and where the signed text lives.
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { error: 'terms must be an object with a title and summary' };
+  const known = new Set(['title', 'summary', 'document_ref']);
+  for (const k of Object.keys(raw)) if (!known.has(k)) return { error: `unknown term: ${k}` };
+  const text = (v) => (typeof v === 'string' ? v.replace(/\s+/g, ' ').trim() : '');
+  const title = text(raw.title);
+  const summary = text(raw.summary);
+  if (title.length < 3 || title.length > 120) return { error: 'terms.title must be 3 to 120 characters' };
+  if (summary.length < 3 || summary.length > 1000) return { error: 'terms.summary must be 3 to 1000 characters' };
+  const out = { title, summary };
+  if (raw.document_ref !== undefined && raw.document_ref !== null) {
+    const ref = text(raw.document_ref);
+    if (!ref || ref.length > 300) return { error: 'terms.document_ref must be up to 300 characters' };
+    out.document_ref = ref;
+  }
+  return { value: out };
+}
+
+module.exports = function buildPayoutApprovalsRouter({
+  store = require('../payout-approvals'),
+  gates = require('../payout-gates'),
+  requireBuilder = auth.requireBuilder,
+  requirePermission = auth.requirePermission,
+} = {}) {
+  const router = express.Router();
+
+  function personal(req, res) {
+    const p = store.personalSession(req);
+    if (!p.ok) {
+      res.fail('personal_approval_required', { status: 403, message: PERSONAL_REFUSALS[p.reason] || PERSONAL_REFUSALS.no_session });
+      return null;
+    }
+    return p.actor;
+  }
+
+  function dbRefusal(res, err, what) {
+    // The trigger's refusals (check_violation / insufficient_privilege) are the
+    // database saying no; anything else is a fault.
+    if (err && (err.code === '23514' || err.code === '42501')) {
+      res.fail('payout_refused', { status: 409, message: String(err.message || '').replace(/^payout_approvals:\s*/, '') });
+      return;
+    }
+    if (err && err.code === '23505') {
+      res.fail('already_recorded', { status: 409, message: 'This has already been recorded.' });
+      return;
+    }
+    if (err && err.code === '23503') {
+      res.fail('unknown_builder', { status: 400, message: 'That recipient is not a builder on this project.' });
+      return;
+    }
+    log.error({ err: err && err.message }, `${what} failed`);
+    res.fail('payout_write_failed', { status: 500, message: 'internal error' });
+  }
+
+  function single(body, res) {
+    if (Array.isArray(body) || (body && Object.values(body).some(Array.isArray))) {
+      res.fail('one_at_a_time', { status: 400, message: 'Approve one at a time: each payout, grant or contract is its own approval.' });
+      return false;
+    }
+    return true;
+  }
+
+  // GET /api/bongos/payouts/approvals — the log, newest first. ?rule_id= narrows it.
+  router.get('/payouts/approvals', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const ruleId = req.query.rule_id;
+    if (ruleId !== undefined && !store.isId(ruleId)) return res.fail('bad_rule_id', { status: 400, message: 'rule_id must be a number' });
+    try {
+      res.json({ approvals: await store.listLog({ ruleId: ruleId || null, limit: req.query.limit }) });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'GET /payouts/approvals failed');
+      res.fail('payout_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /api/bongos/payouts/rules — every standing rule with its current terms.
+  router.get('/payouts/rules', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    try {
+      res.json({ rules: await store.listRules() });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'GET /payouts/rules failed');
+      res.fail('payout_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /api/bongos/payouts/rules — sign a standing payout rule. Body: { terms, note? }.
+  router.post('/payouts/rules', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { terms: { required: true }, note: {} })) return;
+    const body = req.body || {};
+    const v = store.validateRuleTerms(body.terms);
+    if (v.errors) return res.fail('bad_terms', { status: 400, message: v.errors.join('; ') });
+    const note = store.cleanNote(body.note);
+    if (note.error) return res.fail('bad_note', { status: 400, message: note.error });
+    try {
+      const row = await store.insertEvent({ kind: 'rule_signed', actor, terms: v.terms, note: note.value });
+      res.status(201).json({ approval: row });
+    } catch (err) { dbRefusal(res, err, 'POST /payouts/rules'); }
+  });
+
+  // POST /api/bongos/payouts/rules/:id/narrow — tighten a rule. Body: { terms, note? }.
+  router.post('/payouts/rules/:id/narrow', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { terms: { required: true }, note: {} })) return;
+    if (!store.isId(req.params.id)) return res.fail('bad_rule_id', { status: 400, message: 'rule id must be a number' });
+    const body = req.body || {};
+    const v = store.validateRuleTerms(body.terms);
+    if (v.errors) return res.fail('bad_terms', { status: 400, message: v.errors.join('; ') });
+    const note = store.cleanNote(body.note);
+    if (note.error) return res.fail('bad_note', { status: 400, message: note.error });
+    try {
+      const { rule } = await store.readRule(req.params.id);
+      if (!rule) return res.fail('no_such_rule', { status: 404, message: 'No payout rule has that id.' });
+      if (!rule.active) return res.fail('rule_revoked', { status: 409, message: 'That rule is revoked. Sign a new one instead.' });
+      const widen = store.wideningReasons(rule.terms, v.terms);
+      if (widen.length) {
+        return res.fail('would_widen', { status: 409, message: `A narrowing can only tighten a rule, but ${widen.join(', ')}. To change that, sign a new rule.` });
+      }
+      const row = await store.insertEvent({ kind: 'rule_narrowed', rule_id: rule.id, actor, terms: v.terms, note: note.value });
+      res.status(201).json({ approval: row });
+    } catch (err) { dbRefusal(res, err, 'POST /payouts/rules/:id/narrow'); }
+  });
+
+  // POST /api/bongos/payouts/rules/:id/revoke — end a rule. Body: { note? }.
+  router.post('/payouts/rules/:id/revoke', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { note: {} })) return;
+    if (!store.isId(req.params.id)) return res.fail('bad_rule_id', { status: 400, message: 'rule id must be a number' });
+    const note = store.cleanNote((req.body || {}).note);
+    if (note.error) return res.fail('bad_note', { status: 400, message: note.error });
+    try {
+      const { rule } = await store.readRule(req.params.id);
+      if (!rule) return res.fail('no_such_rule', { status: 404, message: 'No payout rule has that id.' });
+      if (!rule.active) return res.fail('rule_revoked', { status: 409, message: 'That rule is already revoked.' });
+      const row = await store.insertEvent({ kind: 'rule_revoked', rule_id: rule.id, actor, note: note.value });
+      res.status(201).json({ approval: row });
+    } catch (err) { dbRefusal(res, err, 'POST /payouts/rules/:id/revoke'); }
+  });
+
+  // POST /api/bongos/payouts/rules/:id/runs — notice a run under a rule, opening
+  // its pause window. Authorises nothing by itself, so the runner may file it.
+  // Body: { run_key, payouts: [{ recipient_id, amount_cents }], note? }.
+  router.post('/payouts/rules/:id/runs', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    if (validateOrRespond(req, res, { run_key: {}, payouts: {}, note: {} })) return;
+    if (!store.isId(req.params.id)) return res.fail('bad_rule_id', { status: 400, message: 'rule id must be a number' });
+    const body = req.body || {};
+    if (typeof body.run_key !== 'string' || !store.RUN_KEY_RE.test(body.run_key)) {
+      return res.fail('bad_run_key', { status: 400, message: 'run_key must be 1 to 80 letters, digits or . _ : -' });
+    }
+    const payouts = body.payouts;
+    if (!Array.isArray(payouts) || payouts.length === 0 || payouts.length > 500
+        || payouts.some((p) => !p || !store.isId(p.recipient_id) || !store.isCents(p.amount_cents))) {
+      return res.fail('bad_payouts', { status: 400, message: 'payouts must list each recipient_id with a whole number of cents above zero' });
+    }
+    const note = store.cleanNote(body.note);
+    if (note.error) return res.fail('bad_note', { status: 400, message: note.error });
+    try {
+      const { rule } = await store.readRule(req.params.id);
+      if (!rule) return res.fail('no_such_rule', { status: 404, message: 'No payout rule has that id.' });
+      if (!rule.active) return res.fail('rule_revoked', { status: 409, message: 'That rule is revoked; nothing can run under it.' });
+      const total = payouts.reduce((s, p) => s + p.amount_cents, 0);
+      const caps = rule.terms.caps;
+      if (payouts.some((p) => p.amount_cents > caps.per_payout_cents) || total > caps.per_run_cents) {
+        return res.fail('over_cap', { status: 409, message: 'This run is over the caps the rule was signed with.' });
+      }
+      // N10: every recipient passes the age and sanctions gates. A recipient who
+      // does not is told why and how to appeal (a hold is filed for the money they
+      // are owed); the run is refused until it is re-noticed without them.
+      const owed = new Map();
+      for (const p of payouts) owed.set(String(p.recipient_id), (owed.get(String(p.recipient_id)) || 0) + p.amount_cents);
+      const held = [];
+      for (const [rid, g] of await gates.gateOwedPayMany(owed)) {
+        if (!g.ok) held.push({ recipient_id: rid, reason: g.reason, freeze_id: g.freeze_id });
+      }
+      if (held.length) {
+        return res.fail('payout_gated', { status: 409, message: 'Some recipients cannot be paid yet. Each has been told why and how to appeal; notice the run again without them, or once their hold is lifted.', details: { held } });
+      }
+      const row = await store.insertEvent({
+        kind: 'run_noticed',
+        rule_id: rule.id,
+        run_key: body.run_key,
+        actor: { id: req.builder.id, rank: req.builder.rank || null, session_id: req.gdsSession ? req.gdsSession.session_id : null, session_source: req.gdsSession ? req.gdsSession.source : null },
+        amount_cents: total,
+        currency: rule.terms.currency,
+        terms: { payouts: payouts.map((p) => ({ recipient_id: String(p.recipient_id), amount_cents: p.amount_cents })) },
+        note: note.value,
+      });
+      const opensAt = new Date(new Date(row.created_at).getTime() + rule.terms.pause_hours * 3600_000).toISOString();
+      res.status(201).json({ approval: row, pays_from: opensAt });
+    } catch (err) { dbRefusal(res, err, 'POST /payouts/rules/:id/runs'); }
+  });
+
+  // POST /api/bongos/payouts/rules/:id/runs/:runKey/hold — a person stops a run
+  // in its pause window. Body: { note? }.
+  router.post('/payouts/rules/:id/runs/:runKey/hold', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { note: {} })) return;
+    if (!store.isId(req.params.id)) return res.fail('bad_rule_id', { status: 400, message: 'rule id must be a number' });
+    if (!store.RUN_KEY_RE.test(req.params.runKey)) return res.fail('bad_run_key', { status: 400, message: 'unknown run' });
+    const note = store.cleanNote((req.body || {}).note);
+    if (note.error) return res.fail('bad_note', { status: 400, message: note.error });
+    try {
+      const { rule, events } = await store.readRule(req.params.id);
+      // A run may be held whenever it exists, is not held already and its rule
+      // stands — inside the pause window or after it, until it is paid. Nothing
+      // else about the run (caps, its payouts) decides whether stopping it is allowed.
+      if (!rule) return res.fail('no_such_rule', { status: 404, message: 'No payout rule has that id.' });
+      if (!rule.active) return res.fail('rule_revoked', { status: 409, message: 'That rule is revoked; nothing under it can pay.' });
+      const mine = events.filter((e) => e.run_key === req.params.runKey);
+      if (!mine.some((e) => e.kind === 'run_noticed')) return res.fail('run_not_noticed', { status: 404, message: 'There is no run with that key to hold.' });
+      if (mine.some((e) => e.kind === 'run_held')) return res.fail('already_recorded', { status: 409, message: 'That run is already held.' });
+      const row = await store.insertEvent({ kind: 'run_held', rule_id: rule.id, run_key: req.params.runKey, actor, note: note.value });
+      res.status(201).json({ approval: row });
+    } catch (err) { dbRefusal(res, err, 'POST /payouts/rules/:id/runs/:runKey/hold'); }
+  });
+
+  // POST /api/bongos/payouts/approve — approve ONE payout.
+  // Body: { recipient_id, amount_cents, currency, note? }.
+  router.post('/payouts/approve', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { recipient_id: {}, amount_cents: {}, currency: {}, note: {} })) return;
+    const body = req.body || {};
+    if (!single(body, res)) return;
+    if (!store.isId(body.recipient_id)) return res.fail('bad_recipient', { status: 400, message: 'recipient_id must be a builder id' });
+    if (!store.isCents(body.amount_cents)) return res.fail('bad_amount', { status: 400, message: 'amount_cents must be a whole number of cents above zero' });
+    if (typeof body.currency !== 'string' || !/^[A-Z]{3}$/.test(body.currency)) return res.fail('bad_currency', { status: 400, message: 'currency must be a three-letter code such as USD' });
+    const note = store.cleanNote(body.note);
+    if (note.error) return res.fail('bad_note', { status: 400, message: note.error });
+    try {
+      const g = await gates.gateOwedPay(body.recipient_id, { owedCents: body.amount_cents });
+      if (!g.ok) {
+        return res.fail('payout_gated', { status: 409, message: 'This person cannot be paid yet. They have been told why and how to appeal.', details: { reason: g.reason, freeze_id: g.freeze_id } });
+      }
+      const row = await store.insertEvent({ kind: 'payout_approved', actor, recipient_id: body.recipient_id, amount_cents: body.amount_cents, currency: body.currency, note: note.value });
+      res.status(201).json({ approval: row });
+    } catch (err) { dbRefusal(res, err, 'POST /payouts/approve'); }
+  });
+
+  // POST /api/bongos/payouts/grants and /payouts/contracts — sign ONE equity grant
+  // or ONE contract. Body: { recipient_id, terms: { title, summary, document_ref? }, note? }.
+  async function signDoc(req, res, path, kind) {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { recipient_id: {}, terms: { required: true }, note: {} })) return;
+    const body = req.body || {};
+    if (!single(body, res)) return;
+    if (!store.isId(body.recipient_id)) return res.fail('bad_recipient', { status: 400, message: 'recipient_id must be a builder id' });
+    const doc = cleanDoc(body.terms);
+    if (doc.error) return res.fail('bad_terms', { status: 400, message: doc.error });
+    const note = store.cleanNote(body.note);
+    if (note.error) return res.fail('bad_note', { status: 400, message: note.error });
+    try {
+      // A grant or contract is not money owed yet, so a refusal files no hold; it
+      // is refused on the same age and sanctions rules, with the reason.
+      const g = await gates.gateRecipient(body.recipient_id);
+      if (!g.ok) return res.fail('payout_gated', { status: 409, message: 'This person cannot receive this yet.', details: { reason: g.reason, freeze_id: g.freeze_id || null } });
+      const row = await store.insertEvent({ kind, actor, recipient_id: body.recipient_id, terms: doc.value, note: note.value });
+      res.status(201).json({ approval: row });
+    } catch (err) { dbRefusal(res, err, 'POST ' + path); }
+  }
+
+  // POST /api/bongos/payouts/grants — sign ONE equity grant.
+  // Body: { recipient_id, terms: { title, summary, document_ref? }, note? }.
+  router.post('/payouts/grants', requireBuilder, requirePermission('payout.approve'), (req, res) => signDoc(req, res, '/payouts/grants', 'grant_signed'));
+
+  // POST /api/bongos/payouts/contracts — sign ONE contract. Body as for grants.
+  router.post('/payouts/contracts', requireBuilder, requirePermission('payout.approve'), (req, res) => signDoc(req, res, '/payouts/contracts', 'contract_signed'));
+
+  return router;
+};

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

@@ -0,0 +1,179 @@
+'use strict';
+
+// src/bongos/routes/payout-gates.js — the approver's side of the payout gates
+// (task 1004914, goal 1000092 N10; ADR 0385 decision 8).
+//
+// WHY. The gates themselves run inside every money route (../payout-gates.js,
+// called from routes/payout-approvals.js and from checkRun / checkApproval). This
+// file is where their facts are recorded — an age tier, a guardian link, a
+// sanctions screening, a hand-made hold — and where an appeal is decided. The
+// person whose pay is held reads why and appeals in routes/my-payouts.js (the
+// framework, cited by Article only, forbids withholding earned pay silently).
+//
+// GATES. Recording a fact about someone else needs requireBuilder +
+// requirePermission('payout.approve') (fresh per request, ADR 0016) AND the
+// person's own web session — the same rule as signing a payout, because each of
+// these decides whether money moves.
+//
+// Dependencies are injectable so the router is testable without Postgres.
+
+const express = require('express');
+const auth = require('../auth');
+const { validateOrRespond } = require('./_helpers');
+const log = require('../logger').logger.child({ src: 'payout-gates' });
+
+// The refusals core_284's triggers raise, word for word. Only these reach the
+// person; tests/payout_gates.mjs reads each one out of the migration and feeds it
+// through the route, so a reworded trigger cannot silently fall back to the
+// generic line.
+const OUR_REFUSALS = Object.freeze([
+  /^only the person whose pay is frozen may appeal it$/,
+  /^a person may not decide the appeal on their own freeze$/,
+  /^only the builder's current guardian may co-sign their payout$/,
+  /^payout freeze \d+ is already lifted$/,
+  /^payout_[a-z_]+ is append-only: (UPDATE|DELETE|TRUNCATE) refused \(a correction is a new row\)$/,
+]);
+
+const PERSONAL_REFUSAL ='This must be done by the person themselves, signed in on the website. A command-line or AI session cannot do it.';
+
+function buildPayoutGatesRouter({
+  gates = require('../payout-gates'),
+  approvals = require('../payout-approvals'),
+  requireBuilder = auth.requireBuilder,
+  requirePermission = auth.requirePermission,
+} = {}) {
+  const router = express.Router();
+
+  function personal(req, res) {
+    const p = approvals.personalSession(req);
+    if (!p.ok) {
+      res.fail('personal_approval_required', { status: 403, message: PERSONAL_REFUSAL });
+      return null;
+    }
+    return p.actor;
+  }
+
+  function fault(res, err, what) {
+    // A trigger refusal is the database saying no. Its words are passed on only
+    // when they are one of this file's own plain-language rules (core_284); any
+    // other database text stays in the log, never in the response.
+    if (err && (err.code === '23514' || err.code === '42501')) {
+      const said = String(err.message || '');
+      const ours = OUR_REFUSALS.some((re) => re.test(said));
+      if (!ours) log.warn({ err: said }, `${what} refused by the database`);
+      return res.fail('payout_refused', { status: 409, message: ours ? said : 'The payout rules refused this.' });
+    }
+    if (err && err.code === '23505') return res.fail('already_recorded', { status: 409, message: 'This has already been recorded.' });
+    if (err && err.code === '23503') return res.fail('unknown_builder', { status: 400, message: 'That is not a builder on this project.' });
+    log.error({ err: err && err.message }, `${what} failed`);
+    return res.fail('payout_gate_failed', { status: 500, message: 'internal error' });
+  }
+
+  const statement = (raw, max) => (typeof raw === 'string' ? raw.replace(/\s+/g, ' ').trim() : '').slice(0, max + 1);
+
+  // GET /api/bongos/payouts/gates/:builderId — may this builder be paid now, and why not.
+  router.get('/payouts/gates/:builderId', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    if (!approvals.isId(req.params.builderId)) return res.fail('bad_builder_id', { status: 400, message: 'builder id must be a number' });
+    try {
+      const v = await gates.gateRecipient(req.params.builderId);
+      res.json({ gate: gates.present(v) });
+    } catch (err) { fault(res, err, 'GET /payouts/gates/:builderId'); }
+  });
+
+  // POST /api/bongos/payouts/age-records — record a builder's age tier, verified by a person.
+  // Body: { builder_id, tier }.
+  router.post('/payouts/age-records', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { builder_id: { required: true }, tier: { required: true } })) return;
+    const b = req.body;
+    if (!approvals.isId(b.builder_id)) return res.fail('bad_builder_id', { status: 400, message: 'builder_id must be a number' });
+    if (!gates.AGE_TIERS.includes(b.tier)) return res.fail('bad_tier', { status: 400, message: `tier must be one of ${gates.AGE_TIERS.join(', ')}` });
+    try {
+      res.status(201).json({ record: await gates.recordAge({ builderId: b.builder_id, tier: b.tier, basis: 'verified_by_person', recordedBy: actor.id }) });
+    } catch (err) { fault(res, err, 'POST /payouts/age-records'); }
+  });
+
+  // POST /api/bongos/payouts/guardians — link (or unlink) a 16-17 builder's guardian
+  // and the account the guardian controls. Body: { builder_id, guardian_id, guardian_account?, active }.
+  router.post('/payouts/guardians', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { builder_id: { required: true }, guardian_id: { required: true }, guardian_account: {}, active: { required: true } })) return;
+    const b = req.body;
+    if (!approvals.isId(b.builder_id) || !approvals.isId(b.guardian_id)) return res.fail('bad_builder_id', { status: 400, message: 'builder_id and guardian_id must be numbers' });
+    if (String(b.builder_id) === String(b.guardian_id)) return res.fail('guardian_is_self', { status: 400, message: 'A builder cannot be their own guardian.' });
+    if (typeof b.active !== 'boolean') return res.fail('bad_active', { status: 400, message: 'active must be true or false' });
+    const account = b.guardian_account == null ? null : statement(b.guardian_account, 200);
+    if (b.active && (!account || account.length < 3 || account.length > 200)) {
+      return res.fail('bad_guardian_account', { status: 400, message: 'An active guardian link must name the account the guardian controls (3 to 200 characters).' });
+    }
+    try {
+      res.status(201).json({ record: await gates.recordGuardian({ builderId: b.builder_id, guardianId: b.guardian_id, guardianAccount: account, active: b.active, recordedBy: actor.id }) });
+    } catch (err) { fault(res, err, 'POST /payouts/guardians'); }
+  });
+
+  // POST /api/bongos/payouts/screenings — record a sanctions screening a person ran.
+  // Body: { builder_id, result: clear|match|error, reference?, valid_days? }.
+  router.post('/payouts/screenings', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { builder_id: { required: true }, result: { required: true }, reference: {}, valid_days: {} })) return;
+    const b = req.body;
+    if (!approvals.isId(b.builder_id)) return res.fail('bad_builder_id', { status: 400, message: 'builder_id must be a number' });
+    if (!gates.SCREEN_RESULTS.includes(b.result)) return res.fail('bad_result', { status: 400, message: `result must be one of ${gates.SCREEN_RESULTS.join(', ')}` });
+    let validUntil = null;
+    if (b.result === 'clear') {
+      if (!Number.isSafeInteger(b.valid_days) || b.valid_days < 1 || b.valid_days > gates.MAX_SCREEN_DAYS) {
+        return res.fail('bad_valid_days', { status: 400, message: `A clear result needs valid_days from 1 to ${gates.MAX_SCREEN_DAYS}.` });
+      }
+      validUntil = new Date(Date.now() + b.valid_days * 86_400_000).toISOString();
+    }
+    const reference = b.reference == null ? null : statement(b.reference, 200);
+    if (reference !== null && reference.length > 200) return res.fail('bad_reference', { status: 400, message: 'reference must be up to 200 characters' });
+    const login = String(req.builder.github_login || actor.id).replace(/[^A-Za-z0-9._-]/g, '').slice(0, 60) || String(actor.id);
+    try {
+      res.status(201).json({ record: await gates.recordScreening({ builderId: b.builder_id, result: b.result, screenedBy: `person:${login}`, reference, validUntil, recordedBy: actor.id }) });
+    } catch (err) { fault(res, err, 'POST /payouts/screenings'); }
+  });
+
+  // POST /api/bongos/payouts/freezes — a person freezes a builder's payouts by hand.
+  // The notice is required: there is no silent freeze. Body: { builder_id, notice_text, owed_cents? }.
+  router.post('/payouts/freezes', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { builder_id: { required: true }, notice_text: { required: true }, owed_cents: {} })) return;
+    const b = req.body;
+    if (!approvals.isId(b.builder_id)) return res.fail('bad_builder_id', { status: 400, message: 'builder_id must be a number' });
+    const notice = statement(b.notice_text, 1000);
+    if (notice.length < 20 || notice.length > 1000) return res.fail('bad_notice', { status: 400, message: 'notice_text must say, in 20 to 1000 characters, what is held and why. The person reads it.' });
+    if (b.owed_cents != null && !approvals.isCents(b.owed_cents)) return res.fail('bad_amount', { status: 400, message: 'owed_cents must be a whole number of cents above zero' });
+    try {
+      res.status(201).json({ freeze: await gates.freezeManually({ builderId: b.builder_id, noticeText: notice, owedCents: b.owed_cents ?? null, frozenBy: actor.id }) });
+    } catch (err) { fault(res, err, 'POST /payouts/freezes'); }
+  });
+
+  // POST /api/bongos/payouts/freezes/:id/decide — uphold or lift a freeze, with the
+  // reason the person will read. Body: { decision: upheld|lifted, statement }.
+  router.post('/payouts/freezes/:id/decide', requireBuilder, requirePermission('payout.approve'), async (req, res) => {
+    const actor = personal(req, res);
+    if (!actor) return;
+    if (validateOrRespond(req, res, { decision: { required: true }, statement: { required: true } })) return;
+    if (!approvals.isId(req.params.id)) return res.fail('bad_freeze_id', { status: 400, message: 'freeze id must be a number' });
+    const { decision } = req.body;
+    if (decision !== 'upheld' && decision !== 'lifted') return res.fail('bad_decision', { status: 400, message: 'decision must be upheld or lifted' });
+    const words = statement(req.body.statement, 2000);
+    if (!words || words.length > 2000) return res.fail('bad_statement', { status: 400, message: 'statement must say why, in up to 2000 characters. The person reads it.' });
+    try {
+      const f = await gates.readFreeze(req.params.id);
+      if (!f) return res.fail('no_such_freeze', { status: 404, message: 'No freeze has that id.' });
+      if (f.lifted) return res.fail('already_lifted', { status: 409, message: 'That freeze is already lifted.' });
+      if (String(f.builder_id) === String(actor.id)) return res.fail('own_freeze', { status: 403, message: 'You cannot decide a freeze on your own pay.' });
+      res.status(201).json({ event: await gates.addFreezeEvent({ freezeId: f.id, kind: decision, actorId: actor.id, statement: words }) });
+    } catch (err) { fault(res, err, 'POST /payouts/freezes/:id/decide'); }
+  });
+
+  return router;
+};
+buildPayoutGatesRouter.OUR_REFUSALS = OUR_REFUSALS;
+module.exports = buildPayoutGatesRouter;