@bongos/core 1.24.23 → 1.24.24

package/modules/economy/ledger-check.js

@@ -0,0 +1,360 @@
+'use strict';
+
+// modules/economy/ledger-check.js — EVERY DAY, OUR RECORD AGAINST THE PROCESSOR'S, WITH AN
+// ALARM TO THE OWNER ON ANY DIFFERENCE (task 1004912, goal 1000092 N8; ADR 0397 decision 7).
+//
+// WHY. Bongos holds no money (ADR 0385, ADR 0397): the processor does, and what Bongos shows
+// is its own record of each movement and its cause. That record is only worth showing if it
+// is TRUE, and the way to prove that without holding the money is to set it beside the
+// processor's figures every day and say so loudly when they differ.
+//
+// THE PRODUCT GATE (legal framework, by Article only; a product constraint, not advice).
+//   actor     nobody moves anything. The server's own daily timer reads two records and
+//             writes one row saying whether they agree.
+//   custody   the processor, throughout. Nothing here holds, moves, nets or corrects money;
+//             a difference is raised to a person, never "fixed" by a booked figure.
+//   words     record, balance, difference, check. Never deposit, wallet, interest or yield.
+//   control   read only, once a day. The one write is this check's own row (and the alarm).
+//   advice    none is given.
+//   primitive the Stripe Connect balance read of the project's connected account, and the
+//             list of its balance transactions / transfers / payouts (ADR 0397 D3 table).
+//             Only the processor adapter names Stripe; here it is a port.
+//
+// WHAT IS COMPARED.
+//   1. The project's balance: the sum of our record (project-account.js) against the
+//      processor's own figure for the project's connected account. Any difference is drift.
+//   2. Every movement, by its processor reference, over the last WINDOW_DAYS: each one our
+//      records say happened (project-account movements, member payments, cash-outs) must be
+//      one the processor has, for the same amount; and each one the processor has must be one
+//      we recorded. This is what proves each USER's side: by ADR 0397 a member's balance is
+//      the processor's figure and is never summed from our rows, so what is checked for a
+//      member is that every payment to or from them that we show is one the processor made,
+//      for the amount we show.
+//
+// THE PROCESSOR PORT (all optional):
+//   balanceMicro()                       the project's account balance (the existing read)
+//   listMovements({ since, until })      → [{ ref, amountMicro, createdAt }] every movement
+//                                        the processor made for this project's connection in
+//                                        that window, by the same reference Bongos stored
+//   With no port, or neither method, the check is recorded `unchecked` (no_processor) and no
+//   alarm is raised: there is nothing yet to compare with. That is the state of every
+//   instance until a processor adapter lands (task 1005040).
+//
+// THE ALARM. A difference, or a processor that could not be read, opens a blocker for the
+// owner. The blocker queue is PUBLIC (the status dashboard shows it), so the blocker carries
+// no amounts and no references: it says a difference was found and where to read it. The
+// numbers are in this check's row, read through GET /project-account/ledger-checks behind
+// the payout authority (payout.approve), and shown on the owner's Project settings page.
+// The same set of differences is raised once, not every day; a changed set is raised again,
+// and a clean day clears it, so a difference that comes back is a fresh alarm.
+
+const crypto = require('node:crypto');
+
+const WINDOW_DAYS = 7;
+// A movement made in the last hour may not be in the processor's list yet, and the two
+// clocks are not the same clock, so the newest hour is left to tomorrow's check.
+const SETTLE_MS = 60 * 60_000;
+// The processor's list is asked for from a day before our window starts up to now, so a
+// movement whose two timestamps fall either side of an edge is still in their list and is not
+// reported missing. (Our window ends SETTLE_MS before now; theirs runs to now.)
+const EDGE_MS = 24 * 60 * 60_000;
+const READ_TIMEOUT_MS = 15_000;
+const MICRO_PER_CENT = 10_000;
+const FINDINGS_MAX = 200;
+const LOCK = [1004912, 1];
+
+const DAY_MS = 24 * 60 * 60_000;
+
+const KIND_WORDS = Object.freeze({
+  balance: 'The balance differs',
+  missing_at_processor: 'We recorded it, the processor has no such movement',
+  unknown_to_us: 'The processor made it, we have no record of it',
+  amount_differs: 'Both have it, for different amounts',
+  records_disagree: 'Two of our own records give this reference different amounts',
+});
+
+function withTimeout(p, ms) {
+  let timer;
+  return Promise.race([
+    p,
+    new Promise((_, rej) => { timer = setTimeout(() => rej(Object.assign(new Error('the processor did not answer in time'), { code: 'timeout' })), ms); }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+// Every movement our records say went through the processor, as { ref, amount_micro,
+// created_at, source }. One reference can appear twice (a member funding the project is both
+// a member payment and a project `funding` movement), so the caller folds by reference.
+const OUR_REFS_SQL = `
+  SELECT processor_ref AS ref, amount_micro, created_at, 'project_account:' || kind AS source
+    FROM economy_project_account_movements
+   WHERE processor_ref IS NOT NULL AND kind IN ('funding', 'payout', 'payout_return', 'fee') AND ($1::text[] IS NULL OR processor_ref = ANY($1))
+     AND ($2::timestamptz IS NULL OR created_at >= $2) AND ($3::timestamptz IS NULL OR created_at < $3)
+  UNION ALL
+  SELECT a.processor_ref, t.amount_cents * ${MICRO_PER_CENT}, a.created_at, 'member_payment'
+    FROM economy_user_transfer_attempts a JOIN economy_user_transfers t ON t.id = a.transfer_id
+   WHERE a.outcome = 'sent' AND ($1::text[] IS NULL OR a.processor_ref = ANY($1))
+     AND ($2::timestamptz IS NULL OR a.created_at >= $2) AND ($3::timestamptz IS NULL OR a.created_at < $3)
+  UNION ALL
+  SELECT a.processor_ref, c.amount_cents * ${MICRO_PER_CENT}, a.created_at, 'cash_out'
+    FROM cash_out_attempts a JOIN cash_outs c ON c.id = a.cash_out_id
+   WHERE a.outcome = 'sent' AND ($1::text[] IS NULL OR a.processor_ref = ANY($1))
+     AND ($2::timestamptz IS NULL OR a.created_at >= $2) AND ($3::timestamptz IS NULL OR a.created_at < $3)`;
+
+const RECORDED_BALANCE_SQL = `
+  SELECT COALESCE(SUM(CASE direction WHEN 'in' THEN amount_micro WHEN 'out' THEN -amount_micro ELSE 0 END), 0) AS micro
+    FROM economy_project_account_movements`;
+
+// The store: the SQL, kept apart so the comparison tests without a database.
+function createStore(db) {
+  return {
+    async recordedBalanceMicro() { return Number((await db.query(RECORDED_BALANCE_SQL)).rows[0].micro); },
+    async ourMovements({ since = null, until = null, refs = null } = {}) {
+      const { rows } = await db.query(OUR_REFS_SQL, [refs, since, until]);
+      return rows.map((r) => ({ ref: r.ref, amount_micro: Number(r.amount_micro), created_at: r.created_at, source: r.source }));
+    },
+    async recentChecks(limit = 10) {
+      const { rows } = await db.query('SELECT * FROM economy_ledger_checks ORDER BY created_at DESC, id DESC LIMIT $1', [limit]);
+      return rows;
+    },
+    async insertCheck(row) {
+      const { rows } = await db.query(
+        `INSERT INTO economy_ledger_checks
+           (outcome, reason, recorded_balance_micro, processor_balance_micro, drift_micro, window_from, window_to,
+            refs_compared, findings, fingerprint, alarm, blocker_id)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9::jsonb,$10,$11,$12) RETURNING *`,
+        [row.outcome, row.reason ?? null, row.recorded_balance_micro ?? null, row.processor_balance_micro ?? null,
+          row.drift_micro ?? null, row.window_from ?? null, row.window_to ?? null, row.refs_compared || 0,
+          JSON.stringify(row.findings || []), row.fingerprint ?? null, row.alarm || 'none', row.blocker_id ?? null]);
+      return rows[0];
+    },
+  };
+}
+
+// foldOurs(rows) — pure. One entry per reference; two of our records that give one
+// reference different amounts are themselves a finding.
+function foldOurs(rows) {
+  const byRef = new Map();
+  const findings = [];
+  for (const r of rows) {
+    const had = byRef.get(r.ref);
+    if (!had) { byRef.set(r.ref, { ref: r.ref, amount_micro: r.amount_micro, sources: [r.source] }); continue; }
+    had.sources.push(r.source);
+    if (had.amount_micro !== r.amount_micro && !findings.some((f) => f.ref === r.ref)) {
+      findings.push({ kind: 'records_disagree', ref: r.ref, ours_micro: had.amount_micro, other_micro: r.amount_micro, sources: had.sources.slice() });
+    }
+  }
+  return { byRef, findings };
+}
+
+// compareMovements({ ours, theirs, theirsInWindow, oursAnyTime }) — pure.
+//   ours           our movements inside the window (rows)
+//   theirs         the processor's movements over the wider window ({ ref, amountMicro, createdAt })
+//   inWindow(t)    whether one of theirs falls inside our window
+//   oursAnyTime    Map ref → our entry, for the processor's movements we did not find in-window
+// → findings (each names its reference and both amounts).
+function compareMovements({ ours, theirs, inWindow, oursAnyTime = new Map() }) {
+  const { byRef, findings } = foldOurs(ours);
+  const theirsByRef = new Map();
+  for (const t of theirs) {
+    const ref = typeof t.ref === 'string' ? t.ref.trim() : '';
+    if (!ref) continue;
+    const had = theirsByRef.get(ref);
+    // The processor may list one movement as several lines (a transfer and its reversal);
+    // what is compared is the movement's own amount, its first line.
+    if (!had) theirsByRef.set(ref, { ref, amount_micro: Number(t.amountMicro), createdAt: t.createdAt });
+  }
+  for (const o of byRef.values()) {
+    const t = theirsByRef.get(o.ref);
+    if (!t) findings.push({ kind: 'missing_at_processor', ref: o.ref, ours_micro: o.amount_micro, theirs_micro: null, sources: o.sources });
+    else if (t.amount_micro !== o.amount_micro) findings.push({ kind: 'amount_differs', ref: o.ref, ours_micro: o.amount_micro, theirs_micro: t.amount_micro, sources: o.sources });
+  }
+  for (const t of theirsByRef.values()) {
+    if (byRef.has(t.ref) || !inWindow(t)) continue;
+    const o = oursAnyTime.get(t.ref);
+    if (!o) findings.push({ kind: 'unknown_to_us', ref: t.ref, ours_micro: null, theirs_micro: t.amount_micro, sources: [] });
+    else if (o.amount_micro !== t.amount_micro) findings.push({ kind: 'amount_differs', ref: t.ref, ours_micro: o.amount_micro, theirs_micro: t.amount_micro, sources: o.sources });
+  }
+  return { findings, compared: new Set([...byRef.keys(), ...theirsByRef.keys()]).size };
+}
+
+const fingerprintOf = (keys) => crypto.createHash('sha1').update([...keys].sort().join('\n')).digest('hex').slice(0, 16);
+const findingKey = (f) => `${f.kind}:${f.ref || ''}:${f.ours_micro ?? ''}:${f.theirs_micro ?? ''}`;
+
+// Whether to raise this set. The last check that could say something (clean, drift or
+// error) decides: the same set it already raised is `unchanged`; anything else is new.
+function alarmDecision(recent, fingerprint) {
+  const last = (recent || []).find((r) => r.outcome === 'clean' || r.outcome === 'drift' || r.outcome === 'error');
+  if (last && last.outcome !== 'clean' && last.fingerprint === fingerprint && (last.alarm === 'filed' || last.alarm === 'unchanged')) return 'unchanged';
+  return 'file';
+}
+
+function isDue(recent, now, slackMs = 30 * 60_000) {
+  const last = (recent || [])[0];
+  if (!last) return true;
+  const at = new Date(last.created_at).getTime();
+  return !Number.isFinite(at) || now - at >= DAY_MS - slackMs;
+}
+
+// The blocker: public, so no amounts and no references (see THE ALARM above).
+function blockerFor(row) {
+  const day = new Date(row.created_at || Date.now()).toISOString().slice(0, 10);
+  if (row.outcome === 'error') {
+    return {
+      title: "Ledger check: the payment processor's records could not be read",
+      bodyMd: [
+        `The daily check of this project's money records against the payment processor (${day}) could not read the processor, so it could not confirm the records are right.`,
+        '',
+        "The details are on [Project settings](/project-settings), under *Where the money went*, for the project's owner.",
+        '',
+        'Filed by modules/economy/ledger-check.js (task 1004912). Raised once; a different result is raised again.',
+      ].join('\n'),
+    };
+  }
+  const n = row.findings.length;
+  return {
+    title: `Ledger check: our money records and the payment processor's differ (${n} ${n === 1 ? 'difference' : 'differences'})`,
+    bodyMd: [
+      `The daily check of this project's money records against the payment processor (${day}) found ${n} ${n === 1 ? 'difference' : 'differences'}. Until it is explained, a balance shown in Bongos may not match the money the processor holds.`,
+      '',
+      "The amounts and the processor's references for each difference are on [Project settings](/project-settings), under *Where the money went*, for the project's owner. They are not repeated here because this list is public: anyone can read it, and who was paid what is the project's own business.",
+      '',
+      'Nothing was changed or moved by the check. A wrong record is corrected by a new adjustment, never an edit.',
+      '',
+      'Filed by modules/economy/ledger-check.js (task 1004912). The same differences are not re-filed tomorrow; a changed set is.',
+    ].join('\n'),
+  };
+}
+
+// runLedgerCheck(deps) — one check, if one is due. Never throws for a processor failure (that
+// is recorded as `error`); a database failure is the caller's to log.
+//   deps: { pool, store, processor, fileBlocker, now, force, log }
+async function runLedgerCheck(deps = {}) {
+  const now = deps.now ? deps.now() : Date.now();
+  const pool = deps.pool;
+  const client = deps.client || (pool && typeof pool.connect === 'function' ? await pool.connect() : null);
+  const db = client || pool;
+  const store = deps.store || createStore(db);
+  try {
+    // One check at a time across every server process sharing this database.
+    if (client) {
+      const { rows } = await client.query('SELECT pg_try_advisory_lock($1, $2) AS got', LOCK);
+      if (!rows[0].got) return { skipped: 'busy' };
+    }
+    try {
+      const recent = await store.recentChecks(10);
+      if (!deps.force && !isDue(recent, now)) return { skipped: 'not_due' };
+      const row = await check({ store, processor: deps.processor, now, log: deps.log });
+      if (row.outcome === 'drift' || row.outcome === 'error') {
+        const decision = alarmDecision(recent, row.fingerprint);
+        if (decision === 'unchanged') row.alarm = 'unchanged';
+        else if (typeof deps.fileBlocker !== 'function') row.alarm = 'undelivered';
+        else {
+          try {
+            const b = await deps.fileBlocker({
+              ...blockerFor({ ...row, created_at: new Date(now) }),
+              source: 'ledger-check', sourceRef: `ledger-check-${row.fingerprint}-${new Date(now).toISOString().slice(0, 10)}`,
+            });
+            if (b && b.id) { row.alarm = 'filed'; row.blocker_id = String(b.id); } else row.alarm = 'unchanged';
+          } catch (e) {
+            if (deps.log) deps.log.error({ err: e.message }, 'ledger check: filing the alarm failed');
+            row.alarm = 'undelivered';
+          }
+        }
+      }
+      const saved = await store.insertCheck(row);
+      return { outcome: row.outcome, alarm: row.alarm, check: saved };
+    } finally {
+      if (client) await client.query('SELECT pg_advisory_unlock($1, $2)', LOCK).catch(() => {});
+    }
+  } finally {
+    if (client && !deps.client) client.release();
+  }
+}
+
+// check — the comparison itself, as the row to write.
+async function check({ store, processor, now, log }) {
+  const hasBalance = !!processor && typeof processor.balanceMicro === 'function';
+  const hasList = !!processor && typeof processor.listMovements === 'function';
+  const recorded = await store.recordedBalanceMicro();
+  if (!hasBalance && !hasList) {
+    return { outcome: 'unchecked', reason: 'no_processor', recorded_balance_micro: recorded, alarm: 'none' };
+  }
+  const windowTo = new Date(now - SETTLE_MS);
+  const windowFrom = new Date(windowTo.getTime() - WINDOW_DAYS * DAY_MS);
+  const findings = [];
+  const failed = [];
+  let processorMicro = null;
+  let drift = null;
+  let compared = 0;
+
+  if (hasBalance) {
+    try {
+      const v = Number(await withTimeout(Promise.resolve(processor.balanceMicro()), READ_TIMEOUT_MS));
+      if (!Number.isSafeInteger(v)) throw new Error('the processor gave no whole-number balance');
+      processorMicro = v;
+      drift = v - recorded;
+      if (drift !== 0) findings.push({ kind: 'balance', ref: null, ours_micro: recorded, theirs_micro: v });
+    } catch (e) {
+      failed.push('balance');
+      if (log) log.error({ err: e.message }, 'ledger check: processor balance unreadable');
+    }
+  }
+  if (hasList) {
+    try {
+      const theirs = await withTimeout(Promise.resolve(processor.listMovements({
+        since: new Date(windowFrom.getTime() - EDGE_MS), until: new Date(now),
+      })), READ_TIMEOUT_MS);
+      if (!Array.isArray(theirs)) throw new Error('the processor gave no list of movements');
+      const ours = await store.ourMovements({ since: windowFrom, until: windowTo });
+      const ourRefs = new Set(ours.map((o) => o.ref));
+      const inWindow = (t) => {
+        const at = new Date(t.createdAt).getTime();
+        return Number.isFinite(at) && at >= windowFrom.getTime() && at < windowTo.getTime();
+      };
+      const outside = [...new Set(theirs.filter((t) => t && inWindow(t) && !ourRefs.has(t.ref)).map((t) => t.ref))];
+      const oursAnyTime = outside.length ? foldOurs(await store.ourMovements({ refs: outside })).byRef : new Map();
+      const out = compareMovements({ ours, theirs: theirs.filter(Boolean), inWindow, oursAnyTime });
+      findings.push(...out.findings);
+      compared = out.compared;
+    } catch (e) {
+      failed.push('movements');
+      if (log) log.error({ err: e.message }, 'ledger check: processor movements unreadable');
+    }
+  }
+
+  const base = {
+    recorded_balance_micro: recorded, processor_balance_micro: processorMicro, drift_micro: drift,
+    window_from: hasList ? windowFrom : null, window_to: hasList ? windowTo : null, refs_compared: compared,
+  };
+  if (failed.length) {
+    // "Could not check" is never clean, even when the part that was read agreed.
+    return {
+      ...base, outcome: 'error', reason: `unreadable: ${failed.join(', ')}`,
+      findings: findings.slice(0, FINDINGS_MAX), fingerprint: fingerprintOf([`error:${failed.join(',')}`, ...findings.map(findingKey)]), alarm: 'none',
+    };
+  }
+  if (!findings.length) return { ...base, outcome: 'clean', findings: [], fingerprint: null, alarm: 'none' };
+  return { ...base, outcome: 'drift', findings: findings.slice(0, FINDINGS_MAX), fingerprint: fingerprintOf(findings.map(findingKey)), alarm: 'none' };
+}
+
+// readLedgerChecks(db, { limit }) — the owner's view: the newest checks, numbers included.
+async function readLedgerChecks(db, { limit = 10 } = {}) {
+  const lim = Math.min(Math.max(parseInt(limit, 10) || 10, 1), 60);
+  const rows = await createStore(db).recentChecks(lim);
+  const n = (v) => (v === null || v === undefined ? null : Number(v));
+  return {
+    unit: 'micro_usd', holds_money: false, kind_words: KIND_WORDS,
+    checks: rows.map((r) => ({
+      id: String(r.id), created_at: r.created_at, outcome: r.outcome, reason: r.reason,
+      recorded_balance_micro: n(r.recorded_balance_micro), processor_balance_micro: n(r.processor_balance_micro),
+      drift_micro: n(r.drift_micro), window_from: r.window_from, window_to: r.window_to,
+      refs_compared: Number(r.refs_compared), findings: r.findings || [], alarm: r.alarm,
+      blocker_id: r.blocker_id === null ? null : String(r.blocker_id),
+    })),
+  };
+}
+
+module.exports = {
+  WINDOW_DAYS, SETTLE_MS, KIND_WORDS,
+  createStore, isDue, runLedgerCheck, readLedgerChecks,
+};

package/modules/economy/migrations/economy_003_user_balances.sql

@@ -0,0 +1,116 @@
+-- economy_003_user_balances.sql — a user's money in this project, and the payments
+-- they make on their own instruction: funding the project, paying another user. No
+-- platform fee (task 1004907, goal 1000092 N3; ADR 0385, ADR 0387, ADR 0397 D2/D3).
+--
+-- NO BALANCE IS HERE. Each user's money sits in their own processor-held connected
+-- account, the project's in the project's (ADR 0397 D2). A balance on screen is a read
+-- of the processor's figure; nothing in these tables is ever summed into one. These
+-- tables record which account is whose, what a person asked to move, and what the
+-- processor said, so "why did my balance change" always has an answer.
+--
+--   economy_member_accounts         which processor account belongs to which user, in
+--                                   THIS project. One account never belongs to two
+--                                   people. The latest row for a user is their account.
+--   economy_user_transfers          one row per instruction a person gave: fund the
+--                                   project, or pay another user. Written before the
+--                                   processor is asked, naming both accounts used.
+--   economy_user_transfer_attempts  every try at carrying one instruction out: sent
+--                                   (with the processor's transfer reference), failed
+--                                   or held (with the reason). At most one sent.
+--
+-- ISOLATION. Every project runs its own database (ADR 0100), so another project's users,
+-- accounts and transfers are not in these tables at all. A transfer may only name
+-- accounts linked here, and a link is only written once this project's own processor
+-- connection confirms the account is one it opened. So one project can neither see nor
+-- spend another's balance (tests/user_balances_db.mjs proves it with two projects).
+--
+-- FEE-FREE is a column, not a promise: platform_fee_cents must be 0. Charging a fee on
+-- these transfers is a migration and a decision, not a quiet code change.
+--
+-- All three tables are append-only: a wrong row is answered by a new one.
+
+CREATE TABLE IF NOT EXISTS economy_member_accounts (
+  id                BIGSERIAL   PRIMARY KEY,
+  builder_id        BIGINT      NOT NULL REFERENCES builders(id),
+  processor_account TEXT        NOT NULL,
+  linked_by         BIGINT      REFERENCES builders(id),
+  created_at        TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT economy_member_accounts_ref_chk CHECK (processor_account ~ '^[A-Za-z0-9_.:-]{3,200}$')
+);
+
+-- one account, one person
+CREATE UNIQUE INDEX IF NOT EXISTS economy_member_accounts_one_owner
+  ON economy_member_accounts (processor_account);
+CREATE INDEX IF NOT EXISTS economy_member_accounts_by_builder
+  ON economy_member_accounts (builder_id, id DESC);
+
+CREATE TABLE IF NOT EXISTS economy_user_transfers (
+  id                 BIGSERIAL   PRIMARY KEY,
+  kind               TEXT        NOT NULL,
+  from_builder_id    BIGINT      NOT NULL REFERENCES builders(id),
+  to_builder_id      BIGINT      REFERENCES builders(id),
+  from_account       TEXT        NOT NULL,
+  to_account         TEXT,
+  amount_cents       BIGINT      NOT NULL,
+  currency           TEXT        NOT NULL DEFAULT 'USD',
+  platform_fee_cents BIGINT      NOT NULL DEFAULT 0,
+  instruction_id     TEXT        NOT NULL,
+  note               TEXT        NOT NULL DEFAULT '',
+  created_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT economy_user_transfers_kind_chk CHECK (kind IN ('fund_project', 'pay_user')),
+  CONSTRAINT economy_user_transfers_amount_chk CHECK (amount_cents > 0),
+  CONSTRAINT economy_user_transfers_currency_chk CHECK (currency = 'USD'),
+  CONSTRAINT economy_user_transfers_fee_free_chk CHECK (platform_fee_cents = 0),
+  CONSTRAINT economy_user_transfers_note_chk CHECK (length(note) <= 300),
+  CONSTRAINT economy_user_transfers_instruction_chk CHECK (instruction_id ~ '^[A-Za-z0-9_-]{8,80}$'),
+  -- funding goes to the project's own account; a payment names a different person
+  CONSTRAINT economy_user_transfers_target_chk CHECK (
+    (kind = 'fund_project' AND to_builder_id IS NULL AND to_account IS NULL) OR
+    (kind = 'pay_user' AND to_builder_id IS NOT NULL AND to_account IS NOT NULL
+                       AND to_builder_id <> from_builder_id AND to_account <> from_account))
+);
+
+-- one instruction is carried out once, however often the button is pressed
+CREATE UNIQUE INDEX IF NOT EXISTS economy_user_transfers_one_per_instruction
+  ON economy_user_transfers (from_builder_id, instruction_id);
+CREATE INDEX IF NOT EXISTS economy_user_transfers_by_from ON economy_user_transfers (from_builder_id, id DESC);
+CREATE INDEX IF NOT EXISTS economy_user_transfers_by_to ON economy_user_transfers (to_builder_id, id DESC) WHERE to_builder_id IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS economy_user_transfer_attempts (
+  id            BIGSERIAL   PRIMARY KEY,
+  transfer_id   BIGINT      NOT NULL REFERENCES economy_user_transfers(id),
+  outcome       TEXT        NOT NULL,
+  processor_ref TEXT,
+  reason        TEXT,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT economy_user_transfer_attempts_outcome_chk CHECK (outcome IN ('sent', 'failed', 'held')),
+  CONSTRAINT economy_user_transfer_attempts_reason_len_chk CHECK (reason IS NULL OR length(reason) <= 300),
+  CONSTRAINT economy_user_transfer_attempts_cause_chk CHECK (
+    (outcome = 'sent' AND processor_ref IS NOT NULL) OR
+    (outcome IN ('failed', 'held') AND reason IS NOT NULL AND length(reason) > 0))
+);
+
+-- sent at most once
+CREATE UNIQUE INDEX IF NOT EXISTS economy_user_transfer_attempts_one_sent
+  ON economy_user_transfer_attempts (transfer_id) WHERE outcome = 'sent';
+CREATE INDEX IF NOT EXISTS economy_user_transfer_attempts_by_transfer
+  ON economy_user_transfer_attempts (transfer_id, id DESC);
+
+CREATE OR REPLACE FUNCTION economy_user_balances_append_only() RETURNS trigger AS $$
+BEGIN
+  RAISE EXCEPTION '% is append-only: record a new row instead', TG_TABLE_NAME;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS economy_member_accounts_no_rewrite ON economy_member_accounts;
+CREATE TRIGGER economy_member_accounts_no_rewrite BEFORE UPDATE OR DELETE ON economy_member_accounts
+  FOR EACH ROW EXECUTE FUNCTION economy_user_balances_append_only();
+DROP TRIGGER IF EXISTS economy_user_transfers_no_rewrite ON economy_user_transfers;
+CREATE TRIGGER economy_user_transfers_no_rewrite BEFORE UPDATE OR DELETE ON economy_user_transfers
+  FOR EACH ROW EXECUTE FUNCTION economy_user_balances_append_only();
+DROP TRIGGER IF EXISTS economy_user_transfer_attempts_no_rewrite ON economy_user_transfer_attempts;
+CREATE TRIGGER economy_user_transfer_attempts_no_rewrite BEFORE UPDATE OR DELETE ON economy_user_transfer_attempts
+  FOR EACH ROW EXECUTE FUNCTION economy_user_balances_append_only();
+
+INSERT INTO schema_migrations (version) VALUES ('economy_003_user_balances')
+  ON CONFLICT DO NOTHING;

package/modules/economy/migrations/economy_004_module_share_payouts.sql

@@ -0,0 +1,22 @@
+-- economy_004_module_share_payouts.sql — a payout out of the project's account may be a
+-- module-sale share instead of a task (task 1004910, goal 1000092 N6; ADR 0388 D5).
+--
+-- A module sale pays its seller and contributors by transfer from the project's account,
+-- and none of those transfers is "for a task". The cause rule still holds: a payout names
+-- the person paid, the processor transfer, and EITHER the task OR the module-sale share
+-- it was for (core_292's module_sale_shares_owed). No foreign key: the share table is
+-- core's, and a module migration does not reach into core's schema.
+
+ALTER TABLE economy_project_account_movements ADD COLUMN IF NOT EXISTS module_share_id BIGINT;
+
+ALTER TABLE economy_project_account_movements DROP CONSTRAINT IF EXISTS economy_project_account_cause_chk;
+ALTER TABLE economy_project_account_movements ADD CONSTRAINT economy_project_account_cause_chk CHECK (
+  (kind = 'payout'        AND builder_id IS NOT NULL AND processor_ref IS NOT NULL
+                          AND (task_id IS NOT NULL OR module_share_id IS NOT NULL)) OR
+  (kind = 'payout_return' AND builder_id IS NOT NULL AND processor_ref IS NOT NULL) OR
+  (kind IN ('funding', 'fee') AND processor_ref IS NOT NULL) OR
+  (kind = 'adjustment'    AND corrects_id IS NOT NULL AND actor_id IS NOT NULL AND length(note) > 0) OR
+  (kind IN ('hold', 'hold_release') AND task_id IS NOT NULL));
+
+INSERT INTO schema_migrations (version) VALUES ('economy_004_module_share_payouts')
+  ON CONFLICT DO NOTHING;

package/modules/economy/migrations/economy_005_project_account_holds_index.sql

@@ -0,0 +1,20 @@
+-- economy_005_project_account_holds_index.sql — the funding wall's hold read stays cheap
+-- (task 1003185, goal 1000092 M06; ADR 0386).
+--
+-- Every claim of a cash-paying task under the default rule (hold at claim) nets each
+-- task's holds against its releases (modules/economy/project-account.js, NET_HOLDS_SQL).
+-- The record is append-only and keeps every row forever, so without this the read
+-- scans every movement the project has ever booked. A partial index over just the hold
+-- and release rows, carrying the two columns the read sums, lets it read those alone.
+--
+-- Numbered 005 to stay clear of the economy migrations other tasks of this goal are
+-- adding at the same time.
+--
+-- Additive: one index on this module's own table, nothing else.
+
+CREATE INDEX IF NOT EXISTS economy_project_account_holds
+  ON economy_project_account_movements (task_id) INCLUDE (kind, amount_micro)
+  WHERE kind IN ('hold', 'hold_release');
+
+INSERT INTO schema_migrations (version) VALUES ('economy_005_project_account_holds_index')
+  ON CONFLICT DO NOTHING;

package/modules/economy/migrations/economy_006_ledger_checks.sql

@@ -0,0 +1,68 @@
+-- economy_006_ledger_checks.sql — one row per daily check of our record against the
+-- processor's (task 1004912, goal 1000092 N8; ADR 0397 decision 7).
+--
+-- The check itself is modules/economy/ledger-check.js. Each run writes one row saying what it
+-- compared and what it found, so "did yesterday's check run, and did the figures agree" is a
+-- read of this table, and an alarm is raised only when the set of differences changes.
+--
+--   outcome   clean      both sides were read and agree
+--             drift      both sides were read and differ; findings names each difference
+--             unchecked  no processor is connected, so there was nothing to compare with
+--             error      the processor could not be read; never recorded as clean
+--   alarm     filed      a blocker was opened for the owner (blocker_id)
+--             unchanged  the same differences as the last alarm, so none was re-filed
+--             undelivered  there was something to raise and nowhere it could be filed
+--             none       nothing to raise
+--
+-- Holds no money and no balance of anyone's: the figures are copies of what was compared that
+-- day. Append-only, like the account it checks.
+--
+-- Also one partial index on this module's economy_user_transfer_attempts: the check reads the
+-- last week's `sent` member payments by time, and the table's only indexes are by transfer, so
+-- without it every daily check scans every attempt ever made. (The same index on core's
+-- cash_out_attempts is core_294, since a module migration may only touch its own tables.)
+--
+-- Additive: one new table and one index, both on this module's own side, nothing else.
+
+CREATE TABLE IF NOT EXISTS economy_ledger_checks (
+  id                      BIGSERIAL   PRIMARY KEY,
+  outcome                 TEXT        NOT NULL,
+  reason                  TEXT,
+  recorded_balance_micro  BIGINT,
+  processor_balance_micro BIGINT,
+  drift_micro             BIGINT,
+  window_from             TIMESTAMPTZ,
+  window_to               TIMESTAMPTZ,
+  refs_compared           INTEGER     NOT NULL DEFAULT 0,
+  findings                JSONB       NOT NULL DEFAULT '[]'::jsonb,
+  fingerprint             TEXT,
+  alarm                   TEXT        NOT NULL DEFAULT 'none',
+  blocker_id              BIGINT,
+  created_at              TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT economy_ledger_checks_outcome_chk CHECK (outcome IN ('clean', 'drift', 'unchecked', 'error')),
+  CONSTRAINT economy_ledger_checks_alarm_chk CHECK (alarm IN ('filed', 'unchanged', 'undelivered', 'none')),
+  CONSTRAINT economy_ledger_checks_shape CHECK (
+    (outcome = 'clean'     AND fingerprint IS NULL AND alarm = 'none') OR
+    (outcome = 'drift'     AND fingerprint IS NOT NULL AND alarm <> 'none') OR
+    (outcome = 'unchecked' AND reason IS NOT NULL AND alarm = 'none') OR
+    (outcome = 'error'     AND reason IS NOT NULL AND fingerprint IS NOT NULL AND alarm <> 'none')),
+  CONSTRAINT economy_ledger_checks_blocker CHECK ((alarm = 'filed') = (blocker_id IS NOT NULL))
+);
+
+CREATE INDEX IF NOT EXISTS economy_ledger_checks_by_time ON economy_ledger_checks (created_at DESC, id DESC);
+
+-- Append-only: a check that was wrong is followed by a new check, never edited.
+CREATE OR REPLACE FUNCTION economy_ledger_checks_append_only() RETURNS trigger AS $$
+BEGIN
+  RAISE EXCEPTION 'economy_ledger_checks is append-only' USING ERRCODE = '42501';
+END $$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS economy_ledger_checks_no_change ON economy_ledger_checks;
+CREATE TRIGGER economy_ledger_checks_no_change BEFORE UPDATE OR DELETE ON economy_ledger_checks
+  FOR EACH ROW EXECUTE FUNCTION economy_ledger_checks_append_only();
+
+CREATE INDEX IF NOT EXISTS economy_user_transfer_attempts_sent_by_time
+  ON economy_user_transfer_attempts (created_at) WHERE outcome = 'sent';
+
+INSERT INTO schema_migrations (version) VALUES ('economy_006_ledger_checks')
+  ON CONFLICT DO NOTHING;

package/modules/economy/module.json

@@ -7,7 +7,7 @@
   "category": { "parent": "money" },
   "default": true,
   "maintenance": { "status": "core-maintained" },
-  "contributes": { "migrations": true, "routes": ["cost", "credits", "earnings", "leaderboard", "project-account", "reward"] },
+  "contributes": { "migrations": true, "routes": ["cost", "credits", "earnings", "leaderboard", "project-account", "balances", "reward"], "pollers": ["ledger-check"] },
   "provides": ["reward", "economy.account"],
   "consumes": []
 }