@bongos/core 1.24.14 → 1.24.16

package/migrations/core_289_task_short_name.sql

@@ -0,0 +1,34 @@
+-- core_289 — every task gets a short name of 2-3 plain words (task 1004958).
+--
+-- A session that mentions "task 1004745" tells the person nothing; "task 1004745 -
+-- payout approvals" does. The name is stored so it is the same on every surface.
+-- modules/lifecycle/task-name.js derives it from the title (createTask writes it on
+-- every new task; the publish-reconciler's hourly backfill names the rows created
+-- before this), and the task's author may change it through PATCH /tasks/:id.
+--
+-- The CHECK is the trust boundary, not decoration: startup notes inject text into
+-- every session, so a name is held to at most three lowercase words of [a-z0-9-],
+-- 40 characters in all — a topic and nothing else. task-name.js NAME_RE is the
+-- same pattern; tests/task_name.mjs holds the two equal.
+--
+-- Additive and nullable with no default, so a rolled-back release that never names
+-- the column keeps working, and a row not yet backfilled simply prints "task N".
+
+BEGIN;
+
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS short_name text;
+ALTER TABLE tasks DROP CONSTRAINT IF EXISTS tasks_short_name_shape;
+ALTER TABLE tasks ADD CONSTRAINT tasks_short_name_shape
+  CHECK (short_name IS NULL OR (
+    char_length(short_name) <= 40
+    AND short_name ~ '^[a-z0-9]+(-[a-z0-9]+)*( [a-z0-9]+(-[a-z0-9]+)*){0,2}$'
+  ));
+-- The hourly backfill reads only unnamed rows. Once the first pass drains, that is a
+-- handful of titles with no topic word, so a partial index keeps every later pass
+-- a read of those few rows rather than a walk of the whole table.
+CREATE INDEX IF NOT EXISTS tasks_short_name_missing_idx ON tasks (id) WHERE short_name IS NULL;
+
+COMMIT;
+
+INSERT INTO schema_migrations (version) VALUES ('core_289_task_short_name')
+  ON CONFLICT (version) DO NOTHING;

package/modules/ai-studio/db.js

@@ -166,7 +166,17 @@ async function requestUploads(requestId, executor) {
   return rows;
 }
 
+// ---- age (provider terms: AI providers serve adults only) -----------------
+
+// The latest age tier recorded for the builder (payout gates' record), or null.
+async function latestAgeTier(builderId, executor) {
+  const { rows } = await exec(executor)(
+    'SELECT tier FROM payout_age_records WHERE builder_id = $1 ORDER BY id DESC LIMIT 1', [builderId]);
+  return rows[0] ? rows[0].tier : null;
+}
+
 module.exports = {
+  latestAgeTier,
   listKeyMeta, getKeyEnc, setKey, clearKey, appendLedger, recentLedger,
   addUpload, createRequest, markRunning, finishRequest, addOutput, getRequest, listRequests, getFile, requestUploads, countActiveRequests,
 };

package/modules/ai-studio/gemini.js

@@ -13,17 +13,71 @@
 
 'use strict';
 
+const crypto = require('node:crypto');
 const { ProviderError } = require('./openrouter');
 
 const BASE = 'https://generativelanguage.googleapis.com/v1beta/models';
 const MODELS = { reply: 'gemini-2.5-pro', images: 'gemini-2.5-flash-image' };
 const TIMEOUT_MS = 120000;
+const LIST_TIMEOUT_MS = 15000;
+
+// Google retires models on short notice, and a retired one answers 404. When
+// that happens we ask the key which models it can use and take the newest one
+// of the same kind, so a retirement never breaks the studio. The pick is
+// remembered per key (under a hash, never the key itself), because two keys
+// can be allowed different models.
+const resolved = new Map();
+const pickSlot = (key, kind) => `${crypto.createHash('sha256').update(String(key)).digest('hex').slice(0, 16)}:${kind}`;
 
 function parts(text, files) {
   return [{ text }, ...(files || []).map((f) => ({ inline_data: { mime_type: f.content_type, data: f.base64 } }))];
 }
 
-async function post(fetchImpl, key, model, body) {
+// Google's own reason, folded into the status: one line of printable text,
+// anything shaped like a Google key blanked, at most 160 characters.
+function googleReason(json) {
+  const m = json && json.error && typeof json.error.message === 'string' ? json.error.message : '';
+  const clean = m.replace(/AIza[\w-]{10,}/g, '[key]').replace(/[^\x20-\x7e]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 160);
+  return clean ? `: ${clean.replace(/\.$/, '')}` : '';
+}
+
+// Higher is better: stable over preview, newer version first.
+function versionOf(name) {
+  const m = /gemini-(\d+)(?:\.(\d+))?/.exec(name);
+  return m ? Number(m[1]) * 100 + Number(m[2] || 0) : 0;
+}
+
+// Choose the best model of a kind from a ListModels answer.
+function pickModel(kind, models) {
+  const usable = (models || []).filter((m) => m && typeof m.name === 'string'
+    && Array.isArray(m.supportedGenerationMethods) && m.supportedGenerationMethods.includes('generateContent'))
+    .map((m) => m.name.replace(/^models\//, ''))
+    .filter((n) => /^gemini-/.test(n));
+  const fits = kind === 'images'
+    ? usable.filter((n) => /image/.test(n))
+    : usable.filter((n) => /-(pro|flash)\b/.test(n) && !/(image|tts|audio|live|embed|lite|robotics|computer)/.test(n));
+  const score = (n) => (/preview|exp/.test(n) ? 0 : 100000)
+    + versionOf(n) * 10
+    + (kind === 'reply' && /-pro\b/.test(n) ? 2 : 0)
+    + (kind === 'images' && !/lite/.test(n) ? 1 : 0);
+  return fits.sort((a, b) => score(b) - score(a) || a.localeCompare(b))[0] || null;
+}
+
+async function listModels(fetchImpl, key) {
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), LIST_TIMEOUT_MS);
+  try {
+    const res = await fetchImpl(`${BASE}?pageSize=1000`, { method: 'GET', headers: { 'x-goog-api-key': key }, signal: ctl.signal });
+    const json = await res.json();
+    return res.ok && json && Array.isArray(json.models) ? json.models : [];
+  } catch (_) {
+    return [];
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function call(fetchImpl, key, model, body) {
   const ctl = new AbortController();
   const timer = setTimeout(() => ctl.abort(), TIMEOUT_MS);
   let res;
@@ -41,15 +95,29 @@ async function post(fetchImpl, key, model, body) {
   }
   let json = null;
   try { json = await res.json(); } catch (_) { /* fall through */ }
+  return { res, json };
+}
+
+async function post(fetchImpl, key, kind, body) {
+  const slot = pickSlot(key, kind);
+  const model = resolved.get(slot) || MODELS[kind];
+  let { res, json } = await call(fetchImpl, key, model, body);
+  if (res.status === 404) {
+    const next = pickModel(kind, await listModels(fetchImpl, key));
+    if (next && next !== model) {
+      ({ res, json } = await call(fetchImpl, key, next, body));
+      if (res.ok) resolved.set(slot, next);
+    }
+  }
   if (!res.ok || !json || json.error) {
-    throw new ProviderError('provider_error', `Google refused the request (HTTP ${res.status}). Check the key in Settings.`);
+    throw new ProviderError('provider_error', `Google refused the request (HTTP ${res.status}${googleReason(json)}). Check the key in Settings.`);
   }
   const cand = json.candidates && json.candidates[0];
   return (cand && cand.content && Array.isArray(cand.content.parts)) ? cand.content.parts : [];
 }
 
 async function reply({ fetchImpl, key, system, prompt, files }) {
-  const out = await post(fetchImpl, key, MODELS.reply, {
+  const out = await post(fetchImpl, key, 'reply', {
     systemInstruction: { parts: [{ text: system }] },
     contents: [{ role: 'user', parts: parts(prompt, files) }],
   });
@@ -59,7 +127,7 @@ async function reply({ fetchImpl, key, system, prompt, files }) {
 }
 
 async function images({ fetchImpl, key, system, brief, files }) {
-  const out = await post(fetchImpl, key, MODELS.images, {
+  const out = await post(fetchImpl, key, 'images', {
     systemInstruction: { parts: [{ text: system }] },
     contents: [{ role: 'user', parts: parts(brief, (files || []).filter((f) => f.content_type !== 'application/pdf')) }],
     generationConfig: { responseModalities: ['TEXT', 'IMAGE'] },
@@ -72,4 +140,4 @@ async function images({ fetchImpl, key, system, brief, files }) {
   return { images: list, costMicro: null };
 }
 
-module.exports = { BASE, reply, images };
+module.exports = { BASE, reply, images, pickModel, googleReason, _resolved: resolved };

package/modules/ai-studio/openrouter.js

@@ -17,6 +17,21 @@ const REPLY_MODEL = 'google/gemini-2.5-pro';
 const IMAGE_MODEL = 'google/gemini-2.5-flash-image';
 const TIMEOUT_MS = 120000;
 
+// What OpenRouter may route a call to (provider terms review, 2026-10-30): never
+// a provider that keeps or trains on prompts, only zero-retention endpoints, and
+// optionally only an allow-list of providers whose terms we have checked.
+//   OPENROUTER_ZDR=off                 allow endpoints that are not zero-retention
+//   OPENROUTER_ALLOWED_PROVIDERS=a,b   route only to these providers
+//   OPENROUTER_DISTILLABLE_ONLY=on     only models whose makers allow training on outputs
+function providerPolicy(env = process.env) {
+  const policy = { data_collection: 'deny' };
+  if (env.OPENROUTER_ZDR !== 'off') policy.zdr = true;
+  const only = String(env.OPENROUTER_ALLOWED_PROVIDERS || '').split(',').map((x) => x.trim()).filter(Boolean);
+  if (only.length) policy.only = only;
+  if (env.OPENROUTER_DISTILLABLE_ONLY === 'on') policy.enforce_distillable_text = true;
+  return policy;
+}
+
 class ProviderError extends Error {
   constructor(code, message) { super(message); this.code = code; }
 }
@@ -36,7 +51,7 @@ async function post(fetchImpl, key, body) {
     res = await fetchImpl(ENDPOINT, {
       method: 'POST',
       headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json', 'x-title': 'Cloud Bongos AI studio' },
-      body: JSON.stringify({ ...body, usage: { include: true } }),
+      body: JSON.stringify({ ...body, provider: providerPolicy(), usage: { include: true } }),
       signal: ctl.signal,
     });
   } catch (err) {
@@ -87,4 +102,4 @@ async function images({ fetchImpl, key, system, brief, files }) {
   return { images: list, costMicro: out.costMicro };
 }
 
-module.exports = { ENDPOINT, ProviderError, reply, images };
+module.exports = { ENDPOINT, ProviderError, providerPolicy, reply, images };

package/modules/ai-studio/routes/ai-studio.js

@@ -69,11 +69,13 @@ function runInBackground(request, choice) {
   });
 }
 
+const ADULTS_ONLY = 'AI Studio is for people 18 and over. Record your age in Settings to use it.';
+
 module.exports = function buildAiStudioRouter() {
   const router = express.Router();
 
   router.get('/ai-studio/status', api.requireBuilder, api.asyncHandler('GET /ai-studio/status', async (req, res) => {
-    res.json({ ok: true, module: 'ai-studio' });
+    res.json({ ok: true, module: 'ai-studio', terms: S.PROVIDER_TERMS, adult: S.isAdult(await db.latestAgeTier(req.builder.id)) });
   }));
 
   router.get('/ai-studio/keys', api.requireBuilder, api.asyncHandler('GET /ai-studio/keys', async (req, res) => {
@@ -138,6 +140,7 @@ module.exports = function buildAiStudioRouter() {
   // amount asked for arrives whole after the processor's fee (ADR 0392 d.4).
   router.post('/ai-studio/topup', api.requireBuilder, api.asyncHandler('POST /ai-studio/topup', async (req, res) => {
     if (api.validateOrRespond(req, res, { amount_usd: { required: true, type: 'number' } })) return;
+    if (!S.isAdult(await db.latestAgeTier(req.builder.id))) return res.fail('adults_only', { status: 403, message: ADULTS_ONLY });
     const b = payments.backend();
     if (b.name === 'none') return res.fail('payments_not_configured', { status: 409, message: 'Paying for generations is not set up here yet.' });
     let quote;
@@ -152,6 +155,8 @@ module.exports = function buildAiStudioRouter() {
 
   // One file per call, so a request body stays small; the global 64 KB parser
   // skips this path (src/bongos/routes.js) and this parser takes it.
+  // Not adults-gated on purpose: an upload is stored here and reaches no AI
+  // company until a request sends it, and /ai-studio/requests is gated.
   router.post('/ai-studio/uploads', api.requireBuilder, express.json({ limit: S.UPLOAD_BODY_LIMIT }), api.asyncHandler('POST /ai-studio/uploads', async (req, res) => {
     if (api.validateOrRespond(req, res, {
       content_type: { required: true, type: 'string', maxLength: 40 },
@@ -170,6 +175,7 @@ module.exports = function buildAiStudioRouter() {
       file_ids: { required: true, type: 'array', maxItems: S.MAX_FILES },
       pay_with: { type: 'string', enum: ['own', 'ours'] },
     })) return;
+    if (!S.isAdult(await db.latestAgeTier(req.builder.id))) return res.fail('adults_only', { status: 403, message: ADULTS_ONLY });
     const checked = S.checkRequest(req.body);
     if (checked.error) return res.fail(checked.error, { status: 400, message: S.MESSAGES[checked.error] });
     const stored = (await db.listKeyMeta(req.builder.id)).map((k) => k.provider);

package/modules/ai-studio/studio.js

@@ -115,7 +115,15 @@ function imageBrief(prompt, replyText) {
   return `Create finished artwork for this request from the project's artist. Follow the attached sketch's composition.\n\nThe artist asked:\n${prompt}\n\nArt direction:\n${clip(replyText, 1500)}`;
 }
 
+// Shown in the Studio, and agreed to by sending a request (OpenRouter terms 5.1:
+// the people we serve must follow each model maker's terms).
+const PROVIDER_TERMS = 'AI Studio is for people 18 and over. By sending a request you agree to follow the terms and usage policies of the AI company whose model answers it (listed at openrouter.ai), and not to use the results to train a competing AI model.';
+
+// The AI providers' terms admit adults only; no recorded age means no.
+const isAdult = (tier) => tier === 'adult';
+
 module.exports = {
+  PROVIDER_TERMS, isAdult,
   MAX_FILES, MAX_IMAGE_BYTES, MAX_PROMPT, MAX_COST_MICRO, MAX_ACTIVE_REQUESTS, CONTEXT_BUDGET, UPLOAD_BODY_LIMIT, MESSAGES,
   checkFile, checkRequest, forProvider, buildContext, imageBrief,
 };

package/modules/builder-settings/checkout-freshness.js

@@ -0,0 +1,71 @@
+// modules/builder-settings/checkout-freshness.js — how far behind this builder's local
+// project folder is, as their own session last reported it (task 1005021).
+//
+// WHY. A builder's hooks, CLAUDE.md and skills run from the folder on THEIR computer. When
+// that folder falls behind, every session there runs old rules and nobody is told: the
+// owner's sat 1,000 changes behind on a side branch for a week (task 1005015). Session
+// start now heals the common case itself (.claude/hooks/session-start.js); this records
+// what it found, so the server can say so when it could NOT heal — in the standing rules
+// every Conductor relays, stale ones included, and in the hall.
+//
+// Stored in one reserved key of the `behavior_prefs` jsonb (migration 119), the
+// core-move-seen.js way: no migration. Written only by the builder's own session.
+
+const RESERVED_KEY = 'checkout_freshness';
+// How far behind before it is worth a word. A day of merges is routine.
+const BEHIND_WORTH_SAYING = 50;
+// A report older than this says nothing about today's folder.
+const REPORT_TTL_MS = 3 * 24 * 60 * 60 * 1000;
+const REASONS = ['up-to-date', 'healed', 'fast-forwarded', 'dirty-tree', 'local-commits-ahead', 'detached-head', 'recent-edits', 'unmerged-branch', 'heal-failed', 'unknown'];
+const BRANCH_RE = /^[A-Za-z0-9._\/-]{1,120}$/;
+
+/** Validate a PATCH body { behind, branch, reason }. PURE. */
+function validatePatch(body) {
+  if (body == null || typeof body !== 'object' || Array.isArray(body)) return { ok: false, errors: [{ error: 'body_must_be_object' }] };
+  const errors = [];
+  const behind = Number(body.behind);
+  if (!Number.isInteger(behind) || behind < 0 || behind > 1000000) errors.push({ key: 'behind', error: 'invalid_value' });
+  const branch = body.branch == null ? '' : String(body.branch);
+  if (branch && !BRANCH_RE.test(branch)) errors.push({ key: 'branch', error: 'invalid_value' });
+  const reason = String(body.reason || '');
+  if (!REASONS.includes(reason)) errors.push({ key: 'reason', error: 'invalid_value', allowed: REASONS });
+  const extra = Object.keys(body).filter((k) => !['behind', 'branch', 'reason'].includes(k));
+  for (const key of extra) errors.push({ key, error: 'unknown_key' });
+  if (errors.length) return { ok: false, errors };
+  return { ok: true, report: { behind, branch, reason } };
+}
+
+/** behavior_prefs with the report stamped; sibling keys untouched. PURE. */
+function applyReport(existing, report, nowMs = Date.now()) {
+  return { ...(existing || {}), [RESERVED_KEY]: { ...report, at: new Date(nowMs).toISOString() } };
+}
+
+/**
+ * What GET /me says about the folder: the last report, whether it is behind enough to
+ * matter, and — when it is — one plain sentence for the person and one for their agent.
+ * null when nothing was ever reported, or the report is too old to mean anything. PURE.
+ */
+function describe(behaviorPrefs, nowMs = Date.now()) {
+  const r = behaviorPrefs && behaviorPrefs[RESERVED_KEY];
+  if (!r || typeof r !== 'object' || !Number.isInteger(r.behind)) return null;
+  const at = Date.parse(r.at);
+  if (!Number.isFinite(at) || nowMs - at > REPORT_TTL_MS) return null;
+  const behind = r.behind >= BEHIND_WORTH_SAYING;
+  const out = { behind_by: r.behind, branch: r.branch || null, reason: r.reason, reported_at: r.at, behind };
+  if (behind) {
+    const why = {
+      'dirty-tree': 'it has unsaved changes',
+      'recent-edits': 'it has recent unsaved changes',
+      'local-commits-ahead': 'it has work that is not merged yet',
+      'unmerged-branch': 'it is on a branch with work that is not merged yet',
+      'detached-head': 'it is not on a branch',
+      'heal-failed': 'the automatic update failed',
+    }[r.reason] || 'it could not update itself';
+    out.line = `Your project folder on this computer is ${r.behind} changes behind, and ${why}, so your AI sessions are running older rules.`;
+    out.agent_line = `This person's main project folder is ${r.behind} changes behind main and could not update itself (${r.reason}). `
+      + 'Tell them once, in plain words, and offer to update it for them (save anything unsaved on a backup branch first).';
+  }
+  return out;
+}
+
+module.exports = { validatePatch, applyReport, describe };

package/modules/builder-settings/routes/settings.js

@@ -31,6 +31,7 @@ const lawLocks = require('../law-locks');
 const renderPrefs = require('../render-prefs');
 const profileNudgePrefs = require('../profile-nudge-prefs');
 const coreMoveSeen = require('../core-move-seen');
+const checkoutFreshness = require('../checkout-freshness'); // task 1005021
 const displayName = require('../display-name');
 const filterViews = require('../filter-views');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
@@ -517,6 +518,31 @@ module.exports = function buildBuilderSettingsRouter() {
     }
   });
 
+  // How far behind this builder's local project folder is (task 1005021,
+  // checkout-freshness.js). Written by their own session start; read back by GET /me,
+  // which tells the person (and their agent) when the folder could not update itself.
+  // Body: { behind, branch, reason }.
+  //
+  // rank: any-builder — a builder's own report about their own computer; same posture
+  // as /me/core-move-seen.
+  router.patch('/me/checkout-freshness', api.requireBuilder, async (req, res) => {
+    if (api.validateOrRespond(req, res, {
+      behind: { required: true, type: 'number' },
+      branch: { type: 'string', maxLength: 120 },
+      reason: { required: true, type: 'string', maxLength: 40 },
+    }, { strict: true })) return undefined;
+    try {
+      const v = checkoutFreshness.validatePatch(req.body || {});
+      if (!v.ok) return res.fail('invalid_patch', 422, { errors: v.errors });
+      const existing = await db.getBuilderBehaviorPrefs(req.builder.id);
+      const saved = await db.setBuilderBehaviorPrefs(req.builder.id, checkoutFreshness.applyReport(existing, v.report));
+      res.json({ ok: true, checkout: checkoutFreshness.describe(saved) });
+    } catch (err) {
+      log.error('PATCH /me/checkout-freshness', err);
+      res.fail('write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // Per-builder SAVED FILTER VIEWS (task 1004553; shares the behavior_prefs jsonb /
   // migration 119). A view is a named set of filter values for one hall page. They
   // are PERSONAL: every route reads and writes only req.builder.id's own prefs, so

package/modules/builder-settings/settings.js

@@ -34,6 +34,7 @@ const renderPrefs = require('./render-prefs');
 const builderNeeds = require('./builder-needs');
 const lawLocks = require('./law-locks');
 const coreMoveSeen = require('./core-move-seen');
+const checkoutFreshness = require('./checkout-freshness'); // task 1005021
 
 module.exports = {
   // --- the raw behavior_prefs blob read (GET /me resolves this once, then shapes
@@ -57,6 +58,7 @@ module.exports = {
   // task 1004731: the core_upgrades row id this builder has acknowledged (the hall's
   // one-time "Upgraded to core X" notice), from the behavior_prefs blob; null if none.
   coreMoveSeen: (behaviorPrefs) => coreMoveSeen.seenId(behaviorPrefs),
+  describeCheckout: (behaviorPrefs) => checkoutFreshness.describe(behaviorPrefs),
 
   // --- the per-builder model ceiling for a skill (cascade-dispatch clamps to it;
   //     never exceeds it). Mirrors the former `skillPrefs.getForBuilder` call.

package/modules/economy/migrations/economy_002_project_account.sql

@@ -0,0 +1,83 @@
+-- economy_002_project_account.sql — the append-only record of every movement on the
+-- project's account, each one naming its cause (task 1003182, goal 1000092; ADR 0385
+-- decision 1, ADR 0397 decision 2).
+--
+-- THE ACCOUNT IS NOT HERE. The processor holds the project's money in the project's
+-- connected account (ADR 0397); Bongos holds none and has no balance column. What
+-- this table is: our own record of what moved and why, so the owner can answer
+-- "where did my money go" and so a daily check can compare it to the processor's
+-- figure (a later task). A balance shown from this table is a sum of the record, and
+-- is labelled as ours beside the processor's.
+--
+--   funding         money in: a charge settled into the project's account
+--   payout          money out to a builder, for a task: names the payee, the task and
+--                   the processor transfer
+--   payout_return   a payout the processor returned or reversed: money back in
+--   fee             a processor or platform fee taken from the account
+--   adjustment      a correction: names the movement it corrects; never an edit
+--   hold            a task's estimate set aside against the balance (ADR 0386);
+--                   moves no money
+--   hold_release    a hold let go on ship or release; moves no money
+--
+-- amount_micro is a positive integer count of micro-dollars. The direction comes from
+-- the kind (an adjustment carries its own direction), so a row cannot disagree with
+-- itself about whether it added or took away.
+--
+-- THE CAUSE IS THE POINT. A payout without a payee and a task, a funding or fee
+-- without a processor reference, or an adjustment that corrects nothing is refused by
+-- the DATABASE, not by whichever code path wrote it. One processor reference books one
+-- movement of its kind, so a retried payout cannot pay twice (the idempotency the
+-- payout task builds on). Rows are never updated or deleted: a wrong figure is fixed
+-- by a new row.
+
+CREATE TABLE IF NOT EXISTS economy_project_account_movements (
+  id            BIGSERIAL   PRIMARY KEY,
+  kind          TEXT        NOT NULL,
+  direction     TEXT        NOT NULL,
+  amount_micro  BIGINT      NOT NULL,
+  builder_id    BIGINT      REFERENCES builders(id),
+  task_id       BIGINT      REFERENCES tasks(id),
+  corrects_id   BIGINT      REFERENCES economy_project_account_movements(id),
+  processor_ref TEXT,
+  actor_id      BIGINT      REFERENCES builders(id),
+  note          TEXT        NOT NULL DEFAULT '',
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT economy_project_account_kind_chk CHECK (kind IN
+    ('funding', 'payout', 'payout_return', 'fee', 'adjustment', 'hold', 'hold_release')),
+  CONSTRAINT economy_project_account_direction_chk CHECK (direction IN ('in', 'out', 'none')),
+  CONSTRAINT economy_project_account_amount_chk CHECK (amount_micro > 0),
+  CONSTRAINT economy_project_account_note_chk CHECK (length(note) <= 300),
+  -- the direction is fixed by the kind; only an adjustment chooses
+  CONSTRAINT economy_project_account_direction_by_kind_chk CHECK (
+    (kind IN ('funding', 'payout_return') AND direction = 'in') OR
+    (kind IN ('payout', 'fee')            AND direction = 'out') OR
+    (kind IN ('hold', 'hold_release')     AND direction = 'none') OR
+    (kind = 'adjustment'                  AND direction IN ('in', 'out'))),
+  -- every movement names its cause
+  CONSTRAINT economy_project_account_cause_chk CHECK (
+    (kind = 'payout'        AND builder_id IS NOT NULL AND task_id IS NOT NULL AND processor_ref 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))
+);
+
+-- one processor reference, one movement of that kind: a retried payout is a no-op
+CREATE UNIQUE INDEX IF NOT EXISTS economy_project_account_one_per_ref
+  ON economy_project_account_movements (kind, processor_ref) WHERE processor_ref IS NOT NULL;
+CREATE INDEX IF NOT EXISTS economy_project_account_by_time ON economy_project_account_movements (created_at DESC, id DESC);
+CREATE INDEX IF NOT EXISTS economy_project_account_by_builder ON economy_project_account_movements (builder_id, created_at DESC) WHERE builder_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS economy_project_account_by_task ON economy_project_account_movements (task_id) WHERE task_id IS NOT NULL;
+
+CREATE OR REPLACE FUNCTION economy_project_account_movements_append_only() RETURNS trigger AS $$
+BEGIN
+  RAISE EXCEPTION 'economy_project_account_movements is append-only: record a correction as a new adjustment row';
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS economy_project_account_movements_no_rewrite ON economy_project_account_movements;
+CREATE TRIGGER economy_project_account_movements_no_rewrite BEFORE UPDATE OR DELETE ON economy_project_account_movements
+  FOR EACH ROW EXECUTE FUNCTION economy_project_account_movements_append_only();
+
+INSERT INTO schema_migrations (version) VALUES ('economy_002_project_account')
+  ON CONFLICT DO NOTHING;

package/modules/economy/module.json

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