@bongos/core 1.23.21 → 1.24.1

package/tests/government_routes.mjs

@@ -104,7 +104,7 @@ test('every /governance route gates via REAL middleware on exactly its PINNED at
   // task 1004712: the treasury is read, and its pots and borrows decided, where the room is (the holder and the seat are the walls).
   // task 1004715: the strictness presets are read where the law book is.
   // task 1004716: the counts are read where the docket they count is.
-  const boardFamily = (key) => key.includes('/board/') || key.includes('/government/asks') || key.endsWith('/government/constitution') || key.endsWith('/government/docket') || key.endsWith('/government/counts') || key.endsWith('/government/laws') || key.endsWith('/government/leads') || key.endsWith('/government/buildouts') || key.includes('/government/treasury') || key.endsWith('/government/presets');
+  const boardFamily = (key) => key.includes('/board/') || key.includes('/government/asks') || key.endsWith('/government/constitution') || key.endsWith('/government/docket') || key.includes('/government/blockers/') || key.endsWith('/government/counts') || key.endsWith('/government/laws') || key.endsWith('/government/leads') || key.endsWith('/government/buildouts') || key.includes('/government/treasury') || key.endsWith('/government/presets');
   for (const r of classified.filter((x) => !boardFamily(x.key))) {
     assert.deepEqual(r.perms, ['government.manage'], `${r.key}: the admin surface gates on the manage atom`);
   }
@@ -149,6 +149,9 @@ const stub = {
   }),
   createRank: async (a) => ({ rank_key: a.rankKey, label: a.label, description: a.description ?? null, is_system: false, seeded_rank: null, created_by: a.createdBy, created_at: 't' }),
   grantRankPermission: async () => true,
+  // task 1004929: the rank-set apply's one-transaction write. The apply tests
+  // swap in the REAL function over a fake SQL store (withRealRankDb below).
+  applyRankSet: async () => new Map(),
   revokeRankPermission: async () => true,
   resetRankGrants: async ({ permissionKeys }) => permissionKeys.length,
   // task 1004481: `deleteAnswer` scripts what the locked delete found.
@@ -265,35 +268,155 @@ test('GET /government/assignments returns builder↔role rows', async () => {
 
 // --- recommended rank sets (task 1004400) -------------------------------------
 
+// task 1004929: the apply is now ONE transaction written by db.applyRankSet. These
+// tests run the REAL route into the REAL db functions, over a small fake of the
+// two tables that understands exactly the statements the old per-row loop and
+// the new batched write send. That is what lets the parity test below run the
+// old loop (tests/fixtures/per-row-loops-legacy.cjs, verbatim) and the new route
+// over the same starting tables and compare the replies AND what was written.
+//
+// `existing` are ranks already there; `race` are ranks another caller creates
+// between this call's read and its insert (invisible to the read, a conflict on
+// the insert) — the case the old loop caught as a 23505.
+function rankStore({ existing = [], race = [], failOnGrant = false } = {}) {
+  let st = { ranks: existing.map((k) => ({ rank_key: k, label: 'Theirs', description: null, created_by: 7 })), grants: [] };
+  let snap = null;
+  const raced = new Set(race);
+  const queries = [];
+  const has = (k) => st.ranks.some((r) => r.rank_key === k);
+  const conflicts = (k) => {
+    if (raced.has(k)) { raced.delete(k); st.ranks.push({ rank_key: k, label: 'Raced', description: null, created_by: 8 }); }
+    return has(k);
+  };
+  const addRank = (k, label, description, createdBy) => {
+    const row = { rank_key: k, label, description: description ?? null, created_by: Number(createdBy) };
+    st.ranks.push(row);
+    return { ...row, is_system: false, seeded_rank: null, created_at: 't' };
+  };
+  const addGrant = (rk, pk) => {
+    if (failOnGrant) throw new Error('grant insert failed');
+    if (st.grants.some((g) => g.rank_key === rk && g.permission_key === pk)) return false;
+    st.grants.push({ rank_key: rk, permission_key: pk });
+    return true;
+  };
+  async function query(sql, p = []) {
+    const s = String(sql).replace(/\s+/g, ' ').trim();
+    queries.push(s);
+    if (s === 'BEGIN') { snap = JSON.parse(JSON.stringify(st)); return { rows: [] }; }
+    if (s === 'COMMIT') { snap = null; return { rows: [] }; }
+    if (s === 'ROLLBACK') { if (snap) st = snap; snap = null; return { rows: [] }; }
+    if (/^SELECT rank_key, label, description, is_system, seeded_rank, created_by, created_at FROM government_ranks WHERE rank_key = \$1$/.test(s)) {
+      return { rows: st.ranks.filter((r) => r.rank_key === p[0]).map((r) => ({ ...r, is_system: false, seeded_rank: null })) };
+    }
+    if (/^INSERT INTO government_ranks \(.*\) VALUES \(\$1, \$2, \$3, false, NULL, \$4\) RETURNING/.test(s)) {
+      if (conflicts(p[0])) throw Object.assign(new Error('duplicate key'), { code: '23505' });
+      return { rows: [addRank(p[0], p[1], p[2], p[3])] };
+    }
+    if (/^INSERT INTO government_rank_permissions \(rank_key, permission_key\) VALUES \(\$1, \$2\) ON CONFLICT/.test(s)) {
+      return { rows: [], rowCount: addGrant(p[0], p[1]) ? 1 : 0 };
+    }
+    if (/^SELECT rank_key FROM government_ranks WHERE rank_key = ANY\(\$1::text\[\]\)$/.test(s)) {
+      return { rows: st.ranks.filter((r) => p[0].includes(r.rank_key)).map((r) => ({ rank_key: r.rank_key })) };
+    }
+    if (/^INSERT INTO government_ranks .* FROM unnest\(\$1::text\[\], \$2::text\[\], \$3::text\[\]\) WITH ORDINALITY .* ORDER BY r\.ord ON CONFLICT DO NOTHING RETURNING rank_key$/.test(s)) {
+      const rows = [];
+      p[0].forEach((k, i) => { if (!conflicts(k)) { addRank(k, p[1][i], p[2][i], p[3]); rows.push({ rank_key: k }); } });
+      return { rows };
+    }
+    if (/^INSERT INTO government_rank_permissions .* FROM unnest\(\$1::text\[\], \$2::text\[\]\) WITH ORDINALITY .* ORDER BY g\.ord ON CONFLICT \(rank_key, permission_key\) DO NOTHING RETURNING rank_key, permission_key$/.test(s)) {
+      const rows = [];
+      p[0].forEach((rk, i) => { if (addGrant(rk, p[1][i])) rows.push({ rank_key: rk, permission_key: p[1][i] }); });
+      return { rows };
+    }
+    throw new Error(`rank store: unhandled statement: ${s.slice(0, 120)}`);
+  }
+  return { query, client: { query, release() {} }, queries, get state() { return JSON.parse(JSON.stringify(st)); } };
+}
+
+// Point the REAL government db functions at a rankStore for the length of `fn`.
+const pgPool = require(path.join(ROOT, 'src', 'bongos', 'pool.js')).pool;
+const RANK_DB_FNS = ['getRankByKey', 'createRank', 'grantRankPermission', 'applyRankSet'];
+async function withRealRankDb(store, fn) {
+  const saved = Object.fromEntries(RANK_DB_FNS.map((k) => [k, stub[k]]));
+  const own = { query: Object.prototype.hasOwnProperty.call(pgPool, 'query'), connect: Object.prototype.hasOwnProperty.call(pgPool, 'connect') };
+  const realQuery = pgPool.query;
+  const realConnect = pgPool.connect;
+  for (const k of RANK_DB_FNS) stub[k] = REAL[k];
+  pgPool.query = store.query;
+  pgPool.connect = async () => store.client;
+  try { return await fn(); } finally {
+    Object.assign(stub, saved);
+    if (own.query) pgPool.query = realQuery; else delete pgPool.query;
+    if (own.connect) pgPool.connect = realConnect; else delete pgPool.connect;
+  }
+}
+
 test('POST /government/rank-sets/apply creates the missing ranks with their grants and leaves existing ones alone', async () => {
-  const realGet = stub.getRankByKey;
   // 'design-lead' already exists: it must be skipped, never re-granted.
-  stub.getRankByKey = async (k) => (k === 'design-lead' ? { rank_key: k, label: 'Mine', is_system: false, seeded_rank: null } : null);
-  try {
-    const r = await call('POST', '/government/rank-sets/apply', { type: 'game', headcount: 20 });
-    assert.equal(r.status, 200);
-    assert.deepEqual(r.json.skipped, [{ rank_key: 'design-lead', label: 'Design lead' }], 'a kept rank is named by its label, not its key (task 1004478)');
-    assert.deepEqual(r.json.created.map((c) => c.rank_key), ['playtester']);
-    const creates = calls.filter(([k]) => k === 'createRank');
-    assert.equal(creates.length, 1);
-    assert.equal(creates[0][1].createdBy, 42, 'created_by is the session builder');
-    const grants = calls.filter(([k]) => k === 'grantRankPermission').map(([, a]) => a);
-    assert.ok(grants.length > 0 && grants.every((g) => g.rankKey === 'playtester'), 'an existing rank is never re-granted');
-    assert.ok(grants.every((g) => catalog.isGrantableTo(g.permissionKey, { is_system: false, seeded_rank: null })));
-  } finally { stub.getRankByKey = realGet; }
+  const store = rankStore({ existing: ['design-lead'] });
+  const r = await withRealRankDb(store, () => call('POST', '/government/rank-sets/apply', { type: 'game', headcount: 20 }));
+  assert.equal(r.status, 200);
+  assert.deepEqual(r.json.skipped, [{ rank_key: 'design-lead', label: 'Design lead' }], 'a kept rank is named by its label, not its key (task 1004478)');
+  assert.deepEqual(r.json.created.map((c) => c.rank_key), ['playtester']);
+  const { ranks, grants } = store.state;
+  assert.deepEqual(ranks.map((x) => [x.rank_key, x.label, x.created_by]), [['design-lead', 'Theirs', 7], ['playtester', 'Playtester', 42]],
+    'the kept rank is untouched and created_by is the session builder');
+  assert.ok(grants.length > 0 && grants.every((g) => g.rank_key === 'playtester'), 'an existing rank is never re-granted');
+  assert.ok(grants.every((g) => catalog.isGrantableTo(g.permission_key, { is_system: false, seeded_rank: null })));
+  assert.deepEqual(r.json.created[0].permissions, grants.map((g) => g.permission_key), 'the reply names exactly what was granted');
+  assert.equal(store.queries.filter((q) => q === 'BEGIN').length, 1, 'one transaction');
+  assert.equal(store.queries.filter((q) => /^INSERT/.test(q)).length, 2, 'one rank insert and one grant insert, however many grants');
 });
 
 test('POST /government/rank-sets/apply needs a headcount and does nothing at founding size', async () => {
   const bad = await call('POST', '/government/rank-sets/apply', { type: 'game' });
   assert.equal(bad.status, 400);
-  const realGet = stub.getRankByKey;
-  stub.getRankByKey = async () => null;
-  try {
-    const solo = await call('POST', '/government/rank-sets/apply', { type: 'game', headcount: 1 });
-    assert.equal(solo.status, 200);
-    assert.deepEqual(solo.json.created, []);
-    assert.equal(calls.filter(([k]) => k === 'createRank').length, 0);
-  } finally { stub.getRankByKey = realGet; }
+  const store = rankStore();
+  const solo = await withRealRankDb(store, () => call('POST', '/government/rank-sets/apply', { type: 'game', headcount: 1 }));
+  assert.equal(solo.status, 200);
+  assert.deepEqual(solo.json.created, []);
+  assert.deepEqual(store.queries, [], 'an empty set touches nothing');
+});
+
+test('POST /government/rank-sets/apply: a failure part-way writes NOTHING (one transaction)', async () => {
+  const store = rankStore({ failOnGrant: true });
+  const r = await withRealRankDb(store, () => call('POST', '/government/rank-sets/apply', { type: 'business', headcount: 200 }));
+  assert.equal(r.status, 500);
+  assert.deepEqual(r.json.error.details, { created: [], skipped: [] }, 'nothing was written, so nothing is reported as added');
+  assert.deepEqual(store.state, { ranks: [], grants: [] }, 'the ranks inserted before the failure are rolled back');
+  assert.ok(store.queries.includes('ROLLBACK'));
+});
+
+test('POST /government/rank-sets/apply: the batched write gives the SAME reply and tables as the old per-row loop', async () => {
+  const legacy = require(path.join(ROOT, 'tests', 'fixtures', 'per-row-loops-legacy.cjs'));
+  const recommendations = require(path.join(ROOT, 'modules', 'government', 'recommendations.js'));
+  const realDb = { getRankByKey: REAL.getRankByKey, createRank: REAL.createRank, grantRankPermission: REAL.grantRankPermission };
+  let compared = 0;
+  for (const { key: type } of recommendations.PROJECT_TYPES) {
+    for (const headcount of [1, 5, 20, 80, 200]) {
+      const keys = recommendations.recommendedRankSet(type, headcount).ranks.map((x) => x.rank_key);
+      const scenarios = {
+        'nothing there yet': {},
+        'the first rank exists': { existing: keys.slice(0, 1) },
+        'every rank exists': { existing: keys },
+        'the last rank is created by someone else mid-call': { race: keys.slice(-1) },
+      };
+      for (const [name, opts] of Object.entries(scenarios)) {
+        const label = `${type} × ${headcount}: ${name}`;
+        const oldStore = rankStore(opts);
+        const old = await withRealRankDb(oldStore, () => legacy.legacyApplyRankSet({
+          db: realDb, catalog, rankSet: recommendations.recommendedRankSet(type, headcount), builderId: 42,
+        }));
+        const newStore = rankStore(opts);
+        const neu = await withRealRankDb(newStore, () => call('POST', '/government/rank-sets/apply', { type, headcount }));
+        assert.equal(neu.status, 200, label);
+        assert.deepEqual({ created: neu.json.created, skipped: neu.json.skipped }, old, `${label}: the same reply`);
+        assert.deepEqual(newStore.state, oldStore.state, `${label}: the same ranks and grants written, in the same order`);
+        compared += 1;
+      }
+    }
+  }
+  assert.ok(compared >= 20, `compared ${compared} cases`);
 });
 
 // --- create role -------------------------------------------------------------

package/tests/grader.mjs

@@ -789,6 +789,37 @@ test('buildContextBundle reads changed files once, skips binaries/missing, respe
   assert.equal(bundle.total_chars, files['src/a.js'].length + files['docs/b.md'].length);
 });
 
+// task 1004932 — the bundle rides in EVERY worker prompt, so its total is capped at
+// 60k chars (was 120k), and it is filled most-changed first so the cap drops the
+// lightly touched files, never the heart of the change.
+const CAP_FILE = 15_000; // under the 16k per-file cap, so nothing truncates
+function capFiles(names) { return Object.fromEntries(names.map((n) => [n, `// ${n}\n` + 'x'.repeat(CAP_FILE)])); }
+function diffAdding(counts) {
+  return Object.entries(counts).map(([f, n]) =>
+    `diff --git a/${f} b/${f}\n--- a/${f}\n+++ b/${f}\n@@ -1 +1,${n} @@\n` +
+    Array.from({ length: n }, (_, i) => `+const line_${i}_of_${f.replace(/\W/g, '_')} = ${i};`).join('\n')).join('\n');
+}
+
+test('buildContextBundle caps the shared bundle at 60k chars (task 1004932)', () => {
+  const names = ['a.js', 'b.js', 'c.js', 'd.js', 'e.js'];
+  const files = capFiles(names);
+  const bundle = grader.buildContextBundle({ changedFiles: names, cwd: '/r', fsImpl: fakeFsFor(files) });
+  assert.ok(bundle.total_chars <= 60_000, `bundle is ${bundle.total_chars} chars — over the 60k cap`);
+  assert.ok(bundle.total_chars > 45_000, 'the cap is not lower than 60k: three ~15k files still fit');
+  assert.deepEqual(bundle.files.map((f) => f.file), ['a.js', 'b.js', 'c.js'], 'no diff: the caller order is kept');
+  assert.deepEqual(bundle.skipped, ['d.js', 'e.js'], 'what does not fit is named in skipped, never silent');
+});
+
+test('buildContextBundle fills most-changed first, so the cap drops the lightly touched files (task 1004932)', () => {
+  const names = ['docs/index.md', 'docs/map.md', 'tests/x.mjs', 'README.md', 'src/heart.js'];
+  const files = capFiles(names);
+  const diff = diffAdding({ 'docs/index.md': 1, 'docs/map.md': 1, 'tests/x.mjs': 20, 'README.md': 2, 'src/heart.js': 60 });
+  const bundle = grader.buildContextBundle({ changedFiles: names, cwd: '/r', diff, fsImpl: fakeFsFor(files) });
+  assert.deepEqual(bundle.files.map((f) => f.file), ['src/heart.js', 'tests/x.mjs', 'README.md'],
+    'the file the diff is mostly about comes first, even when it is listed last');
+  assert.deepEqual(bundle.skipped, ['docs/index.md', 'docs/map.md'], 'ties keep their listed order, and one-line touches are what falls off');
+});
+
 test('buildContextBundle truncates oversized files and marks them', () => {
   const big = 'x'.repeat(20_000);
   const bundle = grader.buildContextBundle({

package/tests/hall_ai_studio.mjs

@@ -0,0 +1,347 @@
+// tests/hall_ai_studio.mjs — the studio's AI pages, /builders/ai-studio (task
+// 1004921, goal 1000136, ADR 0392), built on option C of the AI Studio options
+// canvas plus the owner's addition: the result's request can be changed and
+// made again.
+//
+// Three halves:
+//   1. The pure rules (ai-studio-lib.js): money in words (sub-cent prices to
+//      four decimals, a balance rounded down), the receipt in its three forms,
+//      the month's summary, the waiting checklist, the route, the reply's safe
+//      markup, and the home's line.
+//   2. The REAL page (ai-studio.js) in a vm over a small fake DOM and a stub
+//      client that answers from the hall-preview fixtures (the same shapes the
+//      ai-studio routes send): each view paints its words, step 3 sends the
+//      request on the card pressed, and "Make it again" sends the CHANGED words
+//      on fresh copies of the earlier uploads, paid the same way.
+//   3. The walls: the page writes through three routes only, never asks for a
+//      key, and the studio home shows its AI door only where the module is on.
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PUB = path.join(ROOT, 'modules', 'hall-ui', 'public');
+const FIX = path.join(ROOT, 'scripts', 'hall-preview', 'fixtures');
+const lib = require(path.join(PUB, 'ai-studio-lib.js'));
+const { escapeHtml } = require(path.join(ROOT, 'src', 'html-escape.js'));
+const fixture = (name) => JSON.parse(fs.readFileSync(path.join(FIX, `${name}.json`), 'utf8'));
+// The harness writes relative dates ("@-0.1d"); here every one is an hour ago.
+const HOUR_AGO = new Date(Date.now() - 3600 * 1000).toISOString();
+const dated = (v) => JSON.parse(JSON.stringify(v), (k, x) => (typeof x === 'string' && /^@[-+]/.test(x) ? HOUR_AGO : x));
+
+// ---- 1. the pure rules --------------------------------------------------------
+
+test('money: sub-cent prices keep four decimals, whole cents two, a balance rounds down', () => {
+  assert.equal(lib.usd(42100), '$0.0421');
+  assert.equal(lib.usd(500000), '$0.50');
+  assert.equal(lib.usd(20910000), '$20.91');
+  assert.equal(lib.usd(-2600000), '−$2.60');
+  assert.equal(lib.usd(3100), '$0.0031');
+  assert.equal(lib.balanceUsd(12357900), '$12.35', 'a balance never shows a cent that is not there');
+  assert.equal(lib.balanceUsd(12400000), '$12.40');
+  assert.equal(lib.usd(null), '');
+});
+
+test('the receipt: our key splits the provider and our markup; an own key charges nothing', () => {
+  const done = dated(fixture('ai-studio__requests__done')).request;
+  const ours = lib.receipt(done, 1.08);
+  assert.deepEqual(ours.rows, [['Paid with', 'your balance'], ['OpenRouter', '$0.0390'], ['Our 8%', '$0.0031'], ['You paid', '$0.0421']]);
+  const gemini = lib.receipt(dated(fixture('ai-studio__requests__own')).request, 1.08);
+  assert.deepEqual(gemini.rows, [['Paid with', 'your own Gemini key'], ['Cost', 'not reported']]);
+  assert.match(gemini.note, /We charged nothing/);
+  const openrouter = lib.receipt({ status: 'done', key_source: 'own', provider_cost_micro: 39000 }, 1.08);
+  assert.deepEqual(openrouter.rows, [['Paid with', 'your own OpenRouter key'], ['Cost', '$0.0390']]);
+  assert.deepEqual(lib.receipt(dated(fixture('ai-studio__requests__failed')).request, 1.08).rows, [], 'a failed run has no receipt');
+});
+
+test('the month: added, spent, money back and own-key requests, from the ledger', () => {
+  const bal = dated(fixture('ai-studio__balance'));
+  const sum = lib.monthSummary(bal.ledger, new Date());
+  assert.deepEqual(sum.lines.map((l) => [l.label, l.value]), [
+    ['Added', '+$15.00'],
+    ['Spent on 2 requests', '−$0.0833'],
+    ['Money back from 1 failed request', '$0.50 returned'],
+    ['On your own keys, 1 request', 'free'],
+  ]);
+  const old = lib.monthSummary([{ kind: 'topup', amount_micro: 5000000, created_at: '2001-01-01T00:00:00Z' }], new Date());
+  assert.deepEqual(old.lines, [], 'another month does not count');
+});
+
+test('the waiting lines follow the status and the clock; the clock reads m:ss', () => {
+  assert.deepEqual(lib.waitSteps('queued', 0, 3).map((s) => s.state), ['now', 'later', 'later']);
+  assert.deepEqual(lib.waitSteps('running', 5, 3).map((s) => s.state), ['done', 'now', 'later']);
+  assert.deepEqual(lib.waitSteps('running', lib.ANSWER_AFTER_SEC, 1).map((s) => [s.text, s.state]), [
+    ['Read your file', 'done'], ['Wrote the answer', 'done'], ['Drawing the pictures', 'now'],
+  ]);
+  assert.equal(lib.clock(34), '0:34');
+  assert.equal(lib.clock(75), '1:15');
+});
+
+test('the route, the files, the reply and the home line', () => {
+  assert.deepEqual(lib.routeOf('?request=1002'), { view: 'request', id: '1002' });
+  assert.deepEqual(lib.routeOf('?view=balance&all=1'), { view: 'balance', all: true });
+  assert.deepEqual(lib.routeOf('?step=make&from=7'), { view: 'step', step: 'make', from: '7' });
+  assert.deepEqual(lib.routeOf('?step=nope&from=x'), { view: 'step', step: 'pick', from: null });
+  assert.equal(lib.checkFile({ type: 'image/png', size: 100 }, 0), null);
+  assert.match(lib.checkFile({ type: 'image/svg+xml', size: 100 }, 0), /PNG, JPG/);
+  assert.match(lib.checkFile({ type: 'image/png', size: lib.MAX_IMAGE_BYTES + 1 }, 0), /4 MB/);
+  assert.match(lib.checkFile({ type: 'application/pdf', size: 100 }, lib.MAX_FILES), /up to 6/);
+  assert.equal(lib.replyHtml('Hi **there**\n\n<script>x</script>', escapeHtml), '<p>Hi <b>there</b></p><p>&lt;script&gt;x&lt;/script&gt;</p>');
+  assert.equal(lib.replyHtml('<b>x</b>'), '', 'no escaper, no markup: never unescaped text');
+  assert.equal(lib.homeLine([{ id: '9', status: 'running' }]).href, '/builders/ai-studio?request=9');
+  assert.equal(lib.homeLine([{ id: '9', status: 'done', finished_at: new Date().toISOString() }]).detail, 'your newest pictures are ready');
+  assert.equal(lib.homeLine([]).detail, 'sketches in, ideas and pictures out');
+  assert.equal(lib.againLine(3), 'Change the words and make it again. Same 3 files, paid the same way.');
+});
+
+test('step 3 offers the own key only when one is saved, and says when the balance is short', () => {
+  const keys = fixture('ai-studio__keys');
+  const bal = dated(fixture('ai-studio__balance'));
+  const c = lib.payChoices(keys, bal);
+  assert.deepEqual([c.own.name, c.own.billedBy, c.own.last4, c.left, c.setAside, c.short], ['Gemini', 'Google', '9c1d', '$12.40 left', '$0.50', false]);
+  // OpenRouter wins when both are saved, as keys.chooseKey prefers it. (Built
+  // here: the harness scrubber blanks that provider name out of fixtures.)
+  const both = { keys: [{ provider: 'openrouter', set: true, last4: '4f2a' }, { provider: 'gemini', set: true, last4: '9c1d' }] };
+  assert.deepEqual([lib.ownKey(both).name, lib.ownKey(both).billedBy, lib.ownKey(both).last4], ['OpenRouter', 'OpenRouter', '4f2a']);
+  assert.equal(lib.payChoices({ keys: [] }, bal).own, null);
+  assert.equal(lib.payChoices(keys, { ...bal, balance: { available_micro: 100000, held_micro: 0 } }).short, true);
+  assert.equal(lib.payChoices(keys, { ...bal, balance: null }).payments, false);
+});
+
+// ---- 2. the real page in a vm ------------------------------------------------
+
+// A fake element: enough of the DOM for ai-studio.js. innerHTML is kept as a
+// string, and the elements a view wires are found in that string by id or by
+// data attribute, so a click runs the page's real handler.
+function makeEl(id) {
+  const el = {
+    id, _html: '', value: '', hidden: false, disabled: false, attrs: {}, handlers: {}, children: {},
+    classList: { add() {}, remove() {} },
+    get innerHTML() { return el._html; },
+    set innerHTML(v) { el._html = String(v); el.children = {}; },
+    get innerText() { return el._html.replace(/<[^>]+>/g, ' '); },
+    setAttribute(k, v) { el.attrs[k] = String(v); },
+    getAttribute(k) { return k in el.attrs ? el.attrs[k] : null; },
+    removeAttribute(k) { delete el.attrs[k]; },
+    addEventListener(type, fn) { (el.handlers[type] = el.handlers[type] || []).push(fn); },
+    focus() {},
+    async fire(type, extra = {}) {
+      const ev = { preventDefault() {}, currentTarget: el, target: el, ...extra };
+      for (const fn of el.handlers[type] || []) await fn(ev);
+    },
+    querySelector(sel) {
+      const id2 = /^#([\w-]+)$/.exec(sel);
+      if (id2 && el._html.includes(`id="${id2[1]}"`)) return el.children[sel] || (el.children[sel] = makeEl(id2[1]));
+      if (sel === '[data-head]' && el._html.includes('data-head')) return el.children[sel] || (el.children[sel] = makeEl('head'));
+      return null;
+    },
+    querySelectorAll(sel) {
+      const attr = /^\[(data-[\w-]+)\]$/.exec(sel);
+      if (!attr) return [];
+      const key = `all:${sel}`;
+      if (!el.children[key]) {
+        const re = new RegExp(`${attr[1]}="([^"]*)"`, 'g');
+        el.children[key] = [...el._html.matchAll(re)].map((m) => { const c = makeEl(''); c.attrs[attr[1]] = m[1]; return c; });
+      }
+      return el.children[key];
+    },
+  };
+  return el;
+}
+
+const settle = async () => { for (let i = 0; i < 30; i++) await new Promise((r) => setImmediate(r)); };
+
+function bootPage(search, { routes = {} } = {}) {
+  const els = { 'ais-page': makeEl('ais-page'), 'hall-main': makeEl('hall-main'), 'ais-file': makeEl('ais-file') };
+  const calls = [];
+  const store = new Map();
+  const loc = { search, href: `/builders/ai-studio${search}` };
+  const answers = {
+    'GET /api/bongos/me': { builder: { id: 1 } },
+    'GET /api/bongos/ai-studio/status': { ok: true },
+    'GET /api/bongos/ai-studio/keys': fixture('ai-studio__keys'),
+    'GET /api/bongos/ai-studio/balance': dated(fixture('ai-studio__balance')),
+    'GET /api/bongos/ai-studio/requests': dated(fixture('ai-studio__requests')),
+    'GET /api/bongos/ai-studio/requests/1001': dated(fixture('ai-studio__requests__done')),
+    'GET /api/bongos/ai-studio/requests/1002': dated(fixture('ai-studio__requests__running')),
+    'GET /api/bongos/ai-studio/requests/1003': dated(fixture('ai-studio__requests__failed')),
+    'GET /api/bongos/ai-studio/requests/1004': dated(fixture('ai-studio__requests__own')),
+    'GET /api/bongos/ai-studio/topup/quote': fixture('ai-studio__topup__quote'),
+    'POST /api/bongos/ai-studio/requests': dated(fixture('ai-studio__requests.post')),
+    'POST /api/bongos/ai-studio/topup': fixture('ai-studio__topup.post'),
+    ...routes,
+  };
+  let uploadSeq = 700;
+  const client = {
+    async request(method, url, opts = {}) {
+      calls.push({ method, url, body: opts.body });
+      if (method === 'POST' && url === '/api/bongos/ai-studio/uploads') {
+        uploadSeq += 1;
+        return { ok: true, status: 201, data: { file: { id: String(uploadSeq), role: 'upload', name: opts.body.name, content_type: opts.body.content_type, size_bytes: 10, url: `/api/bongos/ai-studio/files/${uploadSeq}` } } };
+      }
+      const key = `${method} ${url.split('?')[0]}`;
+      if (!(key in answers)) return { ok: false, status: 404, data: { error: { code: 'not_found' } } };
+      const a = answers[key];
+      if (a && a.__status) return { ok: false, status: a.__status, data: a.body };
+      return { ok: true, status: 200, data: a };
+    },
+  };
+  const ctx = {
+    console,
+    URLSearchParams,
+    setTimeout,
+    clearTimeout,
+    setInterval: () => 0,
+    clearInterval: () => {},
+    Date,
+    Promise,
+    document: { getElementById: (id) => els[id] || null, body: makeEl('body') },
+    location: loc,
+    history: {
+      pushState(_s, _t, url) { loc.href = url; loc.search = url.includes('?') ? url.slice(url.indexOf('?')) : ''; },
+      replaceState(_s, _t, url) { loc.href = url; loc.search = url.includes('?') ? url.slice(url.indexOf('?')) : ''; },
+    },
+    sessionStorage: { getItem: (k) => (store.has(k) ? store.get(k) : null), setItem: (k, v) => store.set(k, String(v)) },
+    fetch: async (url) => { calls.push({ method: 'FETCH', url }); return { ok: true, blob: async () => ({ size: 3, type: 'image/png' }) }; },
+    FileReader: class { readAsDataURL() { this.result = 'data:image/png;base64,QUJD'; setImmediate(() => this.onload()); } },
+    addEventListener() {},
+  };
+  ctx.window = ctx;
+  ctx.window.BongosClient = { createClient: () => client };
+  ctx.window.OTB = { toast: () => {}, escapeHtml };
+  vm.createContext(ctx);
+  for (const f of ['studio-lib.js', 'ai-studio-lib.js', 'ai-studio.js']) {
+    const src = f === 'studio-lib.js' ? 'window.OTBStudioLib = { skyAt: () => "night" };' : fs.readFileSync(path.join(PUB, f), 'utf8');
+    vm.runInContext(src, ctx, { filename: f });
+  }
+  return { els, page: els['ais-page'], main: els['hall-main'], calls, loc, store };
+}
+
+test('page: step 1 opens on an earlier request\'s files, carried by address, with Next', async () => {
+  const p = bootPage('?step=pick&from=1001');
+  await settle();
+  assert.match(p.page.innerHTML, /What are you starting from\?/);
+  assert.match(p.page.innerHTML, /hero-sketch\.png/);
+  assert.match(p.page.innerHTML, /mood-board\.pdf/);
+  assert.match(p.page.innerHTML, /3 files ready/);
+  assert.match(p.page.innerHTML, /1 Pick<\/span>/);
+  assert.equal(p.main.getAttribute('data-view'), 'pick');
+});
+
+test('page: step 3 sends the request on the card pressed, with copies of the carried files', async () => {
+  const p = bootPage('?step=make&from=1001');
+  await settle();
+  assert.match(p.page.innerHTML, /How do you want to pay\?/);
+  assert.match(p.page.innerHTML, /Gemini key ending 9c1d/);
+  assert.match(p.page.innerHTML, /Free here\. Google bills you for it directly\./);
+  assert.match(p.page.innerHTML, /Up to \$0\.50 is set aside, and the rest comes back\./);
+  assert.match(p.page.innerHTML, /\$12\.40 left/);
+  const ours = p.page.querySelectorAll('[data-pay]').find((b) => b.getAttribute('data-pay') === 'ours');
+  await ours.fire('click');
+  await settle();
+  const uploads = p.calls.filter((c) => c.method === 'POST' && c.url.endsWith('/ai-studio/uploads'));
+  assert.equal(uploads.length, 3, 'a file goes with one request only, so each carried file is uploaded again');
+  const sent = p.calls.find((c) => c.method === 'POST' && c.url.endsWith('/ai-studio/requests'));
+  assert.equal(sent.body.pay_with, 'ours');
+  assert.equal(JSON.stringify(sent.body.file_ids), JSON.stringify(['701', '702', '703']));
+  assert.equal(p.loc.search, '?request=1002', 'the request\'s own page opens');
+  assert.match(p.page.innerHTML, /usually done in about a minute/);
+  assert.equal(p.main.getAttribute('data-making'), 'on', 'the lamp is on while it runs');
+});
+
+test('page: the result shows the picture, the receipt, and makes it again with the CHANGED words', async () => {
+  const p = bootPage('?request=1001');
+  await settle();
+  const html = p.page.innerHTML;
+  assert.match(html, /class="ais-big" src="\/api\/bongos\/ai-studio\/files\/511"/);
+  assert.match(html, /lit it from the lamp<\/b>/);
+  assert.match(html, /Your request/);
+  assert.match(html, /Same 3 files, paid the same way\./);
+  assert.match(html, /Our 8%/);
+  assert.match(html, /\$0\.0421/);
+  assert.equal(p.main.getAttribute('data-view'), 'result');
+  const box = p.page.querySelector('#ais-again');
+  assert.match(box.value, /^Turn the sketch/, 'the box holds the request as it was sent');
+  box.value = 'Warmer lamp, pinker glow.';
+  await p.page.querySelector('#ais-remake').fire('click');
+  await settle();
+  const sent = p.calls.find((c) => c.method === 'POST' && c.url.endsWith('/ai-studio/requests'));
+  assert.equal(sent.body.prompt, 'Warmer lamp, pinker glow.');
+  assert.equal(sent.body.pay_with, 'ours', 'paid the same way');
+  assert.equal(sent.body.file_ids.length, 3);
+  const fetched = p.calls.filter((c) => c.method === 'FETCH').map((c) => c.url);
+  assert.deepEqual(fetched, ['/api/bongos/ai-studio/files/501', '/api/bongos/ai-studio/files/502', '/api/bongos/ai-studio/files/503'], 'only the uploads are copied, never the outputs');
+});
+
+test('page: "Change files" carries the request\'s files and the edited words into step 1', async () => {
+  const p = bootPage('?request=1004');
+  await settle();
+  assert.match(p.page.innerHTML, /your own Gemini key/);
+  p.page.querySelector('#ais-again').value = 'Same, but at dawn.';
+  await p.page.querySelector('#ais-change').fire('click');
+  await settle();
+  assert.equal(p.loc.search, '?step=pick');
+  assert.match(p.page.innerHTML, /3 files ready/);
+  const draft = JSON.parse(p.store.get('otb.ai-studio.draft'));
+  assert.equal(draft.prompt, 'Same, but at dawn.');
+});
+
+test('page: a failed run says why, shows no receipt, and keeps the request to try again', async () => {
+  const p = bootPage('?request=1003');
+  await settle();
+  assert.match(p.page.innerHTML, /did not answer in time\. You were not charged\./);
+  assert.doesNotMatch(p.page.innerHTML, /ais-receipt/);
+  assert.match(p.page.innerHTML, /Same file, paid the same way\./);
+});
+
+test('page: the balance shows what is left, the card charge before paying, and the month', async () => {
+  const p = bootPage('?view=balance');
+  await settle();
+  const html = p.page.innerHTML;
+  assert.match(html, /\$12\.40<\/span> <span class="ais-soft">left/);
+  assert.match(html, /Add how much\?/);
+  assert.match(html, /Test mode: no real money moves\./);
+  assert.match(html, /Money back from 1 failed request/);
+  assert.equal(p.page.querySelector('#ais-quote').textContent, '$20.00 lands in your balance; your card is charged $20.91.');
+  await p.page.querySelector('#ais-add').fire('click');
+  await settle();
+  const top = p.calls.find((c) => c.method === 'POST' && c.url.endsWith('/ai-studio/topup'));
+  assert.equal(JSON.stringify(top.body), JSON.stringify({ amount_usd: 20 })); // vm-born: compare through JSON
+});
+
+test('page: the module off says so, and calls nothing else', async () => {
+  const p = bootPage('?step=pick', { routes: { 'GET /api/bongos/ai-studio/status': { __status: 404, body: {} } } });
+  await settle();
+  assert.match(p.page.innerHTML, /not switched on for this project/);
+  assert.ok(!p.calls.some((c) => c.url.includes('/ai-studio/keys') || c.method === 'POST'));
+});
+
+// ---- 3. the walls -------------------------------------------------------------
+
+test('walls: the page writes through three routes only, and never asks for a key', () => {
+  const js = fs.readFileSync(path.join(PUB, 'ai-studio.js'), 'utf8');
+  const html = fs.readFileSync(path.join(PUB, 'ai-studio.html'), 'utf8');
+  const writes = [...js.matchAll(/api\.request\('(POST|PUT|PATCH|DELETE)',\s*([^,]+),/g)].map((m) => m[2].trim());
+  assert.ok(writes.length >= 3);
+  for (const w of writes) assert.match(w, /^WRITE_ROUTES\.(upload|request|topup)\(\)$/, `a write outside the allowlist: ${w}`);
+  const block = /const WRITE_ROUTES = Object\.freeze\(\{([\s\S]*?)\}\);/.exec(js)[1];
+  assert.deepEqual([...block.matchAll(/^\s*(\w+):/gm)].map((m) => m[1]), ['upload', 'request', 'topup']);
+  assert.doesNotMatch(js + html, /type="password"|ai-studio\/keys\/|\bkey:\s*[a-z]/i, 'a key is entered only in Settings');
+  assert.match(js, /\/builders\/settings#ai-keys/, 'the page points at Settings for a key');
+});
+
+test('walls: the studio home shows the AI door only where the module is on', () => {
+  const js = fs.readFileSync(path.join(PUB, 'studio.js'), 'utf8');
+  const html = fs.readFileSync(path.join(PUB, 'studio.html'), 'utf8');
+  assert.match(html, /<a class="st-action" id="st-ai" href="\/builders\/ai-studio" hidden>/);
+  assert.match(html, /<span class="st-action__label">Make something with AI<\/span>/);
+  assert.match(html, /id="st-ai-balance"[^>]*hidden/);
+  assert.match(js, /mods\.enabled\['ai-studio'\] !== true\) return;/, 'off by default: a missing flag hides the door');
+  assert.match(js, /loadAi\(\)\]/);
+});

package/tests/hall_city.mjs

@@ -289,6 +289,14 @@ test('the city sits in the hall chrome, behind the shell\'s full-screen switch',
   // gov-feeds.js, its one reader per page (shared with the shell's tally), load before it
   // task 1004702: the card answers its first ask in place, so the deck's card and sender (and the desk rows under them) load before the page
   assert.deepEqual(scripts, ['dom-utils', 'shell-trail', 'craft-mode', 'shell', 'palette', 'gov-living', 'gov-feeds', 'city-draw', 'hall-kit', 'street-draw', 'street-card', 'street-inside', 'street-desk', 'street-deck', 'city-decide', 'city-switchboard', 'city'], 'the shell first, as on every hall page');
+  // task 1004925: every script but dom-utils.js is deferred, so none holds up the
+  // parser; defer runs them in document order, which is why the order above still
+  // holds. dom-utils.js stays synchronous: the one-escaper guard
+  // (scripts/bongos/escape-helper-guard.js) requires window.OTB before anything runs.
+  const tags = [...html.matchAll(/<script\b[^>]*>/g)].map((m) => m[0]);
+  assert.equal(tags.length, scripts.length, 'no inline script runs ahead of the deferred ones');
+  assert.doesNotMatch(tags[0], /\b(defer|async)\b/, 'dom-utils.js loads synchronously, first');
+  for (const tag of tags.slice(1)) assert.match(tag, /\sdefer(?=[\s>])/, `${tag} is deferred`);
   const css = read('city.css').replace(/\/\*[\s\S]*?\*\//g, '');
   assert.match(css, /\.city-main \{ position: fixed; top: var\(--topbar-h, 56px\); left: var\(--sidebar-w-rail, 64px\);[^}]*contain: layout paint;/);
   assert.match(css, /html\[data-fullscreen="on"\] \.city-main \{ top: 0; left: 0; \}/);

package/tests/hall_page_gate_map.mjs

@@ -74,6 +74,9 @@ const ORACLE = {
   // task 1004321 (BV2.TW10): the tweak editor, on the studio's own tier. Its read
   // is any-builder like the .docx download; every write is the page holder's only.
   '/builders/tweak-editor': 'requireBuilderPage',
+  // task 1004921 (goal 1000136): the studio's AI pages, on the studio's tier.
+  // Every read and write behind it is the viewer's own (the ai-studio routes).
+  '/builders/ai-studio': 'requireBuilderPage',
   '/builders/ideas': 'requireBuilderPage',
   // THE ROOM (task 1004098 / BV2.R03) — a builder's own idea trail. Sign-in and
   // no rank floor, the tier /ideas sits on: there is no permission gate on