@bongos/core 1.23.22 → 1.24.2

package/src/bongos/middleware/rate-limit.js

@@ -118,6 +118,12 @@ const DEFAULT_READ_LIMIT     = 600;
 // address-rotating caller must not be able to grow the map without bound between sweeps
 // (same bound as modules/platform-identity/read-rate-limit.js).
 const DEFAULT_READ_MAX_TRACKED_IPS = 10000;
+// Hard size cap on EVERY bucket map below (task 1004964). The sweep bounds them by
+// time only, once per SWEEP_MS; a flood from many source addresses would otherwise
+// grow a map for up to five minutes before it runs. At the cap the oldest-inserted
+// key is evicted first (a Map iterates in insertion order), so the newest callers
+// keep their buckets. A limiter may set a tighter cap (DEFAULT_READ_MAX_TRACKED_IPS).
+const MAX_TRACKED_KEYS = 50000;
 const OPT_OUT_REASON_MIN_LENGTH = 20;
 const SWEEP_MS              = 5 * 60 * 1000;
 
@@ -138,6 +144,15 @@ const WRITE_METHODS = new Set(['POST', 'PATCH', 'PUT', 'DELETE']);
 // limiter — the public router answers CORS preflights and returns 204 first.
 const READ_METHODS  = new Set(['GET', 'HEAD']);
 
+// newBucket(map, key, cap) — start an empty bucket for a key not yet tracked,
+// evicting the oldest-inserted key first while the map is at its cap.
+function newBucket(map, key, cap = MAX_TRACKED_KEYS) {
+  while (map.size >= cap) map.delete(map.keys().next().value);
+  const bucket = [];
+  map.set(key, bucket);
+  return bucket;
+}
+
 function pruneAndCount(bucket, now, windowMs) {
   const cutoff = now - windowMs;
   // arr is the in-place timestamps array; trim in place.
@@ -219,7 +234,7 @@ function rateLimitMiddleware(req, res, next) {
   // --- per-IP ---
   const ip = req.ip || req.socket?.remoteAddress || 'unknown';
   let ipBucket = ipBuckets.get(ip);
-  if (!ipBucket) { ipBucket = []; ipBuckets.set(ip, ipBucket); }
+  if (!ipBucket) ipBucket = newBucket(ipBuckets, ip);
   const ipCount = pruneAndCount(ipBucket, now, PER_IP_WINDOW_MS);
   if (ipCount >= PER_IP_LIMIT) {
     const oldest = ipBucket[0];
@@ -235,7 +250,7 @@ function rateLimitMiddleware(req, res, next) {
   const sessionKey = extractSessionKey(req);
   if (sessionKey) {
     let sBucket = sessionBuckets.get(sessionKey);
-    if (!sBucket) { sBucket = []; sessionBuckets.set(sessionKey, sBucket); }
+    if (!sBucket) sBucket = newBucket(sessionBuckets, sessionKey);
     const sCount = pruneAndCount(sBucket, now, PER_SESSION_WINDOW_MS);
     if (sCount >= PER_SESSION_LIMIT) {
       const oldest = sBucket[0];
@@ -266,7 +281,7 @@ function publicReadRateLimitMiddleware(req, res, next) {
   const now = Date.now();
   const ip = req.ip || req.socket?.remoteAddress || 'unknown';
   let bucket = publicReadBuckets.get(ip);
-  if (!bucket) { bucket = []; publicReadBuckets.set(ip, bucket); }
+  if (!bucket) bucket = newBucket(publicReadBuckets, ip);
   const count = pruneAndCount(bucket, now, PUBLIC_READ_WINDOW_MS);
   if (count >= PUBLIC_READ_LIMIT) {
     const oldest = bucket[0];
@@ -287,18 +302,14 @@ function publicReadRateLimitMiddleware(req, res, next) {
 // names that budget in the 429 body + headers so a caller can tell which ceiling
 // it hit. Keyed on req.ip — the same real-client-IP resolution the write limiter
 // uses (Caddy forwards the client IP, server sets 'trust proxy').
-function perIpSlidingWindow(buckets, { limit, windowMs, scope, maxTracked = Infinity }) {
+function perIpSlidingWindow(buckets, { limit, windowMs, scope, maxTracked = MAX_TRACKED_KEYS }) {
   return markMetered(function slidingWindowRateLimit(req, res, next) {
     const now = Date.now();
     const ip = req.ip || req.socket?.remoteAddress || 'unknown';
     let bucket = buckets.get(ip);
-    if (!bucket) {
-      // Bound the map: a caller rotating source addresses (an IPv6 /64) mints a fresh
-      // bucket per request. Evict the longest-tracked entry (Map iterates oldest first).
-      if (buckets.size >= maxTracked) buckets.delete(buckets.keys().next().value);
-      bucket = [];
-      buckets.set(ip, bucket);
-    }
+    // Bound the map: a caller rotating source addresses (an IPv6 /64) mints a fresh
+    // bucket per request. Evict the longest-tracked entry (Map iterates oldest first).
+    if (!bucket) bucket = newBucket(buckets, ip, maxTracked);
     if (pruneAndCount(bucket, now, windowMs) >= limit) {
       const retryAfter = Math.max(1, Math.ceil((bucket[0] + windowMs - now) / 1000));
       res.set('Retry-After', String(retryAfter));
@@ -451,6 +462,7 @@ module.exports = {
   selfMeteredRoutes,
   DEFAULT_READ_LIMIT,
   DEFAULT_READ_MAX_TRACKED_IPS,
+  MAX_TRACKED_KEYS,
   // exported for tests
   PER_IP_WINDOW_MS,
   PER_IP_LIMIT,
@@ -463,3 +475,10 @@ module.exports = {
   PROJECT_FEED_WINDOW_MS,
   PROJECT_FEED_LIMIT,
 };
+
+// Test seam (task 1004964): the bucket maps, so a test can show each stays capped.
+// Assigned after the export list, not inside it: an object literal there stops
+// cjs-module-lexer, and ESM tests lose every named export after it.
+module.exports._bucketMaps = {
+  ipBuckets, sessionBuckets, publicReadBuckets, accountExistenceBuckets, projectFeedBuckets, defaultReadBuckets,
+};

package/src/bongos/module-scope-map.js

@@ -50,7 +50,7 @@ const MODULE_GLOBS = {
     'src/bongos/permission-path-check.js', 'src/bongos/sensitive-surfaces.js',
     // task 1004024: the auth.js carve (db-kernel.js, above, is db.js's), now protected.
     'src/bongos/auth-admission.js', 'src/bongos/auth-config.js', 'src/bongos/auth-discord.js',
-    'src/bongos/auth-github.js', 'src/bongos/auth-idp.js',
+    'src/bongos/auth-github.js', 'src/bongos/auth-google.js', 'src/bongos/auth-idp.js',
     'src/bongos/middleware/', 'src/bongos/live-channel.js', 'src/bongos/secret-box.js',
     'src/bongos/repo-info.js', 'src/bongos/api-path-404.js', 'src/bongos/serve-internal.js',
     'src/bongos/module-scope-map.js', 'src/bongos/hierarchy-config.js',
@@ -190,6 +190,15 @@ const MODULE_GLOBS = {
   raise: [
     'modules/raise/',
   ],
+  // Market Watch (task 1004935, goal 1000137): a weekly AI watch on a project's
+  // market. default:false; its data layer landed in task 1004936 (no routes yet). Its tests
+  // are listed by EXACT path: this file's format has no wildcards (header above), so a
+  // 'tests/market_watch_*' entry would match nothing. Add each new market_watch test here by name.
+  'market-watch': [
+    'modules/market-watch/', 'tests/market_watch_module.mjs',
+    'tests/market_watch_data.mjs', 'tests/market_watch_data_db.mjs',
+    'tests/market_watch_run.mjs',
+  ],
   // --- builder prefs (wandering/skill/sound/render) + builder-needs ---
   // Carved into modules/builder-settings/ (BV1.R80 / ADR 0093 §1): the five pref
   // libs + builder-needs + their db slice + the `/me/*-prefs` routes + the
@@ -529,6 +538,8 @@ const MODULE_GLOBS = {
   //     enforcement, not methodology prose. ---
   methodology: [
     'CLAUDE.md',
+    // the same instruction core for every other AI model (task 1004922)
+    'AGENTS.md', 'GEMINI.md',
     'docs/',
     '.claude/skills/', '.claude/rules/',
     'scripts/bongos/start.js', 'scripts/bongos/discipline-modes.json',

package/src/bongos/optimizer.js

@@ -29,6 +29,7 @@
 // per-task est_minutes <= timeBudgetMin guard already enforces that.
 
 const { pool } = require('./pool');
+const { resolveCapabilities, feedNeedsClause } = require('./task-needs');
 // touches[] cleanup [5/8] (task 880): the same prefix-aware overlap matcher the
 // claim guard uses, so the planner's "parallel-safe set" agrees with what
 // claimTask / claimTasksBatch will actually allow.
@@ -77,6 +78,12 @@ const UNSHIPPED_DEPS_GUARD = `
                    OR (d.to_kind = 'goal'      AND EXISTS (SELECT 1 FROM goals              x WHERE x.id = d.to_id AND x.status <> 'achieved')))
             )`;
 
+// An artist's page claim is a MARKER, never a file-overlap block (task 1004947).
+// Hand copy of notPageMarkerSql('c', 't2') in modules/lifecycle/page-tweak-artist.js
+// (core cannot require a module, ADR 0083); tests/page_tweak_marker_sql.mjs pins
+// the two together, as claimable_blocker_status.mjs does for the guards above.
+const PAGE_MARKER_GUARD = `NOT (COALESCE(t2.source, '') = 'page-tweak' AND c.worktree_name IS NULL AND c.creator_session_id IS NULL)`;
+
 const VALID_MODES = ['active', 'check-in', 'autonomous'];
 const DEFAULT_MAX_PARALLEL = 3;
 
@@ -108,6 +115,11 @@ async function optimizeSession({ builderId, mode, timeBudgetMin, maxParallel })
   // whose blocker had been resolved stayed invisible here. A comment asking the
   // next editor to remember is not enforcement: tests/claimable_blocker_status.mjs
   // now asserts this file, db-tasks.js and the migration carry the same predicate.
+  // task 1004950 / ADR 0395: recommend only what this builder can do — the same
+  // rule as listClaimableTasks. An autonomous plan runs unattended, so it never
+  // holds `owner` (an agent cannot make the owner's decision).
+  const caps = await resolveCapabilities(builderId);
+  const feedCaps = mode === 'autonomous' ? caps.filter((c) => c !== 'owner') : caps;
   const { rows } = await pool.query(
     `SELECT ct.*, sf.fits_session_modes, sf.credits_per_minute
        FROM (
@@ -120,6 +132,7 @@ ${OPEN_BLOCKER_GUARD}${UNSHIPPED_DEPS_GUARD}
               SELECT 1 FROM claims c
                 JOIN tasks t2 ON t2.id = c.task_id
                WHERE c.released_at IS NULL
+                 AND ${PAGE_MARKER_GUARD}
                  AND t2.touches && t.touches
             )
        ) ct
@@ -142,6 +155,7 @@ ${OPEN_BLOCKER_GUARD}${UNSHIPPED_DEPS_GUARD}
            FROM tasks t
        ) sf ON sf.id = ct.id
       WHERE $1 = ANY(sf.fits_session_modes)
+        AND ${feedNeedsClause('ct', '$3')}
         AND NOT EXISTS (
           SELECT 1 FROM claims c
            WHERE c.task_id = ct.id
@@ -152,7 +166,7 @@ ${OPEN_BLOCKER_GUARD}${UNSHIPPED_DEPS_GUARD}
                ct.priority ASC NULLS LAST,
                COALESCE(ct.est_minutes_calibrated, ct.est_minutes) ASC NULLS LAST,
                ct.id ASC`,
-    [mode, builderId]
+    [mode, builderId, feedCaps]
   );
 
   const chosen = [];

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,
+};