@bongos/core 1.24.22 → 1.24.24

package/tests/payout_gates_db.mjs

@@ -37,7 +37,7 @@ try {
   await client.query(`CREATE SCHEMA ${SCHEMA}`);
   await client.query(`SET search_path TO ${SCHEMA}`);
   await client.query('CREATE TABLE builders (id bigserial PRIMARY KEY, system_role text)');
-  for (const m of ['core_283_payout_approvals.sql', 'core_284_payout_gates.sql']) {
+  for (const m of ['core_283_payout_approvals.sql', 'core_284_payout_gates.sql', 'core_291_payout_nda_tax.sql']) {
     await client.query(readFileSync(join(here, '..', 'migrations', m), 'utf8'));
   }
   // 1 owner, 2 a 16-17 builder, 3 their guardian, 4 an adult, 5 someone else
@@ -69,6 +69,20 @@ try {
   await refused("INSERT INTO payout_freeze_events (freeze_id, kind, actor_id, statement) VALUES ($1, 'lifted', 4, 'x')", [v.freeze_id], 'the frozen person cannot lift their own hold');
 
   await g.recordScreening({ builderId: 4, result: 'clear', screenedBy: 'person:owner', validUntil: new Date(Date.now() + 86_400_000).toISOString(), recordedBy: 1 }, o);
+
+  // contractor papers (task 1004908): an NDA on file and tax details collected
+  await refused("INSERT INTO payout_ndas (builder_id, status, nda_version, recorded_by) VALUES (4, 'on_file', 'beta-v1', 4)", [], 'nobody records their own NDA');
+  await refused("INSERT INTO payout_ndas (builder_id, status, nda_version, recorded_by) VALUES (4, 'signed', 'beta-v1', 1)", [], 'an unknown NDA status is refused');
+  await refused("INSERT INTO payout_tax_details (builder_id, status, collected_by, reference, recorded_by) VALUES (4, 'collected', 'person:owner', 'tin 123-45-6789', 1)", [], 'a tax id in the reference is refused by the database');
+  await refused("INSERT INTO payout_tax_details (builder_id, status, collected_by, recorded_by) VALUES (4, 'collected', 'person:owner', 4)", [], 'nobody records their own tax details');
+  const nda = await g.recordNda({ builderId: 4, status: 'on_file', ndaVersion: 'beta-v1', reference: 'envelope-test-1', recordedBy: 1 }, o);
+  await refused('UPDATE payout_ndas SET status = $1 WHERE id = $2', ['withdrawn', nda.id], 'an NDA record cannot be edited');
+  const p = await g.gateOwedPay(4, { owedCents: 300, pool: client });
+  ok(p.reason === 'frozen', 'papers do not lift an open hold either');
+  await g.recordTaxDetails({ builderId: 4, status: 'incomplete', collectedBy: 'person:owner', reference: 'acct_test_onboarding', recordedBy: 1 }, o);
+  await g.recordTaxDetails({ builderId: 4, status: 'collected', collectedBy: 'person:owner', reference: 'acct_test_onboarding', recordedBy: 1 }, o);
+  // after rows exist: the refuse-change trigger is per-row, so a DELETE on an empty table has nothing to refuse (task 1005039)
+  await refused('DELETE FROM payout_tax_details', [], 'tax-detail records cannot be deleted');
   ok((await g.gateOwedPay(4, { pool: client })).reason === 'frozen', 'a clear screening does not lift a hold by itself: a person does');
   await g.addFreezeEvent({ freezeId: v.freeze_id, kind: 'lifted', actorId: 1, statement: 'Screening came back clear.' }, o);
   await refused("INSERT INTO payout_freeze_events (freeze_id, kind, actor_id, statement) VALUES ($1, 'upheld', 1, 'x')", [v.freeze_id], 'nothing follows a lift');
@@ -82,6 +96,14 @@ try {
   await refused("INSERT INTO payout_guardians (builder_id, guardian_id, active, recorded_by) VALUES (2, 3, true, 1)", [], 'an active guardian link must name the guardian-controlled account');
   await refused("INSERT INTO payout_guardians (builder_id, guardian_id, guardian_account, active, recorded_by) VALUES (2, 2, 'acct', true, 1)", [], 'nobody is their own guardian');
   await g.recordGuardian({ builderId: 2, guardianId: 3, guardianAccount: 'acct_guardian', active: true, recordedBy: 1 }, o);
+  ok((await g.gateRecipient(2, o)).reason === 'nda_missing', 'with no NDA on file, not payable');
+  await g.recordNda({ builderId: 2, status: 'on_file', ndaVersion: 'beta-v1', reference: null, recordedBy: 1 }, o);
+  v = await g.gateOwedPay(2, { owedCents: 400, pool: client });
+  ok(v.reason === 'tax_details_missing' && v.freeze_id, 'with no tax details collected, owed pay is held and told why');
+  const paperHold = await g.readFreeze(v.freeze_id, o);
+  ok(paperHold.reason === 'tax_details_missing' && paperHold.notice_text === g.NOTICES.tax_details_missing, 'the hold table accepts the new reason, with its notice');
+  await g.addFreezeEvent({ freezeId: v.freeze_id, kind: 'lifted', actorId: 1, statement: 'Onboarding finished.' }, o);
+  await g.recordTaxDetails({ builderId: 2, status: 'collected', collectedBy: 'person:owner', reference: 'acct_test_ward', recordedBy: 1 }, o);
   v = await g.gateRecipient(2, o);
   ok(v.ok && v.needs_guardian_cosign && v.pay_to.guardian_account === 'acct_guardian', '16-17 with a guardian is paid only into the guardian\'s account, co-signed');
 

package/tests/project_account_db.mjs

@@ -18,7 +18,9 @@ const require = createRequire(import.meta.url);
 const { Pool } = require('pg');
 const A = require('../modules/economy/project-account.js');
 const here = dirname(fileURLToPath(import.meta.url));
-const MIGRATION = readFileSync(join(here, '..', 'modules', 'economy', 'migrations', 'economy_002_project_account.sql'), 'utf8');
+// economy_004 (task 1004910) adds module_share_id, which recordMovement writes.
+const MIGRATION = ['economy_002_project_account.sql', 'economy_004_module_share_payouts.sql']
+  .map((f) => readFileSync(join(here, '..', 'modules', 'economy', 'migrations', f), 'utf8')).join('\n');
 
 const pgPool = new Pool({ connectionString: process.env.DATABASE_URL || undefined, max: 1 });
 let client;
@@ -45,7 +47,8 @@ try {
   await client.query(`CREATE SCHEMA ${SCHEMA}`);
   await client.query(`SET search_path TO ${SCHEMA}`);
   await client.query('CREATE TABLE builders (id bigserial PRIMARY KEY, display_name text)');
-  await client.query('CREATE TABLE tasks (id bigserial PRIMARY KEY, title text)');
+  // status: a hold counts only while its task is being worked (task 1003185)
+  await client.query("CREATE TABLE tasks (id bigserial PRIMARY KEY, title text, status text NOT NULL DEFAULT 'active')");
   await client.query('CREATE TABLE schema_migrations (version text PRIMARY KEY)');
   await client.query("INSERT INTO builders (display_name) VALUES ('Ada'), ('Owner')");
   await client.query("INSERT INTO tasks (title) VALUES ('Build the thing')");

package/tests/project_outflow.mjs

@@ -0,0 +1,103 @@
+// tests/project_outflow.mjs — where the money went (task 1003184, goal 1000092 M05;
+// criterion money-outflow-visible). Behaviour of modules/economy/outflow.js's shapeOutflow:
+//   - a debt with no sent attempt is committed, and so is an approval nothing was booked against;
+//   - the balance left after commitments subtracts both, and goes negative when it must;
+//   - holds are shown but never subtracted twice (available already excludes them);
+//   - a commitment in another currency is counted, never added to a dollar figure;
+//   - per-builder totals sum spend, paid, owed and approved, biggest first;
+//   - each month's burn is its spend plus money out of the account.
+// The SQL is proven against real Postgres in tests/project_outflow_db.mjs.
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { shapeOutflow } = require('../modules/economy/outflow.js');
+
+const account = (recorded, held = 0) => ({ recorded_balance_micro: String(recorded), held_micro: String(held) });
+const base = {
+  burn: [], payouts: [], approved: [], spendByBuilder: [], spendTotal: '0',
+  account: account(0), names: [{ id: '1', display_name: 'Ada' }, { id: '2', display_name: 'Bo' }],
+};
+const owed = (id, builder, cents, paid = false, extra = {}) => ({
+  id, builder_id: builder, task_id: 90 + id, task_title: `task ${id}`, amount_cents: String(cents),
+  currency: 'USD', created_at: `2026-10-0${id}T00:00:00Z`, paid, ...extra,
+});
+
+test('a balance that owes three payouts shows what is left after them', () => {
+  const out = shapeOutflow({
+    ...base,
+    account: account(100_000_000),
+    payouts: [owed(1, '1', 3000), owed(2, '1', 3000), owed(3, '2', 3000), owed(4, '2', 5000, true)],
+  });
+  assert.equal(out.committed.owed_count, 3);
+  assert.equal(out.committed.owed_micro, 90_000_000);
+  assert.equal(out.balance.available_micro, 100_000_000);
+  assert.equal(out.balance.after_commitments_micro, 10_000_000);
+  assert.equal(out.totals.paid_micro, 50_000_000, 'a sent payout is paid, not owed');
+  assert.deepEqual(out.committed.owed.map((r) => r.owed_id), ['1', '2', '3'], 'oldest debt first');
+  assert.equal(out.committed.owed[0].builder_name, 'Ada');
+});
+
+test('an approval with no payout booked is committed too, and can push the balance below zero', () => {
+  const out = shapeOutflow({
+    ...base,
+    account: account(10_000_000),
+    approved: [{ id: 7, builder_id: '2', amount_cents: '2500', currency: 'USD' }],
+  });
+  assert.equal(out.committed.approved_count, 1);
+  assert.equal(out.committed.approved_micro, 25_000_000);
+  assert.equal(out.committed.total_micro, 25_000_000);
+  assert.equal(out.balance.after_commitments_micro, -15_000_000);
+});
+
+test('holds are shown and already out of available, so they are not subtracted again', () => {
+  const out = shapeOutflow({ ...base, account: account(50_000_000, 20_000_000), payouts: [owed(1, '1', 1000)] });
+  assert.equal(out.committed.held_micro, 20_000_000);
+  assert.equal(out.balance.available_micro, 30_000_000);
+  assert.equal(out.balance.after_commitments_micro, 20_000_000);
+  assert.equal(out.committed.total_micro, 10_000_000, 'the committed total is owed + approved only');
+});
+
+test('another currency is counted, never added to a dollar figure', () => {
+  const out = shapeOutflow({
+    ...base,
+    payouts: [owed(1, '1', 1000, false, { currency: 'EUR' }), owed(2, '1', 1000, true, { currency: 'EUR' })],
+    approved: [{ id: 8, builder_id: '1', amount_cents: '900', currency: 'GBP' }],
+  });
+  assert.equal(out.committed.owed_micro, 0);
+  assert.equal(out.committed.approved_micro, 0);
+  assert.equal(out.committed.other_currency_count, 2, 'unpaid EUR debt and GBP approval; a paid one is not a commitment');
+  assert.deepEqual(out.by_builder, []);
+});
+
+test('per-builder totals add spend, paid, owed and approved, biggest first', () => {
+  const out = shapeOutflow({
+    ...base,
+    spendByBuilder: [{ builder_id: '1', spend_micro: '4000000' }, { builder_id: '3', spend_micro: '0' }],
+    payouts: [owed(1, '2', 1000, true), owed(2, '2', 500)],
+    approved: [{ id: 9, builder_id: '1', amount_cents: '100', currency: 'USD' }],
+  });
+  assert.deepEqual(out.by_builder.map((b) => [b.builder_id, b.total_micro]), [['2', 15_000_000], ['1', 5_000_000]]);
+  const bo = out.by_builder[0];
+  assert.equal(bo.builder_name, 'Bo');
+  assert.equal(bo.paid_micro, 10_000_000);
+  assert.equal(bo.owed_micro, 5_000_000);
+  assert.ok(!out.by_builder.some((b) => b.builder_id === '3'), 'a builder with nothing is left out');
+});
+
+test('each month burns its spend plus money out of the account', () => {
+  const out = shapeOutflow({
+    ...base,
+    burn: [
+      { month: '2026-10', spend_micro: '1500000', payouts_micro: '3000000', other_out_micro: '200000' },
+      { month: '2026-11', spend_micro: '0', payouts_micro: '0', other_out_micro: '0' },
+    ],
+    spendTotal: '9000000',
+  });
+  assert.deepEqual(out.burn.months.map((m) => m.total_micro), [4_700_000, 0]);
+  assert.equal(out.burn.window_total_micro, 4_700_000);
+  assert.equal(out.totals.spend_micro, 9_000_000);
+  assert.equal(out.holds_money, false);
+});

package/tests/project_outflow_db.mjs

@@ -0,0 +1,100 @@
+// tests/project_outflow_db.mjs — task 1003184 (goal 1000092 M05). Real DB.
+//
+// Applies the REAL project-account and builder-payout migrations (economy_002, core_290) over
+// minimal builders / tasks / cost_log / payout_approvals tables, books a small history through
+// the real recordMovement, and proves the real readOutflow's SQL: a sent payout is paid, an
+// owed one with only a failed try is committed, an approval with no payout booked is committed,
+// the months run gap-free to this month, spend lands on its month and its builder, and the
+// balance after commitments is the account less every commitment.
+//
+// Self-skips without a reachable Postgres. `seed` and `check` are exported so the same scenario
+// can be driven through any { query } client.
+// Run:  DATABASE_URL=... node tests/project_outflow_db.mjs
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { strict as assert } from 'node:assert';
+const require = createRequire(import.meta.url);
+const A = require('../modules/economy/project-account.js');
+const { readOutflow } = require('../modules/economy/outflow.js');
+const here = dirname(fileURLToPath(import.meta.url));
+const read = (...p) => readFileSync(join(here, '..', ...p), 'utf8');
+const ACCOUNT_SQL = read('modules', 'economy', 'migrations', 'economy_002_project_account.sql')
+  + read('modules', 'economy', 'migrations', 'economy_004_module_share_payouts.sql');
+const PAYOUTS_SQL = read('migrations', 'core_290_builder_payouts.sql');
+
+export async function seed(q) {
+  await q.query('CREATE TABLE builders (id bigserial PRIMARY KEY, display_name text, github_login text)');
+  // status: a hold counts only while its task is being worked (task 1003185)
+  await q.query("CREATE TABLE tasks (id bigserial PRIMARY KEY, title text, status text NOT NULL DEFAULT 'active')");
+  await q.query('CREATE TABLE schema_migrations (version text PRIMARY KEY)');
+  await q.query(`CREATE TABLE cost_log (id bigserial PRIMARY KEY, amount_usd numeric(10,4) NOT NULL,
+    builder_id bigint, recorded_at timestamptz NOT NULL DEFAULT now())`);
+  await q.query(`CREATE TABLE payout_approvals (id bigserial PRIMARY KEY, kind text NOT NULL,
+    recipient_id bigint, amount_cents bigint, currency text, created_at timestamptz NOT NULL DEFAULT now())`);
+  await q.query(ACCOUNT_SQL);
+  // core_292's binding table, which the approved read excludes (task 1004910)
+  await q.query('CREATE TABLE module_share_approvals (share_id bigint PRIMARY KEY, approval_id bigint NOT NULL UNIQUE)');
+  await q.query(PAYOUTS_SQL);
+  await q.query("INSERT INTO builders (display_name) VALUES ('Ada'), ('Bo'), ('Owner')");
+  await q.query("INSERT INTO tasks (title) VALUES ('Paid task'), ('Owed task'), ('Approved task')");
+  // approvals: 1 paid, 2 owed (failed once), 3 approved and never booked, 4 approved in EUR
+  await q.query(`INSERT INTO payout_approvals (kind, recipient_id, amount_cents, currency) VALUES
+    ('payout_approved', 1, 4000, 'USD'), ('payout_approved', 2, 3000, 'USD'),
+    ('payout_approved', 2, 2000, 'USD'), ('payout_approved', 1, 900, 'EUR'),
+    ('rule_signed', NULL, NULL, NULL)`);
+  await q.query(`INSERT INTO builder_payouts_owed (builder_id, task_id, approval_id, amount_cents, currency, recorded_by)
+    VALUES (1, 1, 1, 4000, 'USD', 3), (2, 2, 2, 3000, 'USD', 3)`);
+  await q.query(`INSERT INTO builder_payout_attempts (owed_id, outcome, processor_ref, reason) VALUES
+    (1, 'failed', NULL, 'timeout'), (1, 'sent', 'tr_1', NULL), (2, 'failed', NULL, 'card declined')`);
+  await A.recordMovement(q, { kind: 'funding', amountMicro: 100_000_000, processorRef: 'ch_1' });
+  await A.recordMovement(q, { kind: 'payout', amountMicro: 40_000_000, builderId: 1, taskId: 1, processorRef: 'tr_1' });
+  await A.recordMovement(q, { kind: 'fee', amountMicro: 1_000_000, processorRef: 'fee_1' });
+  await q.query(`INSERT INTO cost_log (amount_usd, builder_id, recorded_at) VALUES
+    (2.5, 1, now()), (1.25, NULL, now()), (7, 2, now() - interval '400 days')`);
+}
+
+export async function check(q, ok) {
+  const out = await readOutflow(q, { months: 3 });
+  ok(out.burn.months.length === 3, 'the window holds every month, quiet ones included');
+  const thisMonth = out.burn.months[2];
+  ok(thisMonth.spend_micro === 3_750_000, `this month's spend is summed from cost_log (${thisMonth.spend_micro})`);
+  ok(thisMonth.payouts_micro === 40_000_000 && thisMonth.other_out_micro === 1_000_000, 'payouts and fees out of the account land on their month');
+  ok(out.totals.spend_micro === 10_750_000, 'total spend covers all time, not just the window');
+  ok(out.totals.paid_micro === 40_000_000, 'only the debt with a sent attempt is paid');
+  ok(out.committed.owed_count === 1 && out.committed.owed[0].task_title === 'Owed task', 'a debt whose last try failed is still owed');
+  ok(out.committed.owed[0].last_reason === 'card declined', 'the owed row carries its latest try');
+  ok(out.committed.approved_count === 1 && out.committed.approved_micro === 20_000_000, 'an approval nothing was booked against is committed; a rule is not');
+  ok(out.committed.other_currency_count === 1, 'the EUR approval is counted, not added');
+  ok(out.balance.available_micro === 59_000_000, 'available is the account record');
+  ok(out.balance.after_commitments_micro === 9_000_000, 'after commitments = available − owed − approved');
+  const bo = out.by_builder.find((b) => b.builder_name === 'Bo');
+  ok(bo && bo.spend_micro === 7_000_000 && bo.owed_micro === 30_000_000 && bo.approved_micro === 20_000_000, 'per-builder totals read every record');
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const { Pool } = require('pg');
+  const pgPool = new Pool({ connectionString: process.env.DATABASE_URL || undefined, max: 1 });
+  let client;
+  try { client = await pgPool.connect(); } catch (e) {
+    console.log(`project_outflow_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+    await pgPool.end().catch(() => {});
+    process.exit(0);
+  }
+  const SCHEMA = `t1003184_${process.pid}`;
+  let pass = 0;
+  const ok = (c, m) => { assert.ok(c, m); pass++; console.log(`  ok - ${m}`); };
+  try {
+    await client.query(`CREATE SCHEMA ${SCHEMA}`);
+    await client.query(`SET search_path TO ${SCHEMA}`);
+    const q = { query: (s, p) => client.query(s, p) };
+    await seed(q);
+    await check(q, ok);
+    console.log(`project_outflow_db.mjs: ${pass} passed`);
+  } finally {
+    await client.query(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`).catch(() => {});
+    client.release();
+    await pgPool.end();
+  }
+}

package/tests/provision_settings_apply.mjs

@@ -76,6 +76,7 @@ ${NEUTRAL_PREFIX}_ARTIST_GATE_SINCE=
 ${NEUTRAL_PREFIX}_LOOK_ACCENT=
 ${NEUTRAL_PREFIX}_LOGO_URL=
 ${NEUTRAL_PREFIX}_FOUNDING_BIRTH=
+${NEUTRAL_PREFIX}_FOUNDING_GENESIS=
 ${NEUTRAL_PREFIX}_DEMO_PEOPLE=
 ${NEUTRAL_PREFIX}_DEMO_HOURS=
 ${NEUTRAL_PREFIX}_SHIP_MODE=
@@ -148,7 +149,7 @@ t('settingsEnvVarsFor: the runner pushes the SAME pair webEnvBody writes at stan
     [`${NEUTRAL_PREFIX}_LOOK`]: 'own', [`${NEUTRAL_PREFIX}_NIGHT_TINT`]: 'on',
     [`${NEUTRAL_PREFIX}_LOOK_ACCENT`]: '', [`${NEUTRAL_PREFIX}_LOGO_URL`]: '',
     // the birth marker and a demo's box (task 1004506), empty on an un-stamped row
-    [`${NEUTRAL_PREFIX}_FOUNDING_BIRTH`]: '', [`${NEUTRAL_PREFIX}_DEMO_PEOPLE`]: '', [`${NEUTRAL_PREFIX}_DEMO_HOURS`]: '',
+    [`${NEUTRAL_PREFIX}_FOUNDING_BIRTH`]: '', [`${NEUTRAL_PREFIX}_FOUNDING_GENESIS`]: '', [`${NEUTRAL_PREFIX}_DEMO_PEOPLE`]: '', [`${NEUTRAL_PREFIX}_DEMO_HOURS`]: '',
     // the wizard's ship mode (task 1004629), empty when none was picked
     [`${NEUTRAL_PREFIX}_SHIP_MODE`]: '',
     // where the hall's Update button goes (task 1004608), empty when no hub origin resolves

package/tests/provisioning_settings_env.mjs

@@ -126,7 +126,7 @@ t('settingsEnvVars is the single source both legs derive from — same keys, sam
     CLOUDBONGOS_LOOK: 'own', CLOUDBONGOS_NIGHT_TINT: 'on', CLOUDBONGOS_LOOK_ACCENT: '', CLOUDBONGOS_LOGO_URL: '',
     // The birth marker and a demo's box (task 1004506): empty on a row the create
     // route never stamped, which is every row made before it shipped (spec D8).
-    CLOUDBONGOS_FOUNDING_BIRTH: '', CLOUDBONGOS_DEMO_PEOPLE: '', CLOUDBONGOS_DEMO_HOURS: '',
+    CLOUDBONGOS_FOUNDING_BIRTH: '', CLOUDBONGOS_FOUNDING_GENESIS: '', CLOUDBONGOS_DEMO_PEOPLE: '', CLOUDBONGOS_DEMO_HOURS: '',
     // The wizard's ship mode (task 1004629): empty when none was picked.
     CLOUDBONGOS_SHIP_MODE: '',
   });
@@ -137,7 +137,7 @@ t('settingsEnvVars is the single source both legs derive from — same keys, sam
     X_PLATFORM_VISIBILITY: 'public', X_JOINABILITY: 'apply', X_VISIBILITY: 'public', X_JOIN_GRANT: 'full',
     X_ARTIST_GATE: 'strict', X_ARTIST_GATE_SINCE: '', X_SPEND_PAYER: 'none',
     X_LOOK: 'own', X_NIGHT_TINT: 'on', X_LOOK_ACCENT: '', X_LOGO_URL: '',
-    X_FOUNDING_BIRTH: '', X_DEMO_PEOPLE: '', X_DEMO_HOURS: '', X_SHIP_MODE: '',
+    X_FOUNDING_BIRTH: '', X_FOUNDING_GENESIS: '', X_DEMO_PEOPLE: '', X_DEMO_HOURS: '', X_SHIP_MODE: '',
   }, 'defaults, explicitly');
 });
 
@@ -155,6 +155,10 @@ t('a stamped row carries its birth; only a stamped DEMO carries the box', () =>
   assert.deepEqual([oldDemo.X_FOUNDING_BIRTH, oldDemo.X_DEMO_PEOPLE, oldDemo.X_DEMO_HOURS], ['', '', ''],
     'a demo made before the birth shipped is not born into anything, box and all');
   assert.equal(provisioning.settingsEnvVars({ settings: { founding_birth: 'yesterday' } }, 'X').X_FOUNDING_BIRTH, '', 'a mangled stamp reads as none');
+  // Genesis is paused: only a birth stamped with the genesis key carries the companion (owner, 2026-11-01).
+  assert.equal(provisioning.settingsEnvVars({ settings: { founding_birth: at, founding_genesis: 'on' } }, 'X').X_FOUNDING_GENESIS, 'on');
+  assert.equal(real.X_FOUNDING_GENESIS, '', 'a birth alone, the shape of every project before the pause, does not found');
+  assert.equal(provisioning.settingsEnvVars({ settings: { founding_genesis: 'on' } }, 'X').X_FOUNDING_GENESIS, '', 'the genesis key without a birth is nothing');
 });
 
 t('the stamp can neither leak as a setting nor be written by a client patch', () => {
@@ -172,7 +176,7 @@ t('stampBirth writes the row it is given, once: an existing stamp is kept', () =
   assert.equal(seen.length, 1);
   assert.match(seen[0].sql, /UPDATE provisioning_instances/);
   assert.match(seen[0].sql, /WHERE id = \$1 AND NOT \(COALESCE\(settings, '\{\}'::jsonb\) \? \$2::text\)/, 'write-once');
-  assert.deepEqual(seen[0].params, [41, BIRTH_KEY, '2026-10-01T00:00:00.000Z']);
+  assert.deepEqual(seen[0].params, [41, BIRTH_KEY, '2026-10-01T00:00:00.000Z', 'founding_genesis']);
 });
 
 t('the instance reads the marker into founding.*, and never publishes it to the client', () => {

package/tests/user_balances.mjs

@@ -0,0 +1,241 @@
+// tests/user_balances.mjs — user balances and fee-free transfers, isolated per project
+// (task 1004907, goal 1000092 N3; ADR 0385, ADR 0397). Behaviour of
+// modules/economy/user-balances.js and its routes:
+//   - a balance is the processor's figure, never a sum of our record;
+//   - an instruction is carried out once, with no platform fee, and funding books the
+//     project-account movement;
+//   - with no processor nothing moves and the instruction is held, not lost;
+//   - only a person's own web session may pay;
+//   - TWO PROJECTS: neither can read, link or spend the other's accounts.
+// The SQL itself is proven against real Postgres in tests/user_balances_db.mjs.
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const U = require('../modules/economy/user-balances.js');
+
+// A stand-in for one project's database: the three tables and the project-account record,
+// answering the statements user-balances.js and project-account.js send.
+function fakeProjectDb() {
+  const t = { accounts: [], transfers: [], attempts: [], movements: [] };
+  let id = 0;
+  const db = {
+    t,
+    async query(sql, p = []) {
+      const s = sql.replace(/\s+/g, ' ').trim();
+      if (s.startsWith('SELECT pg_advisory_xact_lock')) return { rows: [] };
+      if (s.startsWith('SELECT processor_account FROM economy_member_accounts')) {
+        const r = t.accounts.filter((a) => a.builder_id === String(p[0])).at(-1);
+        return { rows: r ? [r] : [] };
+      }
+      if (s.startsWith('SELECT builder_id FROM economy_member_accounts')) return { rows: t.accounts.filter((a) => a.processor_account === p[0]).slice(0, 1) };
+      if (s.startsWith('INSERT INTO economy_member_accounts')) {
+        t.accounts.push({ id: ++id, builder_id: String(p[0]), processor_account: p[1] }); return { rows: [] };
+      }
+      if (s.startsWith('INSERT INTO economy_user_transfers')) {
+        if (!t.transfers.some((x) => x.from_builder_id === p[1] && x.instruction_id === p[7])) {
+          t.transfers.push({ id: ++id, kind: p[0], from_builder_id: p[1], to_builder_id: p[2], from_account: p[3], to_account: p[4],
+            amount_cents: p[5], currency: p[6], instruction_id: p[7], note: p[8], platform_fee_cents: 0 });
+        }
+        return { rows: [] };
+      }
+      if (s.startsWith('SELECT * FROM economy_user_transfers')) return { rows: t.transfers.filter((x) => x.from_builder_id === String(p[0]) && x.instruction_id === p[1]) };
+      if (s.startsWith('SELECT processor_ref FROM economy_user_transfer_attempts')) return { rows: t.attempts.filter((a) => a.transfer_id === String(p[0]) && a.outcome === 'sent') };
+      if (s.startsWith('INSERT INTO economy_user_transfer_attempts')) {
+        t.attempts.push({ id: ++id, transfer_id: String(p[0]), outcome: p[1], processor_ref: p[2], reason: p[3] }); return { rows: [] };
+      }
+      if (s.startsWith('INSERT INTO economy_project_account_movements')) {
+        const row = { id: ++id, kind: p[0], amount_micro: p[2], builder_id: p[3], processor_ref: p[6] };
+        t.movements.push(row); return { rows: [row] };
+      }
+      if (s.startsWith('SELECT t.id, t.kind')) {
+        const who = String(p[0]);
+        const rows = t.transfers.filter((x) => x.from_builder_id === who || x.to_builder_id === who).reverse().map((x) => {
+          const mine = t.attempts.filter((a) => a.transfer_id === String(x.id));
+          const sent = mine.find((a) => a.outcome === 'sent');
+          const last = mine.at(-1);
+          return { ...x, sent_ref: sent ? sent.processor_ref : null, last_outcome: last && last.outcome, last_reason: last && last.reason };
+        });
+        return { rows };
+      }
+      throw new Error(`unexpected SQL: ${s.slice(0, 80)}`);
+    },
+  };
+  return db;
+}
+
+// A stand-in for one project's processor connection: it knows only the accounts it opened.
+function fakeProcessor(name, { opened = {}, balances = {}, projectMicro = 0 } = {}) {
+  const calls = [];
+  let n = 0;
+  const byKey = new Map();
+  return {
+    calls,
+    async balanceMicro() { return projectMicro; },
+    async memberBalanceMicro(ref) {
+      if (!(ref in balances)) throw new Error(`${name} has no account ${ref}`);
+      return balances[ref];
+    },
+    async confirmMemberAccount({ accountRef, builderId }) { return opened[accountRef] === builderId; },
+    async memberTransfer(req) {
+      calls.push(req);
+      for (const acc of [req.fromAccount, req.toAccount].filter(Boolean)) {
+        if (!(acc in opened)) throw Object.assign(new Error(`${name} does not hold ${acc}`), { code: 'unknown_account' });
+      }
+      if (!byKey.has(req.idempotencyKey)) byKey.set(req.idempotencyKey, `tr_${name}_${++n}`);
+      return { ref: byKey.get(req.idempotencyKey) };
+    },
+  };
+}
+
+async function project(name, members) {
+  const db = fakeProjectDb();
+  const opened = {}; const balances = {};
+  for (const [builderId, ref, micro] of members) { opened[ref] = builderId; balances[ref] = micro; }
+  const processor = fakeProcessor(name, { opened, balances, projectMicro: 9_000_000 });
+  for (const [builderId, ref] of members) await U.linkMemberAccount(db, { builderId, accountRef: ref }, { processor });
+  return { db, processor };
+}
+
+const code = async (p) => { try { await p; } catch (e) { return e.code; } return null; };
+
+test('a balance is the processor figure; our record is never summed into one', async () => {
+  const a = await project('A', [['1', 'acct_a1', 4_200_000]]);
+  const me = await U.readMyBalance(a.db, '1', { processor: a.processor });
+  assert.equal(me.balance_micro, 4_200_000);
+  assert.equal(me.holds_money, false);
+  assert.equal(me.source, 'processor');
+  assert.equal((await U.readProjectBalance({ processor: a.processor })).balance_micro, 9_000_000);
+  const none = await U.readMyBalance(a.db, '2', { processor: a.processor });
+  assert.equal(none.connected, false);
+  assert.equal(none.balance_micro, null);
+  const broken = { memberBalanceMicro: async () => { throw new Error('acct_secret down'); } };
+  const r = await U.readMyBalance(a.db, '1', { processor: broken });
+  assert.equal(r.balance_micro, null);
+  assert.ok(r.processor_error && !r.processor_error.includes('acct_secret'), 'the processor error text never reaches the person');
+});
+
+test('a person pays another member once, with no platform fee', async () => {
+  const a = await project('A', [['1', 'acct_a1', 0], ['2', 'acct_a2', 0]]);
+  const pay = { kind: 'pay_user', fromBuilderId: '1', toBuilderId: '2', amountCents: 2500, instructionId: 'pay-0001-abc' };
+  const out = await U.transfer(pay, { pool: a.db, processor: a.processor });
+  assert.equal(out.status, 'sent');
+  assert.equal(out.platform_fee_cents, 0);
+  assert.deepEqual(a.processor.calls[0], {
+    idempotencyKey: `bongos-user-transfer-${out.transfer_id}`, amountCents: 2500, currency: 'USD',
+    fromAccount: 'acct_a1', toAccount: 'acct_a2', toProject: false,
+  });
+  const again = await U.transfer(pay, { pool: a.db, processor: a.processor });
+  assert.equal(again.status, 'sent');
+  assert.equal(again.already, true);
+  assert.equal(a.processor.calls.length, 1, 'a second press sends nothing');
+  assert.equal(a.db.t.movements.length, 0, 'a payment between people never touches the project account');
+  assert.equal(await code(U.transfer({ ...pay, amountCents: 9999 }, { pool: a.db, processor: a.processor })), 'instruction_reused');
+  const seen = await U.readMyBalance(a.db, '2', { processor: a.processor });
+  assert.equal(seen.transfers[0].direction, 'in');
+  assert.equal(seen.transfers[0].status, 'sent');
+});
+
+test('funding the project books one funding movement naming the funder', async () => {
+  const a = await project('A', [['1', 'acct_a1', 0]]);
+  const out = await U.transfer({ kind: 'fund_project', fromBuilderId: '1', amountCents: 1000, instructionId: 'fund-0001-xy' },
+    { pool: a.db, processor: a.processor });
+  assert.equal(out.status, 'sent');
+  assert.equal(a.processor.calls[0].toProject, true);
+  assert.equal(a.processor.calls[0].toAccount, null);
+  assert.equal(a.db.t.movements.length, 1);
+  assert.equal(a.db.t.movements[0].kind, 'funding');
+  assert.equal(a.db.t.movements[0].amount_micro, 10_000_000);
+  assert.equal(a.db.t.movements[0].builder_id, '1');
+});
+
+test('with no processor connected the instruction is recorded and held, nothing moves', async () => {
+  const a = await project('A', [['1', 'acct_a1', 0], ['2', 'acct_a2', 0]]);
+  const out = await U.transfer({ kind: 'pay_user', fromBuilderId: '1', toBuilderId: '2', amountCents: 5, instructionId: 'held-0001-q' },
+    { pool: a.db, processor: null });
+  assert.equal(out.status, 'held');
+  assert.equal(out.reason, 'no_processor');
+  assert.equal(a.db.t.transfers.length, 1);
+  assert.equal(a.db.t.attempts[0].outcome, 'held');
+});
+
+test('a failed transfer is recorded with its reason and not re-sent on its own', async () => {
+  const a = await project('A', [['1', 'acct_a1', 0], ['2', 'acct_a2', 0]]);
+  const flaky = { memberTransfer: async () => { throw Object.assign(new Error('insufficient funds'), { code: 'balance_insufficient' }); } };
+  const out = await U.transfer({ kind: 'pay_user', fromBuilderId: '1', toBuilderId: '2', amountCents: 5, instructionId: 'fail-0001-q' },
+    { pool: a.db, processor: flaky });
+  assert.equal(out.status, 'failed');
+  assert.match(out.reason, /insufficient funds/);
+  assert.equal(a.db.t.attempts.filter((x) => x.outcome === 'sent').length, 0);
+});
+
+test('malformed instructions are refused before anything is recorded', async () => {
+  const a = await project('A', [['1', 'acct_a1', 0], ['2', 'acct_a2', 0]]);
+  const base = { kind: 'pay_user', fromBuilderId: '1', toBuilderId: '2', amountCents: 5, instructionId: 'okok-0001-q' };
+  const opts = { pool: a.db, processor: a.processor };
+  assert.equal(await code(U.transfer({ ...base, amountCents: 0 }, opts)), 'bad_amount');
+  assert.equal(await code(U.transfer({ ...base, amountCents: 1.5 }, opts)), 'bad_amount');
+  assert.equal(await code(U.transfer({ ...base, toBuilderId: '1' }, opts)), 'self_payment');
+  assert.equal(await code(U.transfer({ ...base, instructionId: 'x' }, opts)), 'bad_instruction_id');
+  assert.equal(await code(U.transfer({ ...base, kind: 'withdraw' }, opts)), 'bad_kind');
+  assert.equal(await code(U.transfer({ ...base, fromBuilderId: '7' }, opts)), 'no_account');
+  assert.equal(await code(U.transfer({ ...base, toBuilderId: '7' }, opts)), 'recipient_has_no_account');
+  assert.equal(a.db.t.transfers.length, 0);
+});
+
+test('TWO PROJECTS: neither can read, link or spend the other balance', async () => {
+  const a = await project('A', [['1', 'acct_a1', 100], ['2', 'acct_a2', 200]]);
+  // project B has its own builders 1 and 3 (ids are per project database)
+  const b = await project('B', [['1', 'acct_b1', 700], ['3', 'acct_b3', 300]]);
+
+  // A cannot link B's account to one of its people: A's processor did not open it
+  assert.equal(await code(U.linkMemberAccount(a.db, { builderId: '1', accountRef: 'acct_b1' }, { processor: a.processor })), 'not_this_projects_account');
+  assert.equal(await code(U.linkMemberAccount(a.db, { builderId: '2', accountRef: 'acct_a1' }, { processor: a.processor })), 'not_this_projects_account');
+
+  // the same builder id reads its OWN project's balance in each project
+  assert.equal((await U.readMyBalance(a.db, '1', { processor: a.processor })).balance_micro, 100);
+  assert.equal((await U.readMyBalance(b.db, '1', { processor: b.processor })).balance_micro, 700);
+  assert.equal((await U.readMyBalance(a.db, '3', { processor: a.processor })).connected, false, "B's member is not a member of A");
+
+  // A's member cannot pay B's member: B's people have no account in A
+  assert.equal(await code(U.transfer({ kind: 'pay_user', fromBuilderId: '1', toBuilderId: '3', amountCents: 50, instructionId: 'cross-0001' },
+    { pool: a.db, processor: a.processor })), 'recipient_has_no_account');
+
+  // a payment in A only ever names A's accounts and only ever reaches A's processor
+  await U.transfer({ kind: 'pay_user', fromBuilderId: '1', toBuilderId: '2', amountCents: 50, instructionId: 'insideA-001' }, { pool: a.db, processor: a.processor });
+  await U.transfer({ kind: 'fund_project', fromBuilderId: '1', amountCents: 50, instructionId: 'fundB-0001' }, { pool: b.db, processor: b.processor });
+  assert.deepEqual(a.processor.calls.map((c) => [c.fromAccount, c.toAccount]), [['acct_a1', 'acct_a2']]);
+  assert.deepEqual(b.processor.calls.map((c) => [c.fromAccount, c.toAccount]), [['acct_b1', null]]);
+  assert.equal(a.db.t.movements.length, 0, "B's funding is not on A's account");
+  assert.equal(b.db.t.movements.length, 1);
+});
+
+// ── the routes ──────────────────────────────────────────────────────────────
+
+test('the payment routes need the person on their own web session', async () => {
+  const api = require('../src/module-api');
+  const build = require('../modules/economy/routes/balances.js');
+  const router = build({ processor: null });
+  const layer = router.stack.find((l) => l.route && l.route.path === '/balances/pay');
+  const handler = layer.route.stack.at(-1).handle;
+  const run = async (req) => {
+    const res = { code: 200, body: null, status(c) { this.code = c; return this; }, json(b) { this.body = b; return this; },
+      fail(c, o) { this.code = o.status; this.body = { error: c }; return this; } };
+    await handler(req, res);
+    return res;
+  };
+  const body = { to_builder_id: '2', amount_cents: 5, instruction_id: 'route-0001' };
+  for (const [what, req] of [
+    ['a CLI session', { builder: { id: '1' }, gdsSession: { source: 'cli', session_id: 1 }, body }],
+    ['a machine principal', { builder: { id: '1', system_role: 'bot' }, gdsSession: { source: 'web', session_id: 1 }, body }],
+    ['no session', { builder: { id: '1' }, body }],
+  ]) {
+    const r = await run(req);
+    assert.equal(r.code, 403, `${what} is refused`);
+    assert.equal(r.body.error, 'personal_session_required');
+  }
+  assert.ok(api.requireBuilder, 'the routes mount requireBuilder from the doorway');
+  assert.ok(layer.route.stack.some((s) => s.handle === api.requireBuilder), 'POST /balances/pay is behind requireBuilder');
+});