@bongos/core 1.24.23 → 1.24.25

package/modules/economy/outflow.js

@@ -0,0 +1,209 @@
+'use strict';
+
+// modules/economy/outflow.js — WHERE THE MONEY WENT: the owner's outflow view (task 1003184,
+// goal 1000092 M05; criterion money-outflow-visible).
+//
+// WHY. A balance that looks healthy while it already owes three payouts is a trap. So this
+// view puts three things beside the project account's balance: what the project spent each
+// month, what each builder has been paid, and — the one people forget — what is COMMITTED
+// BUT NOT YET PAID, with the balance that is left once those commitments are met.
+//
+// A READ, NOT A SECOND CAPTURE PATH. Every figure is summed from a record something else
+// already writes: cost_log (the spend /cost and /public/cost-summary already draw, ADR 0028),
+// the project-account movements (project-account.js), and core's payout records
+// (builder_payouts_owed + builder_payout_attempts, task 1003183; payout_approvals). Nothing
+// here writes. It reads core's tables by SQL the way credits.js reads credit_log.
+//
+// WHAT "COMMITTED" COUNTS, and why each:
+//   * owed       — a payout recorded as owed (builder_payouts_owed) with no `sent` attempt.
+//                  The debt is on record; it has not left the account.
+//   * approved   — a person's `payout_approved` approval no payout has been booked against
+//                  yet. The owner has authorised it; nothing is owed on record until someone
+//                  presses pay, so leaving it out would understate what the balance must cover.
+//   * held       — the account's own holds (project-account.js `held_micro`), already taken
+//                  out of `available_micro`, so they are shown and never subtracted twice. A
+//                  shipped task keeps its hold until it is paid, so an owed debt counts only
+//                  the part its task's hold does not already cover (task 1003186).
+// Only US-dollar commitments are summed: the account is kept in USD (builder-payouts.js), so
+// a commitment in another currency is counted separately and never added to a dollar figure.
+//
+// Units: every figure is integer micro-dollars, the project account's own unit. cost_log is
+// numeric USD and the payout records are cents; both are converted in SQL.
+
+const { accountTotals, readLiveHolds } = require('./project-account');
+
+const MICRO_PER_CENT = 10_000;
+const MONTHS_DEFAULT = 12;
+const MONTHS_MAX = 36;
+const OWED_LIST_MAX = 50;
+
+const n = (v) => Number(v || 0);
+
+// Spend and money out of the account per calendar month, every month in the window present
+// (a quiet month is a real zero, not a gap). to_char labels the month in SQL so no driver
+// timezone can move a row into its neighbour (the cost.js by_month precedent).
+const BURN_SQL = `
+  WITH months AS (
+    SELECT to_char(m, 'YYYY-MM') AS month
+      FROM generate_series(date_trunc('month', now()) - (($1::int - 1) * interval '1 month'),
+                           date_trunc('month', now()), interval '1 month') AS m
+  ),
+  spend AS (
+    SELECT to_char(recorded_at, 'YYYY-MM') AS month, SUM(amount_usd) * 1000000 AS micro
+      FROM cost_log
+     WHERE recorded_at >= date_trunc('month', now()) - (($1::int - 1) * interval '1 month')
+     GROUP BY 1
+  ),
+  paid AS (
+    SELECT to_char(created_at, 'YYYY-MM') AS month,
+           SUM(CASE WHEN kind = 'payout' THEN amount_micro ELSE 0 END) AS payouts_micro,
+           SUM(CASE WHEN direction = 'out' AND kind <> 'payout' THEN amount_micro ELSE 0 END) AS other_out_micro
+      FROM economy_project_account_movements
+     WHERE created_at >= date_trunc('month', now()) - (($1::int - 1) * interval '1 month')
+     GROUP BY 1
+  )
+  SELECT m.month,
+         COALESCE(round(s.micro), 0)       AS spend_micro,
+         COALESCE(p.payouts_micro, 0)      AS payouts_micro,
+         COALESCE(p.other_out_micro, 0)    AS other_out_micro
+    FROM months m
+    LEFT JOIN spend s ON s.month = m.month
+    LEFT JOIN paid p  ON p.month = m.month
+   ORDER BY m.month`;
+
+// One row per payout debt with where it stands, plus every approval nothing has been booked
+// against. The two halves are the per-builder totals and the commitments, read once.
+const PAYOUTS_SQL = `
+  SELECT o.id, o.builder_id, o.task_id, t.title AS task_title, o.amount_cents, o.currency,
+         o.created_at, (s.id IS NOT NULL) AS paid,
+         l.outcome AS last_outcome, l.reason AS last_reason
+    FROM builder_payouts_owed o
+    LEFT JOIN tasks t ON t.id = o.task_id
+    LEFT JOIN builder_payout_attempts s ON s.owed_id = o.id AND s.outcome = 'sent'
+    LEFT JOIN LATERAL (
+      SELECT outcome, reason FROM builder_payout_attempts a
+       WHERE a.owed_id = o.id ORDER BY a.id DESC LIMIT 1) l ON true`;
+
+const APPROVED_SQL = `
+  SELECT a.id, a.recipient_id AS builder_id, a.amount_cents, a.currency, a.created_at
+    FROM payout_approvals a
+   WHERE a.kind = 'payout_approved'
+     AND NOT EXISTS (SELECT 1 FROM builder_payouts_owed o WHERE o.approval_id = a.id)
+     -- an approval bound to a module-sale share is spent too (task 1004910, core_292)
+     AND NOT EXISTS (SELECT 1 FROM module_share_approvals m WHERE m.approval_id = a.id)`;
+
+const SPEND_BY_BUILDER_SQL = `
+  SELECT builder_id, round(SUM(amount_usd) * 1000000) AS spend_micro
+    FROM cost_log WHERE builder_id IS NOT NULL GROUP BY builder_id`;
+
+const SPEND_TOTAL_SQL = 'SELECT round(COALESCE(SUM(amount_usd), 0) * 1000000) AS micro FROM cost_log';
+
+const NAMES_SQL = 'SELECT id, display_name, github_login FROM builders WHERE id = ANY($1::bigint[])';
+
+// shapeOutflow — pure. Everything the route returns is decided here, so the sums are tested
+// without a database. `account` is accountTotals' row (recorded/held/available).
+function shapeOutflow({ burn, payouts, approved, spendByBuilder, spendTotal, account, names, liveHolds }) {
+  const usd = (r) => r.currency === 'USD';
+  const micro = (r) => n(r.amount_cents) * MICRO_PER_CENT;
+  const nameOf = new Map((names || []).map((b) => [String(b.id), b.display_name || b.github_login || null]));
+
+  const builders = new Map();
+  const row = (id) => {
+    const key = String(id);
+    if (!builders.has(key)) {
+      builders.set(key, { builder_id: key, builder_name: nameOf.get(key) || null, spend_micro: 0, paid_micro: 0, owed_micro: 0, approved_micro: 0 });
+    }
+    return builders.get(key);
+  };
+  for (const s of spendByBuilder || []) row(s.builder_id).spend_micro += n(s.spend_micro);
+
+  const owed = [];
+  const heldFor = liveHolds instanceof Map ? liveHolds : new Map();
+  let owedMicro = 0;
+  let coveredMicro = 0;
+  let paidMicro = 0;
+  let otherCurrency = 0;
+  for (const p of payouts || []) {
+    if (!usd(p)) { if (!p.paid) otherCurrency += 1; continue; }
+    if (p.paid) { row(p.builder_id).paid_micro += micro(p); paidMicro += micro(p); continue; }
+    row(p.builder_id).owed_micro += micro(p);
+    owedMicro += micro(p);
+    const covered = Math.min(micro(p), n(heldFor.get(String(p.task_id))));
+    coveredMicro += covered;
+    owed.push({
+      owed_id: String(p.id), builder_id: String(p.builder_id), builder_name: nameOf.get(String(p.builder_id)) || null,
+      task_id: String(p.task_id), task_title: p.task_title || null, amount_micro: micro(p), held_micro: covered,
+      since: p.created_at, last_outcome: p.last_outcome || null, last_reason: p.last_reason || null,
+    });
+  }
+  let approvedMicro = 0;
+  let approvedCount = 0;
+  for (const a of approved || []) {
+    if (!usd(a)) { otherCurrency += 1; continue; }
+    row(a.builder_id).approved_micro += micro(a);
+    approvedMicro += micro(a);
+    approvedCount += 1;
+  }
+
+  // Oldest debt first: the one that has waited longest is the one to act on.
+  owed.sort((a, b) => new Date(a.since) - new Date(b.since) || Number(a.owed_id) - Number(b.owed_id));
+  const byBuilder = [...builders.values()]
+    .map((b) => ({ ...b, total_micro: b.spend_micro + b.paid_micro + b.owed_micro + b.approved_micro }))
+    .filter((b) => b.total_micro > 0)
+    .sort((a, b) => b.total_micro - a.total_micro || Number(a.builder_id) - Number(b.builder_id));
+
+  const months = (burn || []).map((m) => {
+    const spend = n(m.spend_micro);
+    const payoutsOut = n(m.payouts_micro);
+    const other = n(m.other_out_micro);
+    return { month: m.month, spend_micro: spend, payouts_micro: payoutsOut, other_out_micro: other, total_micro: spend + payoutsOut + other };
+  });
+
+  const recorded = n(account.recorded_balance_micro);
+  const held = n(account.held_micro);
+  const available = recorded - held;
+  const committed = owedMicro + approvedMicro;
+  const notYetOut = committed - coveredMicro; // the covered part is already out of available
+  return {
+    unit: 'micro_usd',
+    holds_money: false,
+    burn: { months, window_total_micro: months.reduce((s, m) => s + m.total_micro, 0) },
+    totals: { spend_micro: n(spendTotal), paid_micro: paidMicro },
+    by_builder: byBuilder,
+    committed: {
+      owed_micro: owedMicro,
+      owed_count: owed.length,
+      approved_micro: approvedMicro,
+      approved_count: approvedCount,
+      held_micro: held,
+      total_micro: committed,
+      other_currency_count: otherCurrency,
+      owed: owed.slice(0, OWED_LIST_MAX),
+    },
+    balance: {
+      recorded_micro: recorded,
+      available_micro: available,
+      // The figure the page leads with: what is left once every commitment above is met.
+      // Negative means the project already owes more than it holds.
+      after_commitments_micro: available - notYetOut,
+    },
+  };
+}
+
+// readOutflow(db, { months }) — the owner's view. db is a pool or a client.
+async function readOutflow(db, { months = MONTHS_DEFAULT } = {}) {
+  const win = Math.min(Math.max(parseInt(months, 10) || MONTHS_DEFAULT, 1), MONTHS_MAX);
+  const [burn, payouts, approved, spendByBuilder, spendTotal, account, liveHolds] = await Promise.all([
+    db.query(BURN_SQL, [win]), db.query(PAYOUTS_SQL), db.query(APPROVED_SQL),
+    db.query(SPEND_BY_BUILDER_SQL), db.query(SPEND_TOTAL_SQL), accountTotals(db), readLiveHolds(db),
+  ]);
+  const ids = new Set();
+  for (const r of [...payouts.rows, ...approved.rows, ...spendByBuilder.rows]) ids.add(String(r.builder_id));
+  const names = ids.size ? (await db.query(NAMES_SQL, [[...ids]])).rows : [];
+  return shapeOutflow({
+    burn: burn.rows, payouts: payouts.rows, approved: approved.rows, spendByBuilder: spendByBuilder.rows,
+    spendTotal: spendTotal.rows[0].micro, account, names, liveHolds,
+  });
+}
+
+module.exports = { shapeOutflow, readOutflow };

package/modules/economy/pollers/ledger-check.js

@@ -0,0 +1,87 @@
+'use strict';
+
+// modules/economy/pollers/ledger-check.js — fire the daily ledger check from the server itself
+// (task 1004912, goal 1000092 N8). The check is ../ledger-check.js.
+//
+// A COPY OF THE daily-checks SHAPE (modules/autonomy/pollers/daily-checks.js), not an import of
+// it (modules may not require each other): one unref'd HOURLY tick, the first a few minutes
+// after boot plus jitter, kill-switched by ROUTINE_TIMERS_DISABLED=1, and it never throws into
+// the server. DUE BY THE LEDGER, NOT BY THE BOOT: each tick asks economy_ledger_checks whether
+// the newest check is a day old, so a deploy restarts the timer and changes nothing about when
+// the next check runs.
+//
+// THE TWO PORTS, both resolved optionally and neither declared in `consumes` (declaring one
+// would make "module off" into "instance will not start"; the ideas.descent precedent):
+//   economy.processor  the processor adapter, when one lands (task 1005040). Absent today, so
+//                      every check is recorded `unchecked` (no_processor) and raises nothing.
+//   ideas.fileBlocker  where the alarm goes: the owner's blocker queue (ideas module).
+
+const api = require('../../../src/module-api');
+const { runLedgerCheck } = require('../ledger-check');
+
+const log = api.logger('economy');
+
+const TICK_MS = Number(process.env.LEDGER_CHECK_TICK_MS) || 60 * 60_000;
+// After daily-checks' 3 minutes, so the two first ticks never land together.
+const FIRST_MS = Number(process.env.LEDGER_CHECK_FIRST_MS) || 5 * 60_000;
+const JITTER_MS = 60_000;
+
+let running = false;
+let warnedUnreachable = false;
+
+// tick(deps) — one look at the ledger, and a check if one is due. NEVER throws.
+async function tick(deps = {}) {
+  if (running) return { skipped: 'busy' };
+  running = true;
+  try {
+    const r = await runLedgerCheck({
+      pool: deps.pool || api.pool,
+      processor: deps.processor !== undefined ? deps.processor : api.resolveOptional('economy.processor'),
+      fileBlocker: deps.fileBlocker !== undefined ? deps.fileBlocker : api.resolveOptional('ideas.fileBlocker'),
+      now: deps.now,
+      log,
+    });
+    if (r.outcome) log.info(`[ledger-check] ${r.outcome}${r.alarm && r.alarm !== 'none' ? ` (alarm ${r.alarm})` : ''}`);
+    return r;
+  } catch (e) {
+    const msg = (e && e.message) || String(e);
+    if (/ECONNREFUSED|ENOTFOUND|does not exist|connect/i.test(msg)) {
+      if (!warnedUnreachable) { warnedUnreachable = true; log.info(`[ledger-check] skipped — database unreachable (${msg})`); }
+      return { skipped: 'db_unreachable' };
+    }
+    log.error(`[ledger-check] tick failed: ${msg}`);
+    if (typeof deps.reportError === 'function') deps.reportError();
+    return { skipped: 'error', error: msg };
+  } finally {
+    running = false;
+  }
+}
+
+let firstTimer = null;
+let interval = null;
+
+// Only reportError is taken from the loader's deps, so a loader dep can never be read as a
+// check seam (pool, processor, fileBlocker).
+function start({ reportError } = {}) {
+  if (process.env.ROUTINE_TIMERS_DISABLED === '1') {
+    log.info('[ledger-check] disabled (ROUTINE_TIMERS_DISABLED=1)');
+    return;
+  }
+  if (firstTimer || interval) return;
+  const fire = () => tick({ reportError });
+  firstTimer = setTimeout(() => {
+    firstTimer = null;
+    fire();
+    interval = setInterval(fire, TICK_MS);
+    if (interval.unref) interval.unref();
+  }, FIRST_MS + Math.floor(Math.random() * JITTER_MS));
+  if (firstTimer.unref) firstTimer.unref();
+}
+
+function stop() {
+  if (firstTimer) clearTimeout(firstTimer);
+  if (interval) clearInterval(interval);
+  firstTimer = interval = null;
+}
+
+module.exports = { start, stop, tick, TICK_MS };

package/modules/economy/project-account.js

@@ -50,7 +50,8 @@ function checkMovement(input) {
   }
   const need = (cond, what) => { if (!cond) throw new MovementRefusal('cause_missing', `a ${i.kind} must name ${what}`); };
   if (i.kind === 'payout') {
-    need(isId(i.builderId), 'the builder paid'); need(isId(i.taskId), 'the task it was for'); need(present(i.processorRef), 'the processor transfer');
+    need(isId(i.builderId), 'the builder paid'); need(isId(i.taskId) || isId(i.moduleShareId), 'the task or module-sale share it was for');
+    need(present(i.processorRef), 'the processor transfer');
   } else if (i.kind === 'payout_return') {
     need(isId(i.builderId), 'the builder it came back from'); need(present(i.processorRef), 'the processor reference');
   } else if (i.kind === 'funding' || i.kind === 'fee') {
@@ -64,6 +65,7 @@ function checkMovement(input) {
     kind: i.kind, direction, amount_micro: amount,
     builder_id: isId(i.builderId) ? String(i.builderId) : null,
     task_id: isId(i.taskId) ? String(i.taskId) : null,
+    module_share_id: isId(i.moduleShareId) ? String(i.moduleShareId) : null,
     corrects_id: isId(i.correctsId) ? String(i.correctsId) : null,
     processor_ref: present(i.processorRef) ? i.processorRef.trim() : null,
     actor_id: isId(i.actorId) ? String(i.actorId) : null,
@@ -78,11 +80,11 @@ async function recordMovement(db, input) {
   const r = checkMovement(input);
   const ins = await db.query(
     `INSERT INTO economy_project_account_movements
-       (kind, direction, amount_micro, builder_id, task_id, corrects_id, processor_ref, actor_id, note)
-     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)
+       (kind, direction, amount_micro, builder_id, task_id, corrects_id, processor_ref, actor_id, note, module_share_id)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)
      ON CONFLICT (kind, processor_ref) WHERE processor_ref IS NOT NULL DO NOTHING
      RETURNING *`,
-    [r.kind, r.direction, r.amount_micro, r.builder_id, r.task_id, r.corrects_id, r.processor_ref, r.actor_id, r.note]);
+    [r.kind, r.direction, r.amount_micro, r.builder_id, r.task_id, r.corrects_id, r.processor_ref, r.actor_id, r.note, r.module_share_id]);
   if (ins.rows[0]) return { recorded: true, row: ins.rows[0] };
   // Only the one-per-reference rule is absorbed above, so a skipped insert always has a reference.
   const had = await db.query(
@@ -108,6 +110,16 @@ const RECENT_SQL = `
    ORDER BY m.created_at DESC, m.id DESC
    LIMIT $1 OFFSET $2`;
 
+// accountTotals(db) → the one aggregate row (recorded balance, held, in, out, count). The
+// outflow view (outflow.js) reads the same sums, so they live in one statement.
+// What is HELD is what the funding wall holds: only holds for work still in flight
+// (task 1003185, readAvailable below). A hold whose task shipped or was let go before its
+// hold_release row was written is not counted, so neither view shows money reserved for nothing.
+async function accountTotals(db) {
+  const [totals, live] = await Promise.all([db.query(TOTALS_SQL), readAvailable(db)]);
+  return { ...totals.rows[0], held_micro: live.held_micro };
+}
+
 // shapeAccount — pure. totals is the one aggregate row, processorMicro the processor's own
 // balance or null when no processor is connected. available = what the project could still
 // commit: the recorded balance less what is held. drift is only named when both figures exist.
@@ -156,11 +168,84 @@ async function readAccount(db, { limit = 50, offset = 0, processor = null, log =
   const lim = Math.min(Math.max(parseInt(limit, 10) || 50, 1), 200);
   const off = Math.max(parseInt(offset, 10) || 0, 0);
   const [totals, recent, read] = await Promise.all([
-    db.query(TOTALS_SQL), db.query(RECENT_SQL, [lim, off]), readProcessor(processor, log),
+    accountTotals(db), db.query(RECENT_SQL, [lim, off]), readProcessor(processor, log),
   ]);
-  const out = shapeAccount(totals.rows[0], recent.rows, read.micro);
+  const out = shapeAccount(totals, recent.rows, read.micro);
   if (read.failed) out.processor_error = 'The processor balance could not be read just now.';
   return out;
 }
 
-module.exports = { MovementRefusal, checkMovement, recordMovement, shapeAccount, readAccount };
+// ── the funding wall's half (task 1003185, ADR 0386) ────────────────────────
+//
+// The wall itself (which rule, which task, the refusal) is the lifecycle module's: it owns
+// the claim transaction. What it needs from the account is three things, reached through
+// the `economy.account` port with the caller's own transaction client:
+//
+//   lockAccount        one advisory lock for the whole account, held to commit, so two
+//                      claims cannot both read the same available figure and both hold it
+//   releaseSettledHolds  a `hold_release` row for every hold whose task is no longer in
+//                      work and owes nothing (paid, released back to the queue, abandoned). Holds are
+//                      let go by STATE, not by hooking each of the paths that release a
+//                      claim, so none of them can leave a hold behind for good
+//   readAvailable      recorded balance, what is held for work in flight or shipped and not
+//                      yet paid, and the difference. `exceptTaskId` leaves one task's own hold
+//                      out, for the completion-time check of a task that was held at claim
+//   readLiveHolds      the same holds task by task, so the outflow view can tell a debt the
+//                      balance already covers from one it does not (outflow.js)
+
+// A hold counts while its task is being worked: claimed, declared done, or graded. It also
+// counts once the task has SHIPPED, until a `payout` movement for that task is booked: the
+// builder is paid after the ship, by a person's approval (builder-payouts.js), and letting
+// the hold go at the ship left that pay unreserved, so a second claim could be promised the
+// same money (found by the end-to-end proof, task 1003186).
+const HELD_STATUSES = Object.freeze(['active', 'completed', 'confirmed']);
+const LIVE_HOLD_SQL = `(t.status = ANY($1::text[]) OR (t.status = 'shipped' AND NOT EXISTS (
+       SELECT 1 FROM economy_project_account_movements p WHERE p.kind = 'payout' AND p.task_id = h.task_id)))`;
+const ACCOUNT_LOCK = [1003185, 1];
+
+const NET_HOLDS_SQL = `
+  SELECT m.task_id, SUM(CASE m.kind WHEN 'hold' THEN m.amount_micro ELSE -m.amount_micro END) AS net
+    FROM economy_project_account_movements m
+   WHERE m.kind IN ('hold', 'hold_release')
+   GROUP BY m.task_id`;
+
+async function lockAccount(db) {
+  await db.query('SELECT pg_advisory_xact_lock($1, $2)', ACCOUNT_LOCK);
+}
+
+// → [{ task_id, amount_micro }] for each hold released.
+async function releaseSettledHolds(db) {
+  const { rows } = await db.query(
+    `INSERT INTO economy_project_account_movements (kind, direction, amount_micro, task_id, note)
+     SELECT 'hold_release', 'none', h.net, h.task_id, 'The task is no longer being worked and owes nothing, so its hold is let go.'
+       FROM (${NET_HOLDS_SQL}) h JOIN tasks t ON t.id = h.task_id
+      WHERE h.net > 0 AND NOT ${LIVE_HOLD_SQL}
+     RETURNING task_id, amount_micro`, [HELD_STATUSES]);
+  return rows.map((r) => ({ task_id: String(r.task_id), amount_micro: Number(r.amount_micro) }));
+}
+
+async function readAvailable(db, { exceptTaskId = null } = {}) {
+  const { rows: [r] } = await db.query(
+    `SELECT
+       (SELECT COALESCE(SUM(CASE direction WHEN 'in' THEN amount_micro WHEN 'out' THEN -amount_micro ELSE 0 END), 0)
+          FROM economy_project_account_movements) AS balance_micro,
+       (SELECT COALESCE(SUM(h.net), 0) FROM (${NET_HOLDS_SQL}) h JOIN tasks t ON t.id = h.task_id
+         WHERE h.net > 0 AND ${LIVE_HOLD_SQL} AND ($2::bigint IS NULL OR h.task_id <> $2::bigint)) AS held_micro`,
+    [HELD_STATUSES, exceptTaskId == null ? null : String(exceptTaskId)]);
+  const balance = Number(r.balance_micro);
+  const held = Number(r.held_micro);
+  return { balance_micro: balance, held_micro: held, available_micro: balance - held };
+}
+
+// → Map<task id, micro-dollars held> for every hold readAvailable counts.
+async function readLiveHolds(db) {
+  const { rows } = await db.query(
+    `SELECT h.task_id, h.net FROM (${NET_HOLDS_SQL}) h JOIN tasks t ON t.id = h.task_id
+      WHERE h.net > 0 AND ${LIVE_HOLD_SQL}`, [HELD_STATUSES]);
+  return new Map(rows.map((r) => [String(r.task_id), Number(r.net)]));
+}
+
+module.exports = {
+  MovementRefusal, checkMovement, recordMovement, accountTotals, shapeAccount, readAccount,
+  HELD_STATUSES, lockAccount, releaseSettledHolds, readAvailable, readLiveHolds,
+};

package/modules/economy/routes/balances.js

@@ -0,0 +1,79 @@
+// modules/economy/routes/balances.js — a user's balance, the project's balance, and the
+// two payments a person may make on their own instruction (task 1004907, goal 1000092 N3;
+// ADR 0385, ADR 0397). No platform fee on either.
+//
+//   GET  /balances/me            → { connected, balance_micro|null, holds_money:false, transfers:[…] }
+//   GET  /balances/project       → { balance_micro|null, holds_money:false }  (the figure only)
+//   POST /balances/fund-project  { amount_cents, instruction_id }
+//   POST /balances/pay           { to_builder_id, amount_cents, instruction_id, note? }
+//        → { transfer_id, status: 'sent'|'held'|'failed', platform_fee_cents: 0, … }
+//
+// Balances are the processor's figures; `../user-balances.js` owns the SQL and the order.
+// A payment needs the payer's own signed-in WEB session: a CLI token, an agent or a
+// machine principal never moves a person's money (the payout route's rule).
+//
+// MODULE BOUNDARY: reaches core only through `../../../src/module-api`.
+
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { TransferRefusal, readMyBalance, readProjectBalance, transfer } = require('../user-balances');
+
+const log = api.logger('economy');
+
+// The person themself, in a browser, signed in: never a CLI token, an agent or a machine.
+function personalWebSession(req) {
+  const s = req.gdsSession;
+  const b = req.builder;
+  return Boolean(b && s && !b.system_role && s.source === 'web' && s.session_id !== undefined && s.session_id !== null);
+}
+
+module.exports = function buildBalancesRouter({ processor = null } = {}) {
+  const router = express.Router();
+
+  const fail = (res, err, what) => {
+    if (err instanceof TransferRefusal) return res.fail(err.code, { status: err.status, message: err.message });
+    log.error({ err: err.message }, `${what} failed`);
+    if (!res.headersSent) res.fail('balance_failed', { status: 500, message: 'internal error' });
+  };
+
+  // rank: any-builder — the signed-in person's own balance and their own payments.
+  router.get('/balances/me', api.requireBuilder, async (req, res) => {
+    try {
+      const out = await readMyBalance(api.pool, req.builder.id, { processor, limit: req.query.limit, log });
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) { fail(res, err, 'GET /balances/me'); }
+  });
+
+  // rank: any-builder — the project's balance figure, so a member can see whether it needs funding.
+  router.get('/balances/project', api.requireBuilder, async (req, res) => {
+    try {
+      const out = await readProjectBalance({ processor, log });
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) { fail(res, err, 'GET /balances/project'); }
+  });
+
+  const pay = (kind) => async (req, res) => {
+    if (!personalWebSession(req)) {
+      return res.fail('personal_session_required', { status: 403, message: 'A payment is made by the person themself, signed in on the web.' });
+    }
+    const b = req.body || {};
+    try {
+      const out = await transfer({
+        kind, fromBuilderId: String(req.builder.id), toBuilderId: b.to_builder_id,
+        amountCents: b.amount_cents, instructionId: b.instruction_id, note: b.note,
+      }, { pool: api.pool, processor });
+      res.status(out.status === 'sent' ? 200 : 202).json(out);
+    } catch (err) { fail(res, err, `POST /balances/${kind}`); }
+  };
+
+  // rank: any-builder — a person funds this project from their own account, on their own web session.
+  router.post('/balances/fund-project', api.requireBuilder, pay('fund_project'));
+  // rank: any-builder — a person pays another member of this project from their own account.
+  router.post('/balances/pay', api.requireBuilder, pay('pay_user'));
+
+  return router;
+};

package/modules/economy/routes/project-account.js

@@ -15,7 +15,10 @@
 
 const express = require('express');
 const api = require('../../../src/module-api');
-const { readAccount, recordMovement } = require('../project-account');
+const { readAccount, recordMovement, lockAccount, releaseSettledHolds, readAvailable } = require('../project-account');
+const { readOutflow } = require('../outflow');
+const { readLedgerChecks } = require('../ledger-check');
+const { memberAccount } = require('../user-balances');
 
 const log = api.logger('economy');
 
@@ -23,8 +26,13 @@ const log = api.logger('economy');
 // books its `payout` movement through this, inside its own transaction, without importing the
 // module. Registered here for the reason routes/reward.js gives: the loader runs this factory in
 // the live server and whenever a test rebuilds the router. hasProvider-guarded for re-runs.
+// The lifecycle's funding wall (task 1003185, ADR 0386) uses the other three, the same way.
+// Core's cash-out (task 1004911) reads a person's processor account in this project through
+// memberAccount, so the account a withdrawal pays from is never one the request names.
 function registerSeams() {
-  if (!api.hasProvider('economy.account')) api.registerProvider('economy.account', { recordMovement });
+  if (!api.hasProvider('economy.account')) {
+    api.registerProvider('economy.account', { recordMovement, lockAccount, releaseSettledHolds, readAvailable, memberAccount });
+  }
 }
 
 module.exports = function buildProjectAccountRouter({ processor = null } = {}) {
@@ -45,5 +53,35 @@ module.exports = function buildProjectAccountRouter({ processor = null } = {}) {
     }
   });
 
+  // GET /project-account/outflow?months=12 — where the money went (task 1003184, criterion
+  // money-outflow-visible): spend and money out per month, per-builder totals, and what is
+  // committed but not yet paid beside the balance left after it. Same gate as the account:
+  // who was paid what is the project's own money. Read only, summed from existing records.
+  router.get('/project-account/outflow', api.requireBuilder, api.requirePermission('payout.approve'), async (req, res) => {
+    try {
+      const out = await readOutflow(api.pool, { months: req.query.months });
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) {
+      log.error({ err: err.message }, 'GET /project-account/outflow failed');
+      if (!res.headersSent) res.fail('project_outflow_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /project-account/ledger-checks?limit=10 — the daily check of our record against the
+  // processor's (task 1004912, ADR 0397 D7): each check's outcome and, on a difference, the
+  // amounts and processor references. Same gate as the account; the alarm it raises is a
+  // public blocker with no numbers in it, so the numbers are read here.
+  router.get('/project-account/ledger-checks', api.requireBuilder, api.requirePermission('payout.approve'), async (req, res) => {
+    try {
+      const out = await readLedgerChecks(api.pool, { limit: req.query.limit });
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) {
+      log.error({ err: err.message }, 'GET /project-account/ledger-checks failed');
+      if (!res.headersSent) res.fail('ledger_checks_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   return router;
 };