@bongos/core 1.24.22 → 1.24.24

package/modules/economy/user-balances.js

@@ -0,0 +1,308 @@
+'use strict';
+
+// modules/economy/user-balances.js — A USER'S BALANCE, AND THE PAYMENTS THEY MAKE ON THEIR
+// OWN INSTRUCTION, IN THIS PROJECT ONLY (task 1004907, goal 1000092 N3; ADR 0385, ADR 0387,
+// ADR 0397 D2/D3).
+//
+// WHY. A builder who is paid needs to see what they have, fund the project they work on,
+// and pay a teammate, without Bongos ever holding the money or taking a cut.
+//
+// THE PRODUCT GATE (legal framework, by Article only; a product constraint, not advice).
+//   actor     the paying person, on their own signed-in web session; never a CLI, an agent
+//             or a standing rule (the route refuses every other session).
+//   custody   the processor. Each user's money is in their own connected account, the
+//             project's in the project's (ADR 0397 D2). Bongos holds none and nets none:
+//             no balance is ever summed from these tables, a balance is the processor's figure.
+//   words     balance, payment, transfer. Never deposit, wallet, interest, return or yield.
+//   control   one instruction moves one amount once. Nothing repeats on its own.
+//   advice    none is given.
+//   primitive the Stripe Connect transfer between connected accounts, and the connected
+//             account balance read (ADR 0397 D3 table). Only the processor adapter names
+//             Stripe; here it is a port.
+//
+// THE PROCESSOR PORT (all optional; with none connected nothing moves and every
+// instruction is recorded and held `no_processor`):
+//   balanceMicro()                               the project's own account balance
+//   memberBalanceMicro(accountRef)               one member's account balance
+//   confirmMemberAccount({ accountRef, builderId }) → true only for an account THIS
+//                                                project's connection opened for that person
+//   memberTransfer({ idempotencyKey, amountCents, currency, fromAccount, toAccount, toProject })
+//                                                → { ref }; toProject:true means this project's account
+//
+// ISOLATION. Each project has its own database (ADR 0100) and its own processor port. Every
+// account a transfer names is read from this project's economy_member_accounts, never from
+// the request, and a link is written only when this project's port confirms it. So a person
+// cannot point a payment at, or read, an account another project opened.
+//
+// THE ORDER (the builder-payouts idiom): refuse what is malformed; record the instruction,
+// once per instruction id; hold it if the processor is missing; otherwise send it under a
+// lock with an idempotency key from the instruction's id, booking the `sent` attempt (and,
+// for funding, the project-account `funding` movement) in ONE transaction. A failure is a
+// recorded attempt with its reason and is never re-sent on its own (ADR 0397 D7).
+
+const { recordMovement } = require('./project-account');
+
+const LOCK_SPACE = 1004907;
+const PROCESSOR_TIMEOUT_MS = 15_000;
+const READ_TIMEOUT_MS = 5000;
+const MICRO_PER_CENT = 10_000;
+const CURRENCY = 'USD';
+const NOTE_MAX = 300;
+const REASON_MAX = 300;
+const INSTRUCTION_RE = /^[A-Za-z0-9_-]{8,80}$/;
+const ACCOUNT_RE = /^[A-Za-z0-9_.:-]{3,200}$/;
+
+const isId = (v) => (typeof v === 'number' && Number.isSafeInteger(v) && v > 0) || (typeof v === 'string' && /^[1-9][0-9]{0,18}$/.test(v));
+const clip = (s) => String(s || '').replace(/\s+/g, ' ').trim().slice(0, REASON_MAX) || 'unknown';
+const idempotencyKey = (transferId) => `bongos-user-transfer-${transferId}`;
+
+class TransferRefusal extends Error {
+  constructor(code, message, status = 400) { super(message); this.code = code; this.status = status; }
+}
+
+// Plain words for each reason an instruction waits.
+const HELD_WORDS = Object.freeze({
+  no_processor: 'No payment processor is connected to this project yet, so nothing was sent.',
+});
+
+function withTimeout(promise, ms) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, rej) => { timer = setTimeout(() => rej(Object.assign(new Error('the processor did not answer in time'), { code: 'timeout' })), ms); }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+// A transaction on a checked-out client when the pool can give one; a single connection
+// (a test stand-in, or a caller's client) runs the statements as they are.
+async function inTx(pool, fn) {
+  if (typeof pool.connect !== 'function' || typeof pool.release === 'function') return fn(pool);
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    const out = await fn(client);
+    await client.query('COMMIT');
+    return out;
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// ── accounts ───────────────────────────────────────────────────────────────
+
+async function memberAccount(db, builderId) {
+  const { rows } = await db.query(
+    'SELECT processor_account FROM economy_member_accounts WHERE builder_id = $1 ORDER BY id DESC LIMIT 1', [builderId]);
+  return rows[0] ? rows[0].processor_account : null;
+}
+
+// linkMemberAccount(db, { builderId, accountRef, actorId }, { processor }) — called by the
+// processor adapter when a person finishes the processor's own onboarding. There is no
+// route that takes an account reference typed by a person: that is how one project's
+// account would be pointed at another's.
+async function linkMemberAccount(db, { builderId, accountRef, actorId = null }, { processor = null } = {}) {
+  if (!isId(builderId)) throw new TransferRefusal('bad_builder_id', 'builder_id must be a number.');
+  const ref = typeof accountRef === 'string' ? accountRef.trim() : '';
+  if (!ACCOUNT_RE.test(ref)) throw new TransferRefusal('bad_account', 'That is not a processor account reference.');
+  if (!processor || typeof processor.confirmMemberAccount !== 'function') {
+    throw new TransferRefusal('no_processor', HELD_WORDS.no_processor, 409);
+  }
+  const confirmed = await withTimeout(Promise.resolve(processor.confirmMemberAccount({ accountRef: ref, builderId: String(builderId) })), READ_TIMEOUT_MS);
+  if (confirmed !== true) {
+    throw new TransferRefusal('not_this_projects_account', "This project's processor connection did not open that account for this person.", 403);
+  }
+  const owner = await db.query('SELECT builder_id FROM economy_member_accounts WHERE processor_account = $1 LIMIT 1', [ref]);
+  if (owner.rows[0]) {
+    if (String(owner.rows[0].builder_id) !== String(builderId)) {
+      throw new TransferRefusal('account_belongs_to_someone_else', 'That account already belongs to someone else in this project.', 409);
+    }
+    if (await memberAccount(db, builderId) === ref) return { linked: false, account: ref };
+    throw new TransferRefusal('account_already_used', 'That account was linked to this person before and replaced; it cannot be linked again.', 409);
+  }
+  await db.query('INSERT INTO economy_member_accounts (builder_id, processor_account, linked_by) VALUES ($1,$2,$3)',
+    [builderId, ref, isId(actorId) ? actorId : null]);
+  return { linked: true, account: ref };
+}
+
+// ── reads: the processor's figure, never a sum of ours ─────────────────────
+
+async function readFigure(fn, log, what) {
+  try {
+    const v = Number(await withTimeout(Promise.resolve(fn()), READ_TIMEOUT_MS));
+    if (!Number.isSafeInteger(v)) throw new Error('not a whole number');
+    return { micro: v, failed: false };
+  } catch (e) {
+    if (log) log.error({ err: e.message }, `user balances: ${what} unreadable`);
+    return { micro: null, failed: true };
+  }
+}
+
+const TRANSFER_SQL = `
+  SELECT t.id, t.kind, t.from_builder_id, fb.display_name AS from_name, t.to_builder_id, tb.display_name AS to_name,
+         t.amount_cents, t.currency, t.platform_fee_cents, t.note, t.created_at,
+         s.processor_ref AS sent_ref, l.outcome AS last_outcome, l.reason AS last_reason
+    FROM economy_user_transfers t
+    LEFT JOIN builders fb ON fb.id = t.from_builder_id
+    LEFT JOIN builders tb ON tb.id = t.to_builder_id
+    LEFT JOIN economy_user_transfer_attempts s ON s.transfer_id = t.id AND s.outcome = 'sent'
+    LEFT JOIN LATERAL (
+      SELECT outcome, reason FROM economy_user_transfer_attempts a
+       WHERE a.transfer_id = t.id ORDER BY a.id DESC LIMIT 1) l ON true`;
+
+function shapeTransfer(r, viewerId) {
+  const status = r.sent_ref ? 'sent' : (r.last_outcome === 'failed' ? 'failed' : 'held');
+  return {
+    id: String(r.id), kind: r.kind,
+    direction: String(r.from_builder_id) === String(viewerId) ? 'out' : 'in',
+    from_builder_id: String(r.from_builder_id), from_name: r.from_name,
+    to_builder_id: r.to_builder_id === null || r.to_builder_id === undefined ? null : String(r.to_builder_id), to_name: r.to_name || null,
+    amount_cents: Number(r.amount_cents), currency: r.currency, platform_fee_cents: Number(r.platform_fee_cents),
+    note: r.note, created_at: r.created_at, status, processor_ref: r.sent_ref || null,
+    reason: status === 'sent' ? null : (r.last_reason || null),
+    words: status === 'held' ? (HELD_WORDS[r.last_reason] || null) : null,
+  };
+}
+
+// readMyBalance(db, builderId, { processor, limit, log }) — the person's balance as the
+// processor reports it, and the payments they made or received in this project.
+async function readMyBalance(db, builderId, { processor = null, limit = 20, log = null } = {}) {
+  const lim = Math.min(Math.max(parseInt(limit, 10) || 20, 1), 100);
+  const account = await memberAccount(db, builderId);
+  const recent = await db.query(
+    `${TRANSFER_SQL} WHERE t.from_builder_id = $1 OR t.to_builder_id = $1 ORDER BY t.id DESC LIMIT $2`, [builderId, lim]);
+  const out = {
+    unit: 'micro_usd', holds_money: false, source: 'processor',
+    connected: Boolean(account), balance_micro: null,
+    transfers: recent.rows.map((r) => shapeTransfer(r, builderId)),
+  };
+  if (account && processor && typeof processor.memberBalanceMicro === 'function') {
+    const read = await readFigure(() => processor.memberBalanceMicro(account), log, 'member balance');
+    out.balance_micro = read.micro;
+    if (read.failed) out.processor_error = 'Your balance could not be read from the processor just now.';
+  }
+  return out;
+}
+
+// readProjectBalance({ processor, log }) — the project's balance as the processor reports
+// it. Only the figure: who was paid what stays on the owner's GET /project-account.
+async function readProjectBalance({ processor = null, log = null } = {}) {
+  const out = { unit: 'micro_usd', holds_money: false, source: 'processor', balance_micro: null };
+  if (processor && typeof processor.balanceMicro === 'function') {
+    const read = await readFigure(() => processor.balanceMicro(), log, 'project balance');
+    out.balance_micro = read.micro;
+    if (read.failed) out.processor_error = "The project's balance could not be read from the processor just now.";
+  }
+  return out;
+}
+
+// ── the instruction ────────────────────────────────────────────────────────
+
+function checkInstruction(i) {
+  if (i.kind !== 'fund_project' && i.kind !== 'pay_user') throw new TransferRefusal('bad_kind', 'A transfer either funds the project or pays a person.');
+  if (!isId(i.fromBuilderId)) throw new TransferRefusal('no_actor', 'A transfer is made by a signed-in person.', 403);
+  const amount = Number(i.amountCents);
+  if (!Number.isSafeInteger(amount) || amount <= 0) throw new TransferRefusal('bad_amount', 'amount_cents must be a positive whole number of cents.');
+  if (typeof i.instructionId !== 'string' || !INSTRUCTION_RE.test(i.instructionId)) {
+    throw new TransferRefusal('bad_instruction_id', 'instruction_id must be 8 to 80 letters, digits, dashes or underscores, one per payment.');
+  }
+  const note = String(i.note || '').trim();
+  if (note.length > NOTE_MAX) throw new TransferRefusal('note_too_long', `note is at most ${NOTE_MAX} characters`);
+  if (i.kind === 'pay_user') {
+    if (!isId(i.toBuilderId)) throw new TransferRefusal('bad_recipient', 'to_builder_id must be a number.');
+    if (String(i.toBuilderId) === String(i.fromBuilderId)) throw new TransferRefusal('self_payment', 'You cannot pay yourself.');
+  }
+  return { amount, note };
+}
+
+async function sentAttempt(db, transferId) {
+  const { rows } = await db.query(
+    "SELECT processor_ref FROM economy_user_transfer_attempts WHERE transfer_id = $1 AND outcome = 'sent'", [transferId]);
+  return rows[0] || null;
+}
+
+async function insertAttempt(db, transferId, { outcome, processorRef = null, reason = null }) {
+  await db.query('INSERT INTO economy_user_transfer_attempts (transfer_id, outcome, processor_ref, reason) VALUES ($1,$2,$3,$4)',
+    [transferId, outcome, processorRef, reason === null ? null : clip(reason)]);
+}
+
+// Record the instruction once. A repeat of the same instruction id returns the row already
+// there, and is refused if it now asks for something different.
+async function recordInstruction(db, row) {
+  await db.query(
+    `INSERT INTO economy_user_transfers (kind, from_builder_id, to_builder_id, from_account, to_account, amount_cents, currency, instruction_id, note)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9) ON CONFLICT (from_builder_id, instruction_id) DO NOTHING`,
+    [row.kind, row.from_builder_id, row.to_builder_id, row.from_account, row.to_account, row.amount_cents, CURRENCY, row.instruction_id, row.note]);
+  const { rows } = await db.query(
+    'SELECT * FROM economy_user_transfers WHERE from_builder_id = $1 AND instruction_id = $2', [row.from_builder_id, row.instruction_id]);
+  const had = rows[0];
+  const same = had && had.kind === row.kind && Number(had.amount_cents) === row.amount_cents
+    && String(had.to_builder_id ?? '') === String(row.to_builder_id ?? '');
+  if (!same) throw new TransferRefusal('instruction_reused', 'That instruction id was already used for a different payment.', 409);
+  return had;
+}
+
+// transfer(input, { pool, processor }) — fund the project or pay a person, on the payer's
+// own instruction. input: { kind, fromBuilderId, toBuilderId?, amountCents, instructionId, note? }.
+// Throws TransferRefusal only BEFORE the instruction is recorded; afterwards every outcome is
+// a returned status: 'sent' | 'held' | 'failed'.
+async function transfer(input, { pool, processor = null, timeoutMs = PROCESSOR_TIMEOUT_MS } = {}) {
+  const i = input || {};
+  const { amount, note } = checkInstruction(i);
+
+  const fromAccount = await memberAccount(pool, i.fromBuilderId);
+  if (!fromAccount) throw new TransferRefusal('no_account', 'You have no processor account in this project yet, so there is nothing to pay from.', 409);
+  let toAccount = null;
+  if (i.kind === 'pay_user') {
+    // only a person with an account linked in THIS project can be paid
+    toAccount = await memberAccount(pool, i.toBuilderId);
+    if (!toAccount) throw new TransferRefusal('recipient_has_no_account', 'That person has no processor account in this project, so they cannot be paid here.', 409);
+  }
+
+  const row = await recordInstruction(pool, {
+    kind: i.kind, from_builder_id: String(i.fromBuilderId), to_builder_id: i.kind === 'pay_user' ? String(i.toBuilderId) : null,
+    from_account: fromAccount, to_account: toAccount, amount_cents: amount, instruction_id: i.instructionId, note,
+  });
+  const transferId = String(row.id);
+  const base = { transfer_id: transferId, kind: row.kind, amount_cents: Number(row.amount_cents), platform_fee_cents: 0 };
+
+  const paid = await sentAttempt(pool, transferId);
+  if (paid) return { ...base, status: 'sent', already: true, processor_ref: paid.processor_ref };
+  if (!processor || typeof processor.memberTransfer !== 'function') {
+    await insertAttempt(pool, transferId, { outcome: 'held', reason: 'no_processor' });
+    return { ...base, status: 'held', reason: 'no_processor', words: HELD_WORDS.no_processor };
+  }
+
+  return inTx(pool, async (db) => {
+    await db.query('SELECT pg_advisory_xact_lock($1::int, hashtext($2::text))', [LOCK_SPACE, transferId]);
+    const already = await sentAttempt(db, transferId);
+    if (already) return { ...base, status: 'sent', already: true, processor_ref: already.processor_ref };
+    let ref;
+    try {
+      // the accounts are the ones recorded with the instruction, never re-read from the request
+      const out = await withTimeout(Promise.resolve(processor.memberTransfer({
+        idempotencyKey: idempotencyKey(transferId),
+        amountCents: Number(row.amount_cents), currency: CURRENCY,
+        fromAccount: row.from_account, toAccount: row.to_account, toProject: row.kind === 'fund_project',
+      })), timeoutMs);
+      ref = out && typeof out.ref === 'string' && out.ref.trim() ? out.ref.trim() : null;
+      if (!ref) throw Object.assign(new Error('the processor gave no transfer reference'), { code: 'no_reference' });
+    } catch (err) {
+      const reason = clip(`${err && err.code ? err.code + ': ' : ''}${err && err.message ? err.message : 'transfer failed'}`);
+      await insertAttempt(db, transferId, { outcome: 'failed', reason });
+      return { ...base, status: 'failed', reason };
+    }
+    await insertAttempt(db, transferId, { outcome: 'sent', processorRef: ref });
+    if (row.kind === 'fund_project') {
+      await recordMovement(db, {
+        kind: 'funding', amountMicro: Number(row.amount_cents) * MICRO_PER_CENT,
+        builderId: row.from_builder_id, processorRef: ref, note: `funded by a member (transfer ${transferId})`,
+      });
+    }
+    return { ...base, status: 'sent', already: false, processor_ref: ref };
+  });
+}
+
+module.exports = { TransferRefusal, HELD_WORDS, memberAccount, linkMemberAccount, readMyBalance, readProjectBalance, transfer };

package/modules/government/decision-rules.js

@@ -68,6 +68,7 @@ const AREAS = Object.freeze([
       'PATCH /project-settings/ship-mode',
       'PATCH /project-settings/tweak-autopickup',
       'PATCH /project-settings/pay-terms', // task 1004990: the project's standing pay terms
+      'PATCH /project-settings/funding-wall', // task 1003185: the project's funding rule (ADR 0386)
       'PATCH /work-categories/:id',
       // task 1004941: the owner approving a Market Watch proposal (a passed
       // matter approves it through the market_watch_proposal act instead)

package/modules/hall-ui/public/project-settings.css

@@ -246,3 +246,21 @@
   cursor: pointer;
 }
 .ps-ship__choice input { margin-top: 4px; flex: 0 0 auto; }
+
+/* Where the money went (task 1003184). Four lead figures that wrap two-by-two on a
+   phone; the tables scroll inside their own strip, never the page (hall-ui/CLAUDE.md). */
+.ps-money__figs {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+  gap: 12px;
+  margin-top: 6px;
+}
+.ps-money__fig { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+.ps-money__label { font-size: 12px; color: var(--ink-soft); }
+.ps-money__value { font-size: 20px; font-variant-numeric: tabular-nums; }
+.ps-money__note { font-size: 12px; color: var(--ink-soft); }
+.ps-money__fig--warn .ps-money__value { color: var(--warn); }
+.ps-money__fig--bad .ps-money__value { color: var(--danger); }
+.ps-money__h { margin: 20px 0 8px; font-size: 14px; }
+.ps-money__wrap { overflow-x: auto; }
+.ps-money__wrap .ledger td { font-variant-numeric: tabular-nums; }

package/modules/hall-ui/public/project-settings.html

@@ -10,7 +10,7 @@
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link rel="stylesheet" href="/builders/style.css?v=2026-07-02-shell1">
   <link rel="stylesheet" href="/builders/oversight.css">
-  <link rel="stylesheet" href="/builders/project-settings.css">
+  <link rel="stylesheet" href="/builders/project-settings.css?v=2026-11-02-outflow">
 </head>
 <body data-page="project-settings" data-page-title="Project settings">
 
@@ -48,6 +48,19 @@
                thing this page exists to end. -->
           <div id="ps-rows"><span class="kit-skel"></span></div>
         </section>
+        <!-- Where the money went (task 1003184, criterion money-outflow-visible). Hidden
+             unless GET /project-account/outflow answers — it is the payout authority's
+             read (payout.approve, the owner), so every other reader of this page never
+             sees an empty panel. Written by project-settings.js; every figure is the
+             server's, summed from records that already exist. -->
+        <section class="scroll" id="ps-money" aria-labelledby="ps-money-h" hidden>
+          <h2 class="scroll__h" id="ps-money-h">Where the money went</h2>
+          <p class="scroll__lede">
+            What this project has spent, what each builder has been paid, and what it has
+            promised but not paid yet. A balance only means something after those promises.
+          </p>
+          <div id="ps-money-body"></div>
+        </section>
         <!-- Danger zone (task 1004570): where this project's OWNER takes it offline or
              disconnects it. Both controls live on the platform that hosts the project,
              so this only links there. Hidden unless GET /project/manage-link answers
@@ -76,6 +89,6 @@
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <script src="/builders/hall-kit.js"></script>
-<script src="/builders/project-settings.js?v=2026-10-29-tweak-cap"></script>
+<script src="/builders/project-settings.js?v=2026-11-02-outflow"></script>
 </body>
 </html>

package/modules/hall-ui/public/project-settings.js

@@ -417,6 +417,148 @@
     $('ps-danger').hidden = false;
   }
 
+  // ---- where the money went (task 1003184, criterion money-outflow-visible) --------
+  //
+  // The owner's outflow view. The server sums every figure (modules/economy/outflow.js);
+  // this only draws it. It leads with what is left AFTER what is owed, because a balance
+  // that looks healthy while it owes three payouts is the trap the view exists to show.
+  // Any outcome but a 200 leaves the section hidden: the read is the payout authority's,
+  // and everyone else on this page has nothing to see here, not an error.
+
+  const money = (micro) => {
+    const usd = Number(micro || 0) / 1e6;
+    const abs = Math.abs(usd).toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+    return `${usd < 0 ? '−' : ''}$${abs}`;
+  };
+  const monthLabel = (ym) => {
+    const [y, m] = String(ym).split('-').map(Number);
+    return new Date(Date.UTC(y, m - 1, 1)).toLocaleDateString(undefined, { month: 'short', year: 'numeric', timeZone: 'UTC' });
+  };
+  const dayLabel = (iso) => (iso ? new Date(iso).toLocaleDateString() : '');
+
+  function moneyFiguresHtml(out) {
+    const c = out.committed;
+    const after = out.balance.after_commitments_micro;
+    const fig = (label, value, note, tone) => `<div class="ps-money__fig${tone ? ` ps-money__fig--${tone}` : ''}">
+        <span class="ps-money__label">${escapeHtml(label)}</span>
+        <strong class="ps-money__value">${escapeHtml(value)}</strong>
+        <span class="ps-money__note">${escapeHtml(note)}</span>
+      </div>`;
+    const owedNote = c.owed_count === 1 ? '1 payment' : `${c.owed_count} payments`;
+    const apprNote = c.approved_count === 1 ? '1 approval' : `${c.approved_count} approvals`;
+    return `<div class="ps-money__figs">
+      ${fig('Balance', money(out.balance.available_micro), c.held_micro ? `after ${money(c.held_micro)} held` : 'on our record')}
+      ${fig('Owed but not paid', money(c.owed_micro), owedNote, c.owed_micro ? 'warn' : '')}
+      ${fig('Approved, not started', money(c.approved_micro), apprNote, c.approved_micro ? 'warn' : '')}
+      ${fig('Left after all of that', money(after), after < 0 ? 'the project owes more than it holds' : 'what is really free', after < 0 ? 'bad' : '')}
+    </div>${c.other_currency_count ? `<p class="ps-prov">${c.other_currency_count} more in a currency other than US dollars, not added in.</p>` : ''}`;
+  }
+
+  // The payout's latest try in words. A reason is either the processor's own sentence, shown
+  // as it is, or one of core's held codes (builder-payouts.js HELD_WORDS). The codes an owner
+  // can act on get a short phrase here; any other code is left out rather than shown as a slug.
+  const TRY_WORDS = { held: 'Waiting', failed: 'Did not go through' };
+  const REASON_WORDS = {
+    no_processor: 'no payment processor connected yet',
+    recipient_gated: 'this person cannot be paid right now',
+    guardian_cosign_missing: 'a guardian has not co-signed yet',
+    currency_not_supported: 'not in US dollars',
+  };
+  function lastTryWords(r) {
+    if (!r.last_outcome) return 'Not tried yet';
+    const reason = String(r.last_reason || '');
+    const why = REASON_WORDS[reason] || (/^[a-z_]+$/.test(reason) ? '' : reason);
+    return `${TRY_WORDS[r.last_outcome] || r.last_outcome}${why ? ` — ${why}` : ''}`;
+  }
+
+  function owedHtml(out) {
+    const rows = out.committed.owed;
+    if (!rows.length) return '';
+    return `<h3 class="ps-money__h">Owed but not paid</h3>
+      <div class="ps-money__wrap"><table class="ledger">
+        <thead><tr><th>Builder</th><th>Task</th><th>Amount</th><th>Owed since</th><th>Last try</th></tr></thead>
+        <tbody>${rows.map((r) => `<tr>
+          <td>${escapeHtml(r.builder_name || `builder ${r.builder_id}`)}</td>
+          <td><a href="/builders/task/${encodeURIComponent(r.task_id)}">${escapeHtml(r.task_title || `task ${r.task_id}`)}</a></td>
+          <td>${escapeHtml(money(r.amount_micro))}</td>
+          <td>${escapeHtml(dayLabel(r.since))}</td>
+          <td>${escapeHtml(lastTryWords(r))}</td>
+        </tr>`).join('')}</tbody>
+      </table></div>`;
+  }
+
+  function buildersHtml(out) {
+    const rows = out.by_builder;
+    if (!rows.length) return '';
+    return `<h3 class="ps-money__h">By builder</h3>
+      <div class="ps-money__wrap"><table class="ledger">
+        <thead><tr><th>Builder</th><th>Spent</th><th>Paid</th><th>Owed</th><th>Approved</th></tr></thead>
+        <tbody>${rows.map((b) => `<tr>
+          <td>${escapeHtml(b.builder_name || `builder ${b.builder_id}`)}</td>
+          <td>${escapeHtml(money(b.spend_micro))}</td>
+          <td>${escapeHtml(money(b.paid_micro))}</td>
+          <td>${escapeHtml(money(b.owed_micro))}</td>
+          <td>${escapeHtml(money(b.approved_micro))}</td>
+        </tr>`).join('')}</tbody>
+      </table></div>
+      <p class="ps-prov">Spent is the recorded cost of each builder’s sessions (API, compute). Paid, owed and approved are payouts.</p>`;
+  }
+
+  function burnHtml(out) {
+    const months = out.burn.months;
+    if (!months.some((m) => m.total_micro > 0)) return '';
+    const bars = window.OTBKit.barSeriesHtml(
+      months.map((m) => ({ label: monthLabel(m.month), value: m.total_micro, valueLabel: money(m.total_micro) })),
+      { list: true, ariaLabel: 'Money out by month', valueWidth: '96px' });
+    return `<h3 class="ps-money__h">Money out, by month</h3>${bars}
+      <p class="ps-prov">Each month is recorded spend (${escapeHtml(money(months.reduce((s, m) => s + m.spend_micro, 0)))} over these ${months.length} months) plus payouts and fees out of the project account. Read from the cost log and the account’s own record.</p>`;
+  }
+
+  // The daily check of our record against the processor's (task 1004912). The newest check
+  // in words, and on a difference each one with both amounts. The blocker it raises is public
+  // and carries no numbers, so this is where the owner reads them.
+  const CHECK_WORDS = {
+    clean: 'Our records and the payment processor’s agree.',
+    drift: 'Our records and the payment processor’s differ.',
+    unchecked: 'Not checked: no payment processor is connected yet, so there is nothing to compare with.',
+    error: 'Could not check: the payment processor could not be read.',
+  };
+  function ledgerCheckHtml(out) {
+    const c = out && out.checks && out.checks[0];
+    if (!c) return '';
+    const words = out.kind_words || {};
+    const amt = (v) => (v === null || v === undefined ? '—' : money(v));
+    const rows = (c.findings || []).map((f) => `<tr>
+          <td>${escapeHtml(words[f.kind] || f.kind)}</td>
+          <td>${escapeHtml(f.ref || 'the project balance')}</td>
+          <td>${escapeHtml(amt(f.ours_micro))}</td>
+          <td>${escapeHtml(amt(f.theirs_micro))}</td>
+        </tr>`).join('');
+    return `<h3 class="ps-money__h">Daily check against the payment processor</h3>
+      <p class="ps-prov">${escapeHtml(dayLabel(c.created_at))}: ${escapeHtml(CHECK_WORDS[c.outcome] || c.outcome)}${c.outcome === 'clean' || c.outcome === 'drift' ? ` ${c.refs_compared} ${c.refs_compared === 1 ? 'movement' : 'movements'} compared.` : ''}</p>
+      ${rows ? `<div class="ps-money__wrap"><table class="ledger">
+        <thead><tr><th>Difference</th><th>Reference</th><th>Our record</th><th>Processor</th></tr></thead>
+        <tbody>${rows}</tbody>
+      </table></div>` : ''}`;
+  }
+
+  async function loadMoney() {
+    let out = null;
+    try {
+      const res = await api.request('GET', `${API}/project-account/outflow`);
+      out = res.ok ? res.data : null;
+    } catch (_) { out = null; }
+    if (!out || !out.balance || !out.committed) return;
+    let checks = null;
+    try {
+      const res = await api.request('GET', `${API}/project-account/ledger-checks?limit=1`);
+      checks = res.ok ? res.data : null;
+    } catch (_) { checks = null; }
+    $('ps-money-body').innerHTML = moneyFiguresHtml(out) + ledgerCheckHtml(checks) + owedHtml(out) + buildersHtml(out) + burnHtml(out);
+    $('ps-money').hidden = false;
+  }
+
   load();
+  loadMoney();
   loadDanger();
 })();

package/modules/ideas/module.json

@@ -23,7 +23,8 @@
   "provides": [
     "ideas.capture",
     "ideas.descent",
-    "ideas.ideatorStats"
+    "ideas.ideatorStats",
+    "ideas.fileBlocker"
   ],
   "consumes": [
     "reward",

package/modules/ideas/routes/blockers.js

@@ -79,8 +79,33 @@ function askRequired(req, body) {
   return !TEMPLATED_SOURCES.includes(body.source);
 }
 
+// The `ideas.fileBlocker` port's writer: POST /blockers' shape and length rules, for a caller
+// inside the server, which has no request to validate. A refusal throws with code BAD_BLOCKER.
+function fileBlockerFromServer({ title, bodyMd = '', source, sourceRef } = {}) {
+  const bad = (why) => { throw Object.assign(new Error(`ideas.fileBlocker: ${why}`), { code: 'BAD_BLOCKER' }); };
+  const str = (v, max, name, required) => {
+    if (v === undefined || v === null) { if (required) bad(`${name} is required`); return; }
+    if (typeof v !== 'string') bad(`${name} must be a string`);
+    if (required && !v.trim()) bad(`${name} is required`);
+    if (v.length > max) bad(`${name} is at most ${max} characters`);
+  };
+  str(title, LIMITS.TITLE, 'title', true);
+  str(bodyMd, LIMITS.DESCRIPTION, 'bodyMd', false);
+  str(source, LIMITS.SOURCE, 'source', true);
+  str(sourceRef, LIMITS.SOURCE_REF, 'sourceRef', true);
+  return blockers.createBlocker({ title, bodyMd, source, sourceRef });
+}
+
 module.exports = function buildBlockersRouter() {
   governorDocket.contributeIdeasToDocket();
+  // The `ideas.fileBlocker` PORT (task 1004912): the server's own checks raise a blocker for
+  // the owner without importing this module (the economy module's daily ledger check). Same
+  // idempotent writer as POST /blockers, keyed on (source, source_ref), held to the same
+  // length rules the route enforces. Registered here for the reason routes/inbox.js gives for
+  // `ideas.capture`; hasProvider-guarded for re-runs.
+  if (!api.hasProvider('ideas.fileBlocker')) {
+    api.registerProvider('ideas.fileBlocker', fileBlockerFromServer);
+  }
   const router = express.Router();
 
   // List currently-open blockers + the tasks each is blocking.
@@ -282,3 +307,4 @@ module.exports = function buildBlockersRouter() {
 
 // The scripts whose templated blockers file with or without a card (task 1004704).
 module.exports.TEMPLATED_SOURCES = TEMPLATED_SOURCES;
+module.exports.fileBlockerFromServer = fileBlockerFromServer;

package/modules/lifecycle/db-claims.js

@@ -32,6 +32,8 @@ const { relevanceFrictionFailures } = require('./db-relevance-flags.js');
 // task 1004950 / ADR 0395: a task that needs server access refuses a claimer
 // without the grant — the third extracted gate in the same shape.
 const { taskNeedsFailures } = require('./task-needs-gate.js');
+// task 1003185 / ADR 0386: the funding wall — the same shape, and it PLACES the hold.
+const { fundingWallFailures } = require('./funding-wall.js');
 const { unsatisfiedDeps } = require('./db-deps-criteria.js');
 // depRefusalRow: the ONE shape a DEPS_NOT_SHIPPED refusal carries. All three
 // claim paths below use it — hand-building the object here is what made task
@@ -378,6 +380,11 @@ async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSess
       if (refusal) throw refusal;
     }
 
+    // task 1003185 / ADR 0386: the funding wall, last before the insert, so a task's
+    // cash pay is held only once every other gate has passed (a later rollback undoes it).
+    const fundingRefusals = await fundingWallFailures({ client, tasks: [task], place: true });
+    if (fundingRefusals.length > 0) throw fundingRefusals[0].refusal;
+
     // Pre-allocate a migration number if the task signals it'll add one.
     // Trigger: the tasks.needs_migration boolean (migration 081, touches[]
     // cleanup [1/8] / task 876). Replaced the old touches[]-contains-'migrations/'
@@ -777,6 +784,15 @@ async function claimTasksBatch({ taskIds, builderId, worktreePrefix, creatorSess
       }
     }
 
+    // task 1003185: the funding wall, judged only for a batch every other gate passed,
+    // because it holds the whole batch's cash pay at once (each task against the ones before it).
+    if (failures.length === 0) {
+      for (const f of await fundingWallFailures({ client, tasks: taskRows, place: true })) {
+        const { code, ...rest } = f.refusal;
+        failures.push({ task_id: f.task_id, reason: code, ...rest });
+      }
+    }
+
     if (failures.length > 0) {
       throw { code: 'BATCH_FAILED', failures };
     }
@@ -1042,6 +1058,12 @@ async function validateClaimBatch({ taskIds, builderId }) {
     push(f.task_id, { reason: code, ...rest });
   }
 
+  // task 1003185: the funding wall as a read (no lock, no hold), kept in sync with the two above.
+  for (const f of await fundingWallFailures({ client: pool, tasks: taskRows })) {
+    const { code, ...rest } = f.refusal;
+    push(f.task_id, { reason: code, ...rest });
+  }
+
   // Dependencies — external to the batch only (a batch-internal dep is fine;
   // the batch is worked serially, same rule as claimTasksBatch).
   const batchIdSet = new Set(uniqIds);