@bongos/core 1.23.21 → 1.24.1

package/tests/payout_gates.mjs

@@ -0,0 +1,322 @@
+// tests/payout_gates.mjs — who may be paid at all (task 1004914, ADR 0385 D8).
+// DB-free: the gate's decision, its wiring into every money route and pay-time
+// check, the holds a person reads and appeals, and the needs list that tells them.
+// Pins: under 13 and 13-15 are paid no money; 16-17 only with an active guardian
+// link to a guardian-controlled account AND the guardian's co-signature; a
+// sanctions match or a missing/expired clear screening stops pay; a screening the
+// processor reports does not count until its scope is confirmed in writing; owed
+// pay that is refused always files a hold with a notice and an appeal route.
+// Run:  node tests/payout_gates.mjs
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import http from 'node:http';
+const require = createRequire(import.meta.url);
+const express = require('express');
+const gates = require('../src/bongos/payout-gates');
+const approvals = require('../src/bongos/payout-approvals');
+const buildGates = require('../src/bongos/routes/payout-gates');
+const buildMine = require('../src/bongos/routes/my-payouts');
+const buildApprovals = require('../src/bongos/routes/payout-approvals');
+const needs = require('../modules/builder-settings/builder-needs');
+
+let n = 0;
+const ok = (name) => { n++; console.log(`ok - ${name}`); };
+const NOW = new Date('2026-10-29T12:00:00Z');
+const LATER = '2027-01-01T00:00:00Z';
+const adult = [{ id: '1', tier: 'adult' }];
+const clear = [{ id: '1', result: 'clear', screened_by: 'person:owner', valid_until: LATER }];
+const d = (f) => gates.decide({ ageRecords: adult, screenings: clear, now: NOW, ...f });
+
+// ── 1. the decision ──────────────────────────────────────────────────────
+{
+  assert.deepEqual(d({}), { ok: true, pay_to: 'self', needs_guardian_cosign: false }); ok('an adult with a clear screening is paid to themselves');
+  assert.equal(d({ ageRecords: [] }).reason, 'age_unknown'); ok('no age recorded: not paid');
+  assert.equal(d({ ageRecords: [{ tier: 'under_13' }] }).reason, 'age_no_money'); ok('under 13: no money');
+  assert.equal(d({ ageRecords: [{ tier: '13_15' }] }).reason, 'age_no_money'); ok('13 to 15: no money at all');
+  assert.equal(d({ ageRecords: [{ tier: '16_17' }] }).reason, 'age_needs_guardian'); ok('16-17 with no guardian: not paid');
+  assert.equal(d({ ageRecords: [{ tier: '16_17' }], guardians: [{ guardian_id: '9', guardian_account: 'acct_g', active: false }] }).reason, 'age_needs_guardian'); ok('16-17 with an ended guardian link: not paid');
+  const minor = d({ ageRecords: [{ tier: '16_17' }], guardians: [{ guardian_id: '9', guardian_account: 'acct_g', active: true }] });
+  assert.deepEqual(minor.pay_to, { guardian_id: '9', guardian_account: 'acct_g' }); assert.equal(minor.needs_guardian_cosign, true); ok('16-17 is paid only into the guardian\'s account, and needs their co-signature');
+  assert.equal(d({ ageRecords: [{ tier: 'adult' }, { tier: '13_15' }] }).reason, 'age_no_money'); ok('the latest age record wins');
+  assert.equal(d({ screenings: [] }).reason, 'sanctions_unscreened'); ok('never screened: not paid');
+  assert.equal(d({ screenings: [{ ...clear[0], valid_until: '2026-01-01T00:00:00Z' }] }).reason, 'sanctions_unscreened'); ok('an expired clear screening does not count');
+  assert.equal(d({ screenings: [{ result: 'error', screened_by: 'person:o' }] }).reason, 'sanctions_unscreened'); ok('a screening that errored does not count as clear');
+  assert.equal(d({ screenings: [...clear, { result: 'match', screened_by: 'person:o' }] }).reason, 'sanctions_match'); ok('a sanctions match stops pay');
+  assert.equal(gates.PROCESSOR_SCREENING_CONFIRMED, null);
+  assert.equal(d({ screenings: [{ result: 'clear', screened_by: 'processor:any', valid_until: LATER }] }).reason, 'sanctions_unscreened'); ok('a processor screening is not relied on until what it screens is confirmed');
+  const f = d({ freezes: [{ id: '4', reason: 'manual' }] });
+  assert.equal(f.reason, 'frozen'); assert.equal(f.freeze_id, '4'); ok('an open hold stops pay');
+  assert.equal(d({ freezes: [{ id: '4', reason: 'manual' }], freezeEvents: [{ freeze_id: '4', kind: 'lifted' }] }).ok, true); ok('a lifted hold does not');
+  assert.equal(d({ freezes: [{ id: '4' }], freezeEvents: [{ freeze_id: '4', kind: 'appealed' }] }).reason, 'frozen'); ok('an appeal alone does not lift a hold');
+  for (const r of ['sanctions_match', 'sanctions_unscreened', 'age_no_money', 'age_needs_guardian', 'age_unknown']) {
+    assert.ok(gates.NOTICES[r] && gates.NOTICES[r].length >= 20 && gates.NOTICES[r].length <= 1000, r);
+    assert.match(gates.NOTICES[r], /appeal/i, r);
+  }
+  ok('every automatic hold has a notice that names the appeal, within the table\'s length rule');
+}
+
+// ── 2. gateOwedPay files a hold, never a silent refusal ────────────────────
+function fakeDb({ facts = {}, open = null } = {}) {
+  const calls = [];
+  const pool = {
+    query: async (sql, params) => {
+      calls.push(sql);
+      // the hold's INSERT names payout_freeze_events in its NOT EXISTS, so it is matched first
+      if (/INSERT INTO payout_freezes/.test(sql)) {
+        if (open) return { rows: [] };
+        assert.ok(params[2] && params[3], 'a hold is filed with its notice and appeal route');
+        return { rows: [{ id: 77 }] };
+      }
+      if (/SELECT f\.id FROM payout_freezes/.test(sql)) return { rows: open ? [{ id: open }] : [] };
+      if (/FROM payout_age_records/.test(sql)) return { rows: facts.ageRecords || [] };
+      if (/FROM payout_guardians/.test(sql)) return { rows: facts.guardians || [] };
+      if (/FROM payout_screenings/.test(sql)) return { rows: facts.screenings || [] };
+      if (/FROM payout_freezes WHERE builder_id/.test(sql)) return { rows: facts.freezes || [] };
+      if (/FROM payout_freeze_events/.test(sql)) return { rows: [] };
+      throw new Error('unexpected sql ' + sql);
+    },
+  };
+  return { pool, calls };
+}
+{
+  let db = fakeDb({ facts: { ageRecords: adult, screenings: [] } });
+  let g = await gates.gateOwedPay('8', { owedCents: 500, now: NOW, pool: db.pool });
+  assert.equal(g.ok, false); assert.equal(g.reason, 'sanctions_unscreened'); assert.equal(g.freeze_id, '77'); assert.match(g.notice, /sanctions check/);
+  assert.ok(db.calls.some((s) => /INSERT INTO payout_freezes/.test(s))); ok('refused owed pay files a hold with its notice');
+  db = fakeDb({ facts: { ageRecords: adult, screenings: [] }, open: 55 });
+  g = await gates.gateOwedPay('8', { owedCents: 500, now: NOW, pool: db.pool });
+  assert.equal(g.freeze_id, '55'); ok('a second refusal for the same reason reuses the open hold');
+  db = fakeDb({ facts: { ageRecords: adult, screenings: clear } });
+  g = await gates.gateOwedPay('8', { owedCents: 500, now: NOW, pool: db.pool });
+  assert.equal(g.ok, true); assert.ok(!db.calls.some((s) => /INSERT/.test(s))); ok('payable pay files nothing');
+  db = fakeDb({ facts: { ageRecords: adult, screenings: clear, freezes: [{ id: 3, reason: 'manual' }] } });
+  g = await gates.gateOwedPay('8', { now: NOW, pool: db.pool });
+  assert.equal(g.reason, 'frozen'); assert.ok(!db.calls.some((s) => /INSERT/.test(s))); ok('an existing hold is reported, not filed twice');
+}
+
+// ── 3. the routes over real HTTP ─────────────────────────────────────────
+const recorded = [];
+const freezes = { 5: { id: '5', builder_id: '8', lifted: false, events: [] }, 6: { id: '6', builder_id: '8', lifted: true, events: [] } };
+let verdict = { ok: false, reason: 'sanctions_unscreened', freeze_id: '5', facts: { freezes: [{ id: '5', reason: 'sanctions_unscreened', notice_text: gates.NOTICES.sanctions_unscreened, frozen_at: 'x' }], freezeEvents: [] } };
+const fakeGates = {
+  ...gates,
+  gateRecipient: async () => verdict,
+  gateOwedPay: async () => (verdict.ok ? { ok: true, pay_to: 'self' } : { ok: false, reason: verdict.reason, freeze_id: verdict.freeze_id }),
+  gateOwedPayMany: async (m) => new Map([...m.keys()].map((k) => [k, verdict.ok ? { ok: true, pay_to: 'self' } : { ok: false, reason: verdict.reason, freeze_id: verdict.freeze_id }])),
+  readFreeze: async (id) => freezes[id] || null,
+  recordAge: async (r) => { recorded.push(['age', r]); return { id: '1', ...r }; },
+  recordGuardian: async (r) => { recorded.push(['guardian', r]); return { id: '1' }; },
+  recordScreening: async (r) => { recorded.push(['screening', r]); return { id: '1' }; },
+  freezeManually: async (r) => { recorded.push(['freeze', r]); return { id: '9' }; },
+  addFreezeEvent: async (r) => { recorded.push(['event', r]); return { id: '1', ...r }; },
+  recordCosign: async (r) => { recorded.push(['cosign', r]); return { id: '1' }; },
+  cosignAsGuardian: async (r) => { recorded.push(['cosign', r]); return r.approvalId === 404 ? [] : [{ id: '1', builder_id: '8' }]; },
+};
+let who = { builder: { id: '7', rank: 'archon', system_role: null, github_login: 'owner' }, gdsSession: { source: 'web', session_id: '91' } };
+const gated = [];
+const app = express();
+app.use(express.json());
+app.use((req, res, next) => { res.fail = (code, o = {}) => res.status(o.status || 400).json({ error: code, message: o.message, details: o.details }); next(); });
+app.use((req, res, next) => { req.builder = who.builder; req.gdsSession = who.gdsSession; next(); });
+app.use('/', buildGates({ gates: fakeGates, requireBuilder: (q, r, nx) => nx(), requirePermission: (...p) => { gated.push(p.join(',')); return (q, r, nx) => nx(); } }));
+app.use('/', buildMine({ gates: fakeGates, requireBuilder: (q, r, nx) => nx() }));
+const store = { ...approvals, insertEvent: async (e) => { recorded.push(['approval', e.kind]); return { id: '50', kind: e.kind, created_at: NOW.toISOString() }; }, readRule: async () => ({ rule: { id: '1', active: true, terms: { caps: { per_payout_cents: 1000, per_run_cents: 5000 }, currency: 'USD', pause_hours: 1 } }, events: [] }) };
+app.use('/', buildApprovals({ store, gates: fakeGates, requireBuilder: (q, r, nx) => nx(), requirePermission: () => (q, r, nx) => nx() }));
+const server = http.createServer(app).listen(0);
+const port = server.address().port;
+const call = (method, path, body) => new Promise((resolve) => {
+  const r = http.request({ port, path, method, headers: { 'content-type': 'application/json' } }, (res) => {
+    let s = ''; res.on('data', (c) => (s += c)); res.on('end', () => { let b = null; try { b = JSON.parse(s); } catch { /* not json */ } resolve({ status: res.statusCode, body: b }); });
+  });
+  if (body) r.write(JSON.stringify(body));
+  r.end();
+});
+
+try {
+  assert.ok(gated.length >= 6 && gated.every((g) => g === 'payout.approve')); ok('every approver route gates on payout.approve');
+
+  // every money route refuses a gated recipient, with the reason and the hold
+  let r = await call('POST', '/payouts/approve', { recipient_id: 8, amount_cents: 100, currency: 'USD' });
+  assert.equal(r.status, 409); assert.equal(r.body.error, 'payout_gated'); assert.equal(r.body.details.freeze_id, '5'); assert.ok(!recorded.some((x) => x[0] === 'approval')); ok('approving a payout to a gated person is refused, naming the hold they were told about');
+  r = await call('POST', '/payouts/rules/1/runs', { run_key: 'w1', payouts: [{ recipient_id: 8, amount_cents: 100 }] });
+  assert.equal(r.status, 409); assert.equal(r.body.details.held[0].reason, 'sanctions_unscreened'); ok('a run with a gated recipient is refused, listing who and why');
+  r = await call('POST', '/payouts/grants', { recipient_id: 8, terms: { title: 'Grant', summary: 'one grant' } });
+  assert.equal(r.status, 409); ok('an equity grant to a gated person is refused');
+  r = await call('POST', '/payouts/contracts', { recipient_id: 8, terms: { title: 'Contract', summary: 'one contract' } });
+  assert.equal(r.status, 409); ok('a contract with a gated person is refused');
+  verdict = { ok: true, pay_to: 'self', facts: {} };
+  r = await call('POST', '/payouts/approve', { recipient_id: 8, amount_cents: 100, currency: 'USD' });
+  assert.equal(r.status, 201); ok('a payable person passes');
+
+  // recording the facts: a person's own web session only
+  who = { ...who, gdsSession: { source: 'cli', session_id: '92' } };
+  for (const [p, b] of [['/payouts/age-records', { builder_id: 8, tier: 'adult' }], ['/payouts/guardians', { builder_id: 8, guardian_id: 9, guardian_account: 'acct', active: true }], ['/payouts/screenings', { builder_id: 8, result: 'clear', valid_days: 30 }], ['/payouts/freezes', { builder_id: 8, notice_text: 'Your pay is held while we check something.' }], ['/payouts/freezes/5/decide', { decision: 'lifted', statement: 'ok' }], ['/me/payout-age', { tier: 'adult' }], ['/me/payout-freezes/5/appeal', { statement: 'wrong' }], ['/me/guardian-cosigns', { approval_id: 50 }]]) {
+    const before = recorded.length;
+    r = await call('POST', p, b);
+    assert.equal(r.status, 403, p); assert.equal(r.body.error, 'personal_approval_required'); assert.equal(recorded.length, before, p);
+  }
+  ok('an AI (CLI) session can record no age, guardian, screening, hold, decision, appeal or co-signature');
+  who = { builder: { id: '7', rank: 'archon', system_role: null, github_login: 'owner' }, gdsSession: { source: 'web', session_id: '91' } };
+
+  r = await call('POST', '/payouts/age-records', { builder_id: 8, tier: 'adult', basis: 'self_declared' });
+  assert.equal(r.status, 400); ok('an approver cannot choose the basis of an age record: it is always verified_by_person');
+  r = await call('POST', '/payouts/age-records', { builder_id: 8, tier: '13_15' });
+  assert.equal(r.status, 201); assert.equal(recorded.at(-1)[1].basis, 'verified_by_person'); ok('a person records a verified age tier');
+  r = await call('POST', '/me/payout-age', { tier: 'adult' });
+  assert.equal(r.status, 201); assert.equal(recorded.at(-1)[1].builderId, '7'); assert.equal(recorded.at(-1)[1].basis, 'self_declared'); ok('a builder declares only their own age, marked self-declared');
+  r = await call('POST', '/payouts/guardians', { builder_id: 8, guardian_id: 9, active: true });
+  assert.equal(r.status, 400); ok('an active guardian link must name the guardian-controlled account');
+  r = await call('POST', '/payouts/guardians', { builder_id: 8, guardian_id: 8, guardian_account: 'acct', active: true });
+  assert.equal(r.status, 400); ok('nobody is their own guardian');
+  r = await call('POST', '/payouts/screenings', { builder_id: 8, result: 'clear' });
+  assert.equal(r.status, 400); ok('a clear screening must say how long it counts');
+  r = await call('POST', '/payouts/screenings', { builder_id: 8, result: 'clear', valid_days: 90 });
+  assert.equal(r.status, 201); assert.equal(recorded.at(-1)[1].screenedBy, 'person:owner'); assert.ok(recorded.at(-1)[1].validUntil); ok('a person records a screening under their own name, with an expiry');
+  r = await call('POST', '/payouts/freezes', { builder_id: 8, notice_text: 'short' });
+  assert.equal(r.status, 400); ok('a hand-made hold needs a real notice: there is no silent freeze');
+
+  r = await call('POST', '/payouts/freezes/5/decide', { decision: 'lifted', statement: 'Screening came back clear.' });
+  assert.equal(r.status, 201); ok('an approver lifts a hold with a reason the person reads');
+  r = await call('POST', '/payouts/freezes/6/decide', { decision: 'upheld', statement: 'x' });
+  assert.equal(r.status, 409); ok('a lifted hold is not decided again');
+  who = { ...who, builder: { ...who.builder, id: '8' } };
+  r = await call('POST', '/payouts/freezes/5/decide', { decision: 'lifted', statement: 'mine' });
+  assert.equal(r.status, 403); ok('nobody decides the hold on their own pay');
+  r = await call('POST', '/me/payout-freezes/5/appeal', { statement: 'I am not that person.' });
+  assert.equal(r.status, 201); assert.equal(recorded.at(-1)[1].kind, 'appealed'); ok('the person appeals their own hold');
+  who = { ...who, builder: { ...who.builder, id: '7' } };
+  r = await call('POST', '/me/payout-freezes/5/appeal', { statement: 'not mine' });
+  assert.equal(r.status, 404); ok('nobody appeals a hold on someone else\'s pay');
+
+  r = await call('POST', '/me/guardian-cosigns', { approval_id: 50, rule_id: 1, run_key: 'w1' });
+  assert.equal(r.status, 400); ok('a co-signature names one payout, not two');
+  r = await call('POST', '/me/guardian-cosigns', { builder_id: 8, approval_id: 50 });
+  assert.equal(r.status, 400); ok('a guardian cannot name whose payout it is: that comes from the payout');
+  r = await call('POST', '/me/guardian-cosigns', { approval_id: 50 });
+  assert.equal(r.status, 201); assert.equal(recorded.at(-1)[1].guardianId, '7'); ok('a guardian co-signs as themselves (the database checks they are the guardian)');
+  r = await call('POST', '/me/guardian-cosigns', { approval_id: 404 });
+  assert.equal(r.status, 404); ok('a payout to nobody they are guardian for is refused');
+
+  verdict = { ok: false, reason: 'sanctions_unscreened', facts: { ageRecords: adult, freezes: [{ id: '5', reason: 'sanctions_unscreened', notice_text: gates.NOTICES.sanctions_unscreened, frozen_at: 'x' }], freezeEvents: [{ freeze_id: '5', kind: 'appealed', statement: 'wrong', created_at: 'y' }] } };
+  r = await call('GET', '/me/payouts');
+  assert.equal(r.status, 200); assert.equal(r.body.payable, false); assert.equal(r.body.holds[0].notice, gates.NOTICES.sanctions_unscreened);
+  assert.equal(r.body.holds[0].events[0].kind, 'appealed'); assert.match(r.body.holds[0].appeal, /payout-freezes\/5\/appeal/); ok('the person reads each hold, its notice, what happened since and where to appeal');
+} finally {
+  server.close();
+}
+
+// ── 4. pay-time checks hold the line too ─────────────────────────────────
+{
+  const at = (h) => new Date(Date.UTC(2026, 9, 10) + h * 3600_000).toISOString();
+  const TERMS = { caps: { per_payout_cents: 5000, per_run_cents: 9000 }, currency: 'USD', formula: { kind: 'task_pay_terms' }, schedule: 'weekly', pause_hours: 1 };
+  const P = [{ recipient_id: '8', amount_cents: 100 }, { recipient_id: '9', amount_cents: 200 }, { recipient_id: '10', amount_cents: 300 }];
+  const events = [
+    { id: '1', kind: 'rule_signed', terms: TERMS, actor_id: '7', created_at: at(0) },
+    { id: '2', kind: 'run_noticed', rule_id: '1', run_key: 'w1', amount_cents: 600, currency: 'USD', terms: { payouts: P }, created_at: at(0) },
+  ];
+  const pool = { query: async (sql) => (/FROM payout_approvals WHERE id = \$1 OR rule_id/.test(sql) ? { rows: events } : { rows: [] }) };
+  const g = {
+    gateOwedPay: async (rid) => (rid === '9' ? { ok: false, reason: 'age_no_money', freeze_id: '31' } : rid === '10' ? { ok: true, pay_to: { guardian_account: 'acct_g' }, needs_guardian_cosign: true } : { ok: true, pay_to: 'self' }),
+  };
+  g.gateOwedPayMany = async (m) => new Map(await Promise.all([...m.keys()].map(async (k) => [k, await g.gateOwedPay(k)])));
+  g.cosignedInRun = async () => new Set();
+  const v = await approvals.checkRun({ ruleId: '1', runKey: 'w1', payouts: P, now: new Date(at(5)) }, { pool, gates: g });
+  assert.equal(v.ok, true);
+  assert.deepEqual(v.payouts.map((p) => p.recipient_id), ['8']); assert.equal(v.payouts[0].pay_to, 'self');
+  assert.deepEqual(v.held.map((h) => [h.recipient_id, h.reason]), [['9', 'age_no_money'], ['10', 'guardian_cosign_missing']]);
+  ok('at pay time a run pays only the lines that pass; the rest are held with their reason, never dropped silently');
+  const v2 = await approvals.checkRun({ ruleId: '1', runKey: 'w1', payouts: P, now: new Date(at(5)) }, { pool, gates: { ...g, cosignedInRun: async ({ builderIds }) => new Set(builderIds) } });
+  assert.deepEqual(v2.payouts.find((p) => p.recipient_id === '10').pay_to, { guardian_account: 'acct_g' }); ok('a co-signed 16-17 line is paid into the guardian\'s account');
+
+  const row = { id: 5, kind: 'payout_approved', recipient_id: 8, amount_cents: '100', currency: 'USD', terms: {}, actor_id: 7, created_at: 'x' };
+  const apool = { query: async () => ({ rows: [row] }) };
+  let c = await approvals.checkApproval({ id: 5, recipientId: 8, amountCents: 100, currency: 'USD' }, { pool: apool, gates: { gateOwedPay: async () => ({ ok: false, reason: 'sanctions_match', freeze_id: '40' }) } });
+  assert.equal(c.reason, 'recipient_gated'); assert.equal(c.gate.freeze_id, '40'); ok('an approved payout to someone since gated does not pay, and names the hold');
+  c = await approvals.checkApproval({ id: 5, recipientId: 8, amountCents: 100, currency: 'USD' }, { pool: apool, gates: { gateOwedPay: async () => ({ ok: true, pay_to: { guardian_account: 'g' }, needs_guardian_cosign: true }), hasCosign: async () => false } });
+  assert.equal(c.reason, 'guardian_cosign_missing'); ok('a 16-17 payout without the guardian\'s co-signature does not pay');
+}
+
+// ── 5. the person is told: the needs list ────────────────────────────────
+{
+  assert.equal(needs.computeNeeds({}).items.some((i) => i.id === 'payout_holds'), false); ok('no holds: no need');
+  const r = needs.computeNeeds({ openPayoutHolds: { count: 2, first_id: '5' }, ownKeySet: false, rank: 'archon', artPipeline: true });
+  const h = r.items.find((i) => i.id === 'payout_holds');
+  assert.equal(h.state, 'action_needed'); assert.equal(h.count, 2); assert.match(h.message, /appeal/);
+  assert.equal(r.items[0].id, 'payout_holds'); ok('open holds raise a need that names the appeal, ahead of the person\'s own setup chores');
+  const me = readFileSync(new URL('../src/bongos/routes/me.js', import.meta.url), 'utf8');
+  assert.match(me, /openPayoutHolds: await openPayoutHoldsP/); assert.match(me, /openHoldsFor\(req\.builder\.id\)/); ok('GET /me feeds the open holds into the needs list');
+}
+
+// ── 6. the migration says what the code relies on ────────────────────────
+{
+  const sql = readFileSync(new URL('../migrations/core_284_payout_gates.sql', import.meta.url), 'utf8');
+  assert.match(sql, /notice_text\s+text\s+NOT NULL/); assert.match(sql, /appeal_route\s+text\s+NOT NULL/); ok('a hold cannot be stored without its notice and appeal route');
+  for (const t of ['payout_age_records', 'payout_guardians', 'payout_screenings', 'payout_freezes', 'payout_freeze_events', 'payout_guardian_cosigns']) assert.ok(sql.includes(`'${t}'`), t);
+  assert.match(sql, /BEFORE UPDATE OR DELETE ON %I/); assert.match(sql, /BEFORE TRUNCATE ON %I/); ok('every gate table is append-only by trigger');
+  assert.match(sql, /only the person whose pay is frozen may appeal it/); assert.match(sql, /may not decide the appeal on their own freeze/); assert.match(sql, /only the builder''s current guardian may co-sign/); ok('the database repeats who may appeal, decide and co-sign');
+  for (const t of gates.AGE_TIERS) assert.ok(sql.includes(`'${t}'`), t);
+  for (const r of gates.FREEZE_REASONS) assert.ok(sql.includes(`'${r}'`), r);
+  ok('every tier and hold reason the code writes is one the table accepts');
+}
+
+
+// ── 7. hardening from review: one hold per race, no stray database text ───
+{
+  const log = [];
+  const client = {
+    query: async (sql) => {
+      log.push(sql.trim().split(/\s+/).slice(0, 2).join(' '));
+      if (/INSERT INTO payout_freezes/.test(sql)) return { rows: [{ id: 12 }] };
+      return { rows: [] };
+    },
+    release: () => log.push('release'),
+  };
+  const pool = { connect: async () => client, query: async () => { throw new Error('a pool must not be queried outside the lock'); } };
+  const h = await gates.holdOwedPay('8', 'age_unknown', { pool });
+  assert.equal(h.freeze_id, '12');
+  assert.deepEqual(log, ['BEGIN', 'SELECT pg_advisory_xact_lock($1::int,', 'INSERT INTO', 'COMMIT', 'release']);
+  ok('filing a hold takes a per-builder lock in one transaction, so a race cannot file two');
+  const bare = { query: async (sql) => (/INSERT/.test(sql) ? { rows: [{ id: 13 }] } : { rows: [] }), release: () => {}, connect: () => { throw new Error('a checked-out client is not reconnected'); } };
+  assert.equal((await gates.holdOwedPay('8', 'age_unknown', { pool: bare })).freeze_id, '13'); ok('a checked-out client runs the statements as they are');
+
+  const fail = (message) => ({ ...gates, readFreeze: async () => ({ id: '5', builder_id: '8', lifted: false }), addFreezeEvent: async () => { const e = new Error(message); e.code = '23514'; throw e; } });
+  const mk = (g) => { const a = express(); a.use(express.json()); a.use((req, res, next) => { res.fail = (code, o = {}) => res.status(o.status || 400).json({ error: code, message: o.message }); req.builder = { id: '8' }; req.gdsSession = { source: 'web', session_id: '1' }; next(); }); a.use('/', buildMine({ gates: g, requireBuilder: (q, r, nx) => nx() })); return http.createServer(a).listen(0); };
+  const post = (srv, path, body) => new Promise((resolve) => { const r = http.request({ port: srv.address().port, path, method: 'POST', headers: { 'content-type': 'application/json' } }, (res) => { let s = ''; res.on('data', (c) => (s += c)); res.on('end', () => resolve(JSON.parse(s))); }); r.write(JSON.stringify(body)); r.end(); });
+  let srv = mk(fail('only the person whose pay is frozen may appeal it'));
+  assert.equal((await post(srv, '/me/payout-freezes/5/appeal', { statement: 'x' })).message, 'only the person whose pay is frozen may appeal it'); srv.close();
+  ok('a refusal in our own words is passed on');
+  srv = mk(fail('relation "secret_table" violates something internal'));
+  const m = (await post(srv, '/me/payout-freezes/5/appeal', { statement: 'x' })).message; srv.close();
+  assert.equal(m, 'The payout rules refused this.'); ok('any other database text stays out of the response');
+}
+
+// ── 8. from the second review: real refusal words, and one read per run ──
+{
+  const sql = readFileSync(new URL('../migrations/core_284_payout_gates.sql', import.meta.url), 'utf8');
+  const raised = [...sql.matchAll(/RAISE EXCEPTION '((?:[^']|'')+)'/g)].map((x) => x[1].replace(/''/g, "'"));
+  assert.ok(raised.length >= 5, 'the migration raises its refusals');
+  // fill each % the way Postgres would: the table name, the operation, a freeze id
+  const filled = (t) => t.replace(/^% is append-only: %/, 'payout_freezes is append-only: UPDATE').replace('%', '41');
+  for (const t of raised) assert.ok(buildGates.OUR_REFUSALS.some((re) => re.test(filled(t))), 'not passed on: ' + t);
+  ok('every refusal the gate triggers raise, filled in as Postgres would, is one the route passes on in its own words');
+  assert.ok(buildGates.OUR_REFUSALS.some((re) => re.test('payout_guardian_cosigns is append-only: DELETE refused (a correction is a new row)')));
+  assert.ok(!buildGates.OUR_REFUSALS.some((re) => re.test('payout freeze d is already lifted')));
+  ok('the numbered and table-named refusals match real values, not a stray letter');
+
+  const queries = [];
+  const pool = { query: async (q, params) => {
+    queries.push(q);
+    const rows = (t) => params[0].map((b, i) => ({ id: String(i + 1), builder_id: b, ...t }));
+    if (/FROM payout_age_records/.test(q)) return { rows: rows({ tier: 'adult' }) };
+    if (/FROM payout_screenings/.test(q)) return { rows: rows({ result: 'clear', screened_by: 'person:o', valid_until: LATER }) };
+    return { rows: [] };
+  } };
+  const owed = new Map(Array.from({ length: 40 }, (_, i) => [String(100 + i), 10]));
+  const out = await gates.gateOwedPayMany(owed, { now: NOW, pool });
+  assert.equal(out.size, 40); assert.ok([...out.values()].every((v) => v.ok));
+  assert.equal(queries.length, 4); ok('forty recipients are checked with four reads, not four per person');
+  assert.equal((await gates.readFacts('7', { pool })).ageRecords.length, 1); ok('a single recipient reads through the same batched path');
+}
+
+console.log(`\n${n} passed`);

package/tests/payout_gates_db.mjs

@@ -0,0 +1,113 @@
+// tests/payout_gates_db.mjs — task 1004914 (ADR 0385 D8). Real DB.
+// The payout gate tables built from the real migrations (core_283 then core_284)
+// in a throwaway schema, proving the DATABASE refuses: any edit or delete of a
+// gate record; a hold with no notice; an appeal by anyone but the frozen person;
+// a decision by the frozen person; a co-signature by anyone but the current
+// guardian; anything after a lift. Then the gate end to end over real rows.
+// Self-skips without a reachable Postgres.
+// Run:  DATABASE_URL=... node tests/payout_gates_db.mjs
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { strict as assert } from 'node:assert';
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+const here = dirname(fileURLToPath(import.meta.url));
+
+const pgPool = new Pool({ connectionString: process.env.DATABASE_URL || undefined, max: 1 });
+let client;
+try { client = await pgPool.connect(); } catch (e) {
+  console.log(`payout_gates_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pgPool.end().catch(() => {});
+  process.exit(0);
+}
+const SCHEMA = `t1004914_${process.pid}`;
+let pass = 0;
+const ok = (c, m) => { assert.ok(c, m); pass++; console.log(`  ok - ${m}`); };
+const refused = async (sql, params, m) => {
+  await client.query('SAVEPOINT s');
+  let threw = false;
+  try { await client.query(sql, params); } catch { threw = true; }
+  await client.query('ROLLBACK TO SAVEPOINT s');
+  ok(threw, m);
+};
+
+try {
+  await client.query(`CREATE SCHEMA ${SCHEMA}`);
+  await client.query(`SET search_path TO ${SCHEMA}`);
+  await client.query('CREATE TABLE builders (id bigserial PRIMARY KEY, system_role text)');
+  for (const m of ['core_283_payout_approvals.sql', 'core_284_payout_gates.sql']) {
+    await client.query(readFileSync(join(here, '..', 'migrations', m), 'utf8'));
+  }
+  // 1 owner, 2 a 16-17 builder, 3 their guardian, 4 an adult, 5 someone else
+  await client.query('INSERT INTO builders (system_role) VALUES (NULL), (NULL), (NULL), (NULL), (NULL)');
+  await client.query('BEGIN');
+
+  const g = require('../src/bongos/payout-gates.js');
+  const o = { pool: client };
+
+  const age = await g.recordAge({ builderId: 4, tier: 'adult', basis: 'verified_by_person', recordedBy: 1 }, o);
+  await refused('UPDATE payout_age_records SET tier = $1 WHERE id = $2', ['under_13', age.id], 'an age record cannot be edited');
+  await refused('DELETE FROM payout_age_records WHERE id = $1', [age.id], 'an age record cannot be deleted');
+  await refused('TRUNCATE payout_screenings', [], 'screenings cannot be truncated');
+  await refused("INSERT INTO payout_age_records (builder_id, tier, basis) VALUES (4, 'old', 'self_declared')", [], 'an unknown age tier is refused');
+  await refused("INSERT INTO payout_screenings (builder_id, result, screened_by) VALUES (4, 'clear', 'person:o')", [], 'a clear screening with no expiry is refused');
+
+  let v = await g.gateOwedPay(4, { owedCents: 1000, pool: client });
+  ok(v.ok === false && v.reason === 'sanctions_unscreened' && v.freeze_id, 'an unscreened adult owed money is held, with a hold filed');
+  const hold = await g.readFreeze(v.freeze_id, o);
+  ok(hold.notice_text === g.NOTICES.sanctions_unscreened && hold.appeal_route && hold.owed_cents === 1000, 'the hold carries its notice, appeal route and what is owed');
+  ok((await g.gateOwedPay(4, { owedCents: 1000, pool: client })).freeze_id === v.freeze_id, 'a second refusal reuses the open hold');
+  ok((await g.openHoldsFor(4, o)).count === 1, 'the needs list sees one open hold');
+  await refused("INSERT INTO payout_freezes (builder_id, reason, notice_text, appeal_route) VALUES (4, 'manual', NULL, 'x')", [], 'a hold with no notice is refused: no silent freeze');
+  await refused("INSERT INTO payout_freezes (builder_id, reason, notice_text, appeal_route) VALUES (4, 'manual', 'short', 'x')", [], 'a hold with a token notice is refused');
+
+  await refused("INSERT INTO payout_freeze_events (freeze_id, kind, actor_id, statement) VALUES ($1, 'appealed', 5, 'x')", [v.freeze_id], 'only the frozen person may appeal');
+  await g.addFreezeEvent({ freezeId: v.freeze_id, kind: 'appealed', actorId: 4, statement: 'I was screened last week.' }, o);
+  ok(true, 'the frozen person appeals');
+  await refused("INSERT INTO payout_freeze_events (freeze_id, kind, actor_id, statement) VALUES ($1, 'lifted', 4, 'x')", [v.freeze_id], 'the frozen person cannot lift their own hold');
+
+  await g.recordScreening({ builderId: 4, result: 'clear', screenedBy: 'person:owner', validUntil: new Date(Date.now() + 86_400_000).toISOString(), recordedBy: 1 }, o);
+  ok((await g.gateOwedPay(4, { pool: client })).reason === 'frozen', 'a clear screening does not lift a hold by itself: a person does');
+  await g.addFreezeEvent({ freezeId: v.freeze_id, kind: 'lifted', actorId: 1, statement: 'Screening came back clear.' }, o);
+  await refused("INSERT INTO payout_freeze_events (freeze_id, kind, actor_id, statement) VALUES ($1, 'upheld', 1, 'x')", [v.freeze_id], 'nothing follows a lift');
+  v = await g.gateOwedPay(4, { pool: client });
+  ok(v.ok === true && v.pay_to === 'self', 'lifted and screened clear: the adult is paid to themselves');
+  ok((await g.openHoldsFor(4, o)).count === 0, 'the need goes away when the hold is lifted');
+
+  await g.recordAge({ builderId: 2, tier: '16_17', basis: 'verified_by_person', recordedBy: 1 }, o);
+  await g.recordScreening({ builderId: 2, result: 'clear', screenedBy: 'person:owner', validUntil: new Date(Date.now() + 86_400_000).toISOString(), recordedBy: 1 }, o);
+  ok((await g.gateRecipient(2, o)).reason === 'age_needs_guardian', '16-17 with no guardian is not payable');
+  await refused("INSERT INTO payout_guardians (builder_id, guardian_id, active, recorded_by) VALUES (2, 3, true, 1)", [], 'an active guardian link must name the guardian-controlled account');
+  await refused("INSERT INTO payout_guardians (builder_id, guardian_id, guardian_account, active, recorded_by) VALUES (2, 2, 'acct', true, 1)", [], 'nobody is their own guardian');
+  await g.recordGuardian({ builderId: 2, guardianId: 3, guardianAccount: 'acct_guardian', active: true, recordedBy: 1 }, o);
+  v = await g.gateRecipient(2, o);
+  ok(v.ok && v.needs_guardian_cosign && v.pay_to.guardian_account === 'acct_guardian', '16-17 with a guardian is paid only into the guardian\'s account, co-signed');
+
+  const approval = (await client.query("INSERT INTO payout_approvals (kind, actor_id, session_id, session_source, recipient_id, amount_cents, currency) VALUES ('payout_approved', 1, 11, 'web', 2, 500, 'USD') RETURNING id")).rows[0].id;
+  await refused("INSERT INTO payout_guardian_cosigns (builder_id, guardian_id, approval_id, session_id, session_source) VALUES (2, 5, $1, 12, 'web')", [approval], 'only the current guardian may co-sign');
+  await refused("INSERT INTO payout_guardian_cosigns (builder_id, guardian_id, approval_id, session_id, session_source) VALUES (2, 3, $1, 12, 'cli')", [approval], 'a co-signature from a CLI session is refused');
+  const a = require('../src/bongos/payout-approvals.js');
+  ok((await a.checkApproval({ id: approval, recipientId: 2, amountCents: 500, currency: 'USD' }, o)).reason === 'guardian_cosign_missing', 'the approved payout does not pay before the guardian co-signs');
+  ok((await g.cosignAsGuardian({ guardianId: 5, sessionId: 12, approvalId: approval }, o)).length === 0, 'someone who is not the guardian co-signs nothing');
+  const signed = await g.cosignAsGuardian({ guardianId: 3, sessionId: 12, approvalId: approval }, o);
+  ok(signed.length === 1 && signed[0].builder_id === '2', 'the guardian co-signs, and whose payout it is comes from the payout');
+  const c = await a.checkApproval({ id: approval, recipientId: 2, amountCents: 500, currency: 'USD' }, o);
+  ok(c.ok && c.pay_to.guardian_account === 'acct_guardian', 'after the co-signature it pays, into the guardian\'s account');
+  await refused("INSERT INTO payout_guardian_cosigns (builder_id, guardian_id, approval_id, session_id, session_source) VALUES (2, 3, $1, 13, 'web')", [approval], 'a payout is co-signed once');
+
+  await g.recordGuardian({ builderId: 2, guardianId: 3, guardianAccount: null, active: false, recordedBy: 1 }, o);
+  ok((await g.gateRecipient(2, o)).reason === 'age_needs_guardian', 'ending the guardian link stops pay again');
+
+  await g.recordAge({ builderId: 4, tier: '13_15', basis: 'verified_by_person', recordedBy: 1 }, o);
+  v = await g.gateOwedPay(4, { owedCents: 200, pool: client });
+  ok(v.reason === 'age_no_money' && v.freeze_id, '13-15 owed money is held and told why');
+  await client.query('ROLLBACK');
+} finally {
+  await client.query('ROLLBACK').catch(() => {});
+  await client.query(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`).catch(() => {});
+  client.release();
+  await pgPool.end();
+}
+console.log(`payout_gates_db.mjs: ${pass} passed`);

package/tests/planning_session_skill.mjs

@@ -40,7 +40,15 @@ test('the self-check is described as failing loudly on any mismatch, zero includ
 });
 
 test('the reference implementation is named', () => {
-  assert.ok(NORM.includes('seed-bongos-v1-idea-routing-tasks.js'), 'names the reference seed script');
+  assert.ok(NORM.includes('scripts/bongos/seed-tasks.js'), 'names the one seeder (task 1004979)');
+  assert.ok(NORM.includes('scripts/bongos/seed-tasks.example.json'), 'names the example spec to start from');
+  assert.ok(NORM.includes('--dry-run'), 'tells the session to dry-run first');
+});
+
+test('the per-version seed scripts are no longer the template', () => {
+  for (const old of ['seed-bongos-v1-idea-routing-tasks.js', 'seed-bv1-profiles-tasks.js', 'seed-bv2-ideator-surface-tasks.js', 'seed-<ver_slug>-tasks.js']) {
+    assert.ok(!NORM.includes(old), `the skill no longer points at ${old}`);
+  }
 });
 
 test('the retro incident (RETRO2 / learning 1000188) is cited as the reason', () => {
@@ -48,8 +56,10 @@ test('the retro incident (RETRO2 / learning 1000188) is cited as the reason', ()
   assert.ok(NORM.includes('goal 1000071'));
 });
 
-test('step 5 (run the seed script) points at the self-check rather than treating exit 0 as sufficient on its own', () => {
-  const step5 = NORM.slice(NORM.indexOf('Run the seed script.'));
+test('step 5 (run the seed) points at the self-check rather than treating exit 0 as sufficient on its own', () => {
+  const at = NORM.indexOf('Run the seed:');
+  assert.ok(at >= 0, 'step 5 exists');
+  const step5 = NORM.slice(at);
   assert.ok(step5.slice(0, 400).includes('verifySeedCriteriaLinks'), 'step 5 references the self-check by name');
 });
 

package/tests/project_settings_page.mjs

@@ -6,9 +6,10 @@
 // 1. The route works: one read returns all five rows, the timer round-trips through
 //    the shared parser, and the category set can be renamed, reordered and retired.
 //
-// 2. AN ABSENT FUNDAMENTAL IS REPORTED ABSENT. `upmarket_percent` has no knob behind
-//    it anywhere in this codebase, and equity is a settled owner decision that it is
-//    NOT real. Both must render as themselves. A plausible zero on either would be a
+// 2. AN ABSENT FUNDAMENTAL IS REPORTED ABSENT. `upmarket_percent` (the credit-weighted
+//    pool) has no knob behind it and is gated shut by ADR 0385, and credits are a
+//    settled owner decision that they are NOT equity (ADR 0387; task 1004967). Both
+//    must render as themselves. A plausible zero on either would be a
 //    fabricated claim about the project's economics on the page its owner trusts most
 //    — a worse failure than the illegibility this goal exists to fix.
 //
@@ -130,14 +131,28 @@ test('an absent fundamental is reported absent, never as a plausible zero', asyn
     await handlerFor('get', '/project-settings')({ query: {} }, res);
     const by = Object.fromEntries(res.payload.rows.map((r) => [r.key, r]));
 
-    assert.equal(by.upmarket_percent.state, 'absent');
+    // The credit-weighted pool (task 1004967, ADR 0385 pay-type gates): renamed from
+    // "share of upmarket revenue", reported gated, never a number.
+    assert.equal(by.upmarket_percent.title, 'Credit-weighted pool');
+    assert.equal(by.upmarket_percent.state, 'gated');
     assert.equal(by.upmarket_percent.value, undefined, 'an unconfigured knob must carry NO value');
-    assert.match(by.upmarket_percent.sentence, /no such setting yet/i);
+    assert.match(by.upmarket_percent.sentence, /^not available \(gated\)/i);
     assert.doesNotMatch(by.upmarket_percent.sentence, /\b0\s*%/, 'never render the absent knob as 0%');
+    assert.doesNotMatch(by.upmarket_percent.title, /upmarket/i);
 
+    // Credits are a contribution meter, not ownership; equity is the project's own
+    // separate grant (ADR 0385 decisions 2-3, ADR 0387). The old row said a credit
+    // IS a unit of ownership — that must never come back.
     assert.equal(by.equity_calculation.state, 'not-yet-real');
+    assert.match(by.equity_calculation.sentence, /contribution meter, not ownership/i);
+    assert.match(by.equity_calculation.sentence, /granted by the project separately/i);
     assert.match(by.equity_calculation.sentence, /no legal equity is issued/i);
     assert.match(by.equity_calculation.sentence, /no cap table/i);
+    assert.doesNotMatch(by.equity_calculation.sentence, /ownership stream|unit of ownership/i);
+    // The ADR link points at the file that exists (the old path 404'd).
+    assert.equal(by.equity_calculation.reads.file, 'docs/adr/0054-session-token-reward-cost-plus.md');
+    assert.ok(fs.existsSync(path.join(ROOT, by.equity_calculation.reads.file)), 'the equity row links a real ADR');
+    assert.ok(fs.existsSync(path.join(ROOT, by.upmarket_percent.reads.file)), 'the pool row links a real ADR');
   } finally { restore(); }
 });
 
@@ -151,9 +166,18 @@ test('the credit row reports the formula in force, and says the estimate is not
     assert.match(credit.sentence, /× 1\.20/, 'the multiplier comes from the resolved policy');
     // cost-plus-only: the per-task estimate is advertised and never paid (ADR 0146).
     assert.match(credit.sentence, /advertised guide only/i);
+    // ADR 0387 wording (task 1004967): USD sizes the credit, it is not its worth.
+    assert.match(credit.sentence, /sized by the session’s cost in USD/);
+    assert.match(credit.sentence, /not money/i);
+    assert.doesNotMatch(credit.sentence, /\bpays\b|worth \$|= \$1/i);
   } finally { restore(); }
 });
 
+test('the client draws the gated pool as "not available (gated)", not as unconfigured', () => {
+  const page = read('modules', 'hall-ui', 'public', 'project-settings.js');
+  assert.match(page, /gated:\s*\['ps-pill--absent',\s*'not available \(gated\)'\]/);
+});
+
 test('the credit row degrades named when the economy module is absent', async () => {
   const { handlerFor, restore } = buildRouterWithStubs({ timer: TIMER_OK, categories: CATS, reward: null });
   try {