@bongos/core 1.23.21 → 1.24.1

package/tests/ai_studio_billing.mjs

@@ -0,0 +1,253 @@
+// tests/ai_studio_billing.mjs — what an AI generation costs, and the order
+// money moves in (task 1004920, goal 1000136, ADR 0392):
+//   - price = provider cost x 1.08, in integer micro-dollars, never shaved;
+//   - a top-up adds the processor's fee so the asked-for amount arrives whole;
+//   - the full price is HELD before the call, a short balance refuses and the
+//     call never runs, the real price is captured after, and a provider failure
+//     releases the whole hold;
+//   - the default backend refuses money entirely, and the ledger is append-only.
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+import fs from 'node:fs';
+
+const require = createRequire(import.meta.url);
+const P = require('../modules/ai-studio/pricing.js');
+const payments = require('../modules/ai-studio/payments.js');
+const { runPaid, BillingRefusal } = require('../modules/ai-studio/billing.js');
+const S = require('../modules/ai-studio/studio.js');
+
+const USD = P.MICRO_PER_USD;
+
+// ---- pricing arithmetic ----------------------------------------------------
+
+test('the multiplier is the owner\'s 1.08, and nothing else in the module spells it', () => {
+  assert.equal(P.AI_PRICE_MULTIPLIER, 1.08);
+  for (const f of ['billing.js', 'payments.js', 'keys.js', 'db.js', 'routes/ai-studio.js', 'generate.js', 'studio.js', 'openrouter.js', 'context.js', 'gemini.js']) {
+    const src = fs.readFileSync(new URL(`../modules/ai-studio/${f}`, import.meta.url), 'utf8');
+    assert.doesNotMatch(src, /1\.08|\b108\b/, `${f} re-spells the multiplier`);
+  }
+});
+
+test('price = cost x 1.08: provider cost and markup apart, rounded up, never down', () => {
+  assert.deepEqual(P.priceFor(1 * USD), { provider_cost_micro: 1000000, markup_micro: 80000, price_micro: 1080000 });
+  assert.deepEqual(P.priceFor(0), { provider_cost_micro: 0, markup_micro: 0, price_micro: 0 });
+  // A sub-cent call: 0.0437 cents -> 437 micro x 1.08 = 471.96 -> 472 (up).
+  assert.deepEqual(P.priceFor(437), { provider_cost_micro: 437, markup_micro: 35, price_micro: 472 });
+  for (const c of [1, 7, 99, 12345, 987654321]) {
+    const p = P.priceFor(c);
+    assert.ok(p.price_micro >= c * 1.08, `price for ${c} fell below cost x 1.08`);
+    assert.ok(p.price_micro - c * 1.08 < 1, `price for ${c} rounded up by more than one micro-dollar`);
+    assert.equal(p.provider_cost_micro + p.markup_micro, p.price_micro);
+  }
+  assert.throws(() => P.priceFor(-1), TypeError);
+  assert.throws(() => P.priceFor(1.5), TypeError);
+});
+
+test('a top-up charges enough that, after the processor\'s fee, the full amount arrives', () => {
+  const q = P.topUpCharge(10 * USD);
+  // $10 net: (10 + 0.30) / 0.971 = 10.6076... -> $10.61; fee = round(10.61 x 2.9%) + 0.30 = 0.61.
+  assert.deepEqual(q, { charge_micro: 10610000, processor_fee_micro: 610000, credited_micro: 10000000 });
+  for (const usd of [5, 7.33, 20, 99.99, 500]) {
+    const want = Math.round(usd * USD);
+    const r = P.topUpCharge(want);
+    const chargeCents = r.charge_micro / 10000;
+    assert.ok(r.charge_micro - P.processorFeeCents(chargeCents) * 10000 >= r.credited_micro, `$${usd}: the fee ate into the balance`);
+    assert.ok(r.credited_micro >= want, `$${usd}: credited less than asked`);
+    // And it is the SMALLEST such charge: one cent less would not cover it.
+    assert.ok((chargeCents - 1) - P.processorFeeCents(chargeCents - 1) < r.credited_micro / 10000, `$${usd}: overcharged`);
+  }
+  assert.throws(() => P.topUpCharge(1 * USD), RangeError);
+  assert.throws(() => P.topUpCharge(501 * USD), RangeError);
+});
+
+test('formatUsd shows a sub-cent cost instead of a rounded zero', () => {
+  assert.equal(P.formatUsd(472), '$0.0005');
+  assert.equal(P.formatUsd(10610000), '$10.61');
+  assert.equal(P.formatUsd(0), '$0.00');
+});
+
+// ---- hold, run, capture / release -----------------------------------------
+
+function harness(startUsd) {
+  const b = payments.createFakeBackend();
+  const rows = [];
+  const ledger = async (row) => { rows.push(row); };
+  return { b, rows, ledger, fund: () => b.topUp(1, { chargeMicro: startUsd * USD + 1, creditedMicro: startUsd * USD }) };
+}
+
+test('THE PAID PATH: hold the most it can cost, run, capture the real price, return the rest', async () => {
+  const h = harness(10); await h.fund();
+  let sawHeld = null;
+  const out = await runPaid({
+    builderId: 1, requestId: 'r1', maxCostMicro: 2 * USD, payments: h.b, ledger: h.ledger,
+    run: async () => { sawHeld = await h.b.balance(1); return { costMicro: 500000, result: 'pictures' }; },
+  });
+  // While the call ran, the whole ceiling (2 x 1.08) was already held.
+  assert.deepEqual(sawHeld, { available_micro: 10 * USD - 2160000, held_micro: 2160000 });
+  assert.equal(out.result, 'pictures');
+  assert.equal(out.charge.price_micro, 540000);
+  assert.deepEqual(await h.b.balance(1), { available_micro: 10 * USD - 540000, held_micro: 0 });
+  assert.deepEqual(h.rows.map((r) => [r.kind, r.amountMicro]), [['hold', 2160000], ['capture', 540000]]);
+  const cap = h.rows[1];
+  assert.equal(cap.providerCostMicro, 500000);
+  assert.equal(cap.markupMicro, 40000);
+});
+
+test('a short balance refuses BEFORE the provider is called', async () => {
+  const h = harness(5); await h.fund();
+  let ran = false;
+  await assert.rejects(
+    runPaid({ builderId: 1, requestId: 'r2', maxCostMicro: 6 * USD, payments: h.b, ledger: h.ledger, run: async () => { ran = true; return { costMicro: 1 }; } }),
+    (err) => err instanceof BillingRefusal && err.code === 'insufficient_funds' && err.needed_micro === 6480000);
+  assert.equal(ran, false, 'the generation ran without its funds secured');
+  assert.deepEqual(await h.b.balance(1), { available_micro: 5 * USD, held_micro: 0 });
+  assert.equal(h.rows.length, 0);
+});
+
+test('a provider failure releases the WHOLE hold and records it', async () => {
+  const h = harness(10); await h.fund();
+  await assert.rejects(
+    runPaid({ builderId: 1, requestId: 'r3', maxCostMicro: 3 * USD, payments: h.b, ledger: h.ledger, run: async () => { throw new Error('provider 500'); } }),
+    /provider 500/);
+  assert.deepEqual(await h.b.balance(1), { available_micro: 10 * USD, held_micro: 0 }, 'money was kept after a failed call');
+  assert.deepEqual(h.rows.map((r) => [r.kind, r.amountMicro]), [['hold', 3240000], ['release', 3240000]]);
+});
+
+test('a provider reporting more than its ceiling is charged at most the ceiling', async () => {
+  const h = harness(10); await h.fund();
+  const out = await runPaid({ builderId: 1, requestId: 'r4', maxCostMicro: 1 * USD, payments: h.b, ledger: h.ledger, run: async () => ({ costMicro: 9 * USD }) });
+  assert.equal(out.charge.price_micro, 1080000);
+  assert.deepEqual(await h.b.balance(1), { available_micro: 10 * USD - 1080000, held_micro: 0 });
+});
+
+test('a ledger write failing after money moved does not charge twice or throw', async () => {
+  const h = harness(10); await h.fund();
+  const errors = [];
+  const out = await runPaid({
+    builderId: 1, requestId: 'r5', maxCostMicro: 1 * USD, payments: h.b,
+    ledger: async () => { throw new Error('db down'); }, log: { error: (o) => errors.push(o) },
+    run: async () => ({ costMicro: 100000 }),
+  });
+  assert.equal(out.charge.price_micro, 108000);
+  assert.equal(errors.length, 2);
+  assert.deepEqual(await h.b.balance(1), { available_micro: 10 * USD - 108000, held_micro: 0 });
+});
+
+test('with payments not set up (the default), nothing can be held or topped up', async () => {
+  const saved = process.env.AI_STUDIO_PAYMENTS;
+  for (const v of [undefined, '', 'stripe-typo', 'FAKEISH']) {
+    if (v === undefined) delete process.env.AI_STUDIO_PAYMENTS; else process.env.AI_STUDIO_PAYMENTS = v;
+    payments._setBackend(null);
+    assert.equal(payments.backend().name, 'none', `"${v}" opened a backend`);
+  }
+  if (saved === undefined) delete process.env.AI_STUDIO_PAYMENTS; else process.env.AI_STUDIO_PAYMENTS = saved;
+  let ran = false;
+  await assert.rejects(
+    runPaid({ builderId: 1, requestId: 'r6', maxCostMicro: 1, payments: payments.NONE, ledger: async () => {}, run: async () => { ran = true; } }),
+    (err) => err.code === 'payments_not_configured');
+  assert.equal(ran, false);
+});
+
+test('the ledger table is append-only and has no balance column', () => {
+  const sql = fs.readFileSync(new URL('../modules/ai-studio/migrations/ai_studio_002_ledger.sql', import.meta.url), 'utf8');
+  assert.match(sql, /BEFORE UPDATE OR DELETE ON ai_studio_ledger/);
+  assert.match(sql, /RAISE EXCEPTION 'ai_studio_ledger is append-only'/);
+  assert.match(sql, /provider_cost_micro\s+BIGINT/);
+  assert.match(sql, /markup_micro\s+BIGINT/);
+  assert.match(sql, /processor_fee_micro\s+BIGINT/);
+  assert.doesNotMatch(sql.replace(/--.*$/gm, ''), /\bbalance\b/i, 'a balance column would be Bongos holding user money (ADR 0385)');
+  const db = fs.readFileSync(new URL('../modules/ai-studio/db.js', import.meta.url), 'utf8');
+  assert.doesNotMatch(db, /UPDATE ai_studio_ledger|DELETE FROM ai_studio_ledger/);
+});
+
+// ---- the routes ------------------------------------------------------------
+
+const db = require('../modules/ai-studio/db.js');
+const api = require('../src/module-api.js');
+const ledgerRows = [];
+db.appendLedger = async (row) => { ledgerRows.push({ ...row, id: ledgerRows.length + 1, created_at: 'now' }); return {}; };
+db.recentLedger = async (builderId) => ledgerRows.filter((r) => r.builderId === builderId).map((r) => ({
+  id: r.id, kind: r.kind, request_id: r.requestId || null, amount_micro: r.amountMicro || 0, provider_cost_micro: r.providerCostMicro || 0,
+  markup_micro: r.markupMicro || 0, processor_fee_micro: r.processorFeeMicro || 0, backend: r.backend, note: r.note || '', created_at: r.created_at, ref: r.ref,
+})).reverse();
+let viewer = { id: 7, rank: 'xenos' };
+for (const [name, value] of Object.entries({
+  requireBuilder: (req, res, next) => { req.builder = viewer; next(); },
+  requireRank: () => (req, res, next) => next(),
+})) Object.defineProperty(api, name, { value, configurable: true, writable: true });
+
+const express = require('express');
+const app = express();
+app.use((req, res, next) => {
+  res.fail = (code, opts) => res.status(typeof opts === 'number' ? opts : (opts && opts.status) || 400).json({ error: { code, message: opts && opts.message } });
+  next();
+});
+app.use(express.json());
+app.use('/api/bongos', require('../modules/ai-studio/routes/ai-studio.js')());
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+test.after(() => server.close());
+
+function call(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const data = body === undefined ? null : JSON.stringify(body);
+    const req = http.request(`${base}${path}`, { method, headers: data ? { 'content-type': 'application/json', 'content-length': Buffer.byteLength(data) } : {} }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => resolve({ status: res.statusCode, body: JSON.parse(Buffer.concat(chunks).toString()) }));
+    });
+    req.on('error', reject);
+    if (data) req.write(data);
+    req.end();
+  });
+}
+
+test('routes: top up on the test backend, then read the balance and a ledger with every amount apart', async () => {
+  payments._setBackend(payments.createFakeBackend());
+  const up = await call('POST', '/ai-studio/topup', { amount_usd: 10 });
+  assert.equal(up.status, 201);
+  assert.deepEqual(up.body.topup, { charge_micro: 10610000, processor_fee_micro: 610000, credited_micro: 10000000 });
+  const bal = await call('GET', '/ai-studio/balance');
+  assert.equal(bal.body.payments, 'fake');
+  assert.equal(bal.body.test_mode, true);
+  assert.equal(bal.body.price_multiplier, 1.08);
+  assert.deepEqual(bal.body.balance, { available_micro: 10000000, held_micro: 0 });
+  assert.equal(bal.body.ledger[0].kind, 'topup');
+  assert.equal(bal.body.ledger[0].processor_fee_micro, 610000);
+  assert.ok(!('ref' in bal.body.ledger[0]), 'the processor reference is internal');
+  assert.equal((await call('POST', '/ai-studio/topup', { amount_usd: 1 })).status, 400);
+});
+
+// Task 1004921: the Studio says "your card is charged $20.91" BEFORE anything is
+// paid, and how much a run sets aside, from these two reads, so neither the fee
+// nor the ceiling is spelled in the browser.
+test('routes: a top-up quote charges what the top-up itself would, and writes nothing', async () => {
+  payments._setBackend(payments.createFakeBackend());
+  const before = ledgerRows.length;
+  const q = await call('GET', '/ai-studio/topup/quote?amount_usd=10');
+  assert.equal(q.status, 200);
+  assert.deepEqual(q.body.quote, P.topUpCharge(10 * USD));
+  assert.equal(q.body.quote.charge_micro, 10610000);
+  assert.equal(q.body.min_micro, P.MIN_TOPUP_MICRO);
+  assert.equal(q.body.max_micro, P.MAX_TOPUP_MICRO);
+  assert.equal((await call('GET', '/ai-studio/topup/quote?amount_usd=20')).body.quote.charge_micro, 20910000);
+  assert.equal((await call('GET', '/ai-studio/topup/quote?amount_usd=2')).status, 400);
+  assert.equal((await call('GET', '/ai-studio/topup/quote?amount_usd=abc')).status, 400);
+  assert.equal(ledgerRows.length, before, 'a quote must not move money or write the ledger');
+  const bal = await call('GET', '/ai-studio/balance');
+  assert.equal(bal.body.max_cost_micro, S.MAX_COST_MICRO);
+});
+
+test('routes: with payments not set up, a top-up is refused and no row is written', async () => {
+  payments._setBackend(payments.NONE);
+  const before = ledgerRows.length;
+  const r = await call('POST', '/ai-studio/topup', { amount_usd: 10 });
+  assert.equal(r.status, 409);
+  assert.equal(r.body.error.code, 'payments_not_configured');
+  assert.equal(ledgerRows.length, before);
+  assert.equal((await call('GET', '/ai-studio/balance')).body.balance, null);
+});

package/tests/ai_studio_generate.mjs

@@ -0,0 +1,282 @@
+// tests/ai_studio_generate.mjs — submitting a sketch and generating on our key
+// (task 1004917, goal 1000136, ADR 0392):
+//   - uploads are checked the page-notes way (declared type must match the
+//     file's own bytes, size caps, SVG refused), and a request names its files;
+//   - the project context is read on the server from the instance's files;
+//   - the OpenRouter calls carry the key only in the Authorization header,
+//     bill on the cost the provider reports, and fail closed when it is missing;
+//   - a whole generation holds the full price first, charges cost x 1.08 on
+//     success, refunds everything on a provider failure, never runs on a short
+//     balance, and never says "not charged" once money was taken.
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const S = require('../modules/ai-studio/studio.js');
+const OR = require('../modules/ai-studio/openrouter.js');
+const P = require('../modules/ai-studio/pricing.js');
+const payments = require('../modules/ai-studio/payments.js');
+const { runOnOurKey } = require('../modules/ai-studio/generate.js');
+const { projectContext } = require('../modules/ai-studio/context.js');
+
+const USD = P.MICRO_PER_USD;
+const KEY = 'sk-or-v1-test-0000000000000000000000000000';
+const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 13]);
+const PDF = Buffer.from('%PDF-1.7\n%test\n');
+
+// ---- uploads and requests --------------------------------------------------
+
+test('an upload is accepted only when its bytes are the type it claims', () => {
+  const ok = S.checkFile({ name: 'sketch one.png', content_type: 'image/png', data: PNG.toString('base64') });
+  assert.equal(ok.file.content_type, 'image/png');
+  assert.equal(ok.file.name, 'sketch one.png');
+  assert.ok(Buffer.isBuffer(ok.file.bytes));
+  assert.equal(S.checkFile({ content_type: 'application/pdf', data: PDF.toString('base64') }).file.content_type, 'application/pdf');
+
+  assert.equal(S.checkFile({ content_type: 'image/svg+xml', data: Buffer.from('<svg/>').toString('base64') }).error, 'unsupported_type');
+  assert.equal(S.checkFile({ content_type: 'image/jpeg', data: PNG.toString('base64') }).error, 'type_mismatch');
+  assert.equal(S.checkFile({ content_type: 'image/png', data: '' }).error, 'bad_file');
+  const big = Buffer.concat([PNG, Buffer.alloc(S.MAX_IMAGE_BYTES)]);
+  assert.equal(S.checkFile({ content_type: 'image/png', data: big.toString('base64') }).error, 'file_too_large');
+  assert.equal(S.checkFile({ name: '../../etc/x".png', content_type: 'image/png', data: PNG.toString('base64') }).file.name, '.._.._etc_x_.png');
+  for (const code of ['bad_file', 'unsupported_type', 'file_too_large', 'type_mismatch']) assert.ok(S.MESSAGES[code], code);
+});
+
+test('a request needs a real prompt and 1 to 6 file ids', () => {
+  assert.deepEqual(S.checkRequest({ prompt: '  make it moody  ', file_ids: ['4', 4, '9'] }), { prompt: 'make it moody', fileIds: ['4', '9'] });
+  assert.equal(S.checkRequest({ prompt: 'hi', file_ids: ['1'] }).error, 'prompt_required');
+  assert.equal(S.checkRequest({ prompt: 'x'.repeat(S.MAX_PROMPT + 1), file_ids: ['1'] }).error, 'prompt_too_long');
+  assert.equal(S.checkRequest({ prompt: 'a castle', file_ids: [] }).error, 'file_required');
+  assert.equal(S.checkRequest({ prompt: 'a castle', file_ids: ['1', '2', '3', '4', '5', '6', '7'] }).error, 'too_many_files');
+  assert.equal(S.checkRequest({ prompt: 'a castle', file_ids: ['1; drop table'] }).error, 'bad_file');
+});
+
+// ---- project context -------------------------------------------------------
+
+test('the project context is read on the server from the instance files', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ai-ctx-'));
+  fs.mkdirSync(path.join(root, 'docs'));
+  fs.writeFileSync(path.join(root, 'docs', 'project-context.template.md'), 'TEMPLATE TEXT');
+  fs.writeFileSync(path.join(root, 'DESIGN.md'), 'Night room. Glass rows.');
+  const branding = { identity: { productName: 'Moonfall', worldName: 'Tidelands' }, theme: { colors: { accent: '#7af' } } };
+
+  let ctx = await projectContext({ root, branding });
+  assert.match(ctx, /Moonfall, set in the world of Tidelands/);
+  assert.match(ctx, /#7af/);
+  assert.match(ctx, /TEMPLATE TEXT/, 'falls back to the template when no project doc is written');
+  assert.match(ctx, /Night room\. Glass rows\./);
+
+  fs.writeFileSync(path.join(root, 'docs', 'project-context.md'), 'REAL PROJECT DOC');
+  ctx = await projectContext({ root, branding });
+  assert.match(ctx, /REAL PROJECT DOC/);
+  assert.doesNotMatch(ctx, /TEMPLATE TEXT/);
+
+  fs.writeFileSync(path.join(root, 'DESIGN.md'), 'd'.repeat(S.CONTEXT_BUDGET.design + 500));
+  ctx = await projectContext({ root, branding });
+  assert.match(ctx, /cut for length/, 'a long doc is clipped to its budget');
+});
+
+// ---- the OpenRouter calls --------------------------------------------------
+
+function fakeFetch(responses) {
+  const calls = [];
+  const fn = async (url, init) => {
+    calls.push({ url, init, body: JSON.parse(init.body) });
+    const r = responses.shift();
+    if (r instanceof Error) throw r;
+    return { ok: r.status ? r.status < 400 : true, status: r.status || 200, json: async () => r.json };
+  };
+  fn.calls = calls;
+  return fn;
+}
+const replyJson = (text, cost) => ({ choices: [{ message: { content: text } }], usage: { cost } });
+const imageJson = (cost) => ({
+  choices: [{ message: { content: '', images: [{ image_url: { url: `data:image/png;base64,${PNG.toString('base64')}` } }] } }],
+  usage: { cost },
+});
+const files = [S.forProvider({ name: 's.png', content_type: 'image/png', bytes: PNG }), S.forProvider({ name: 'd.pdf', content_type: 'application/pdf', bytes: PDF })];
+
+test('the reply call sends the key only as a header and bills on the reported cost', async () => {
+  const f = fakeFetch([{ json: replyJson('Lovely silhouette.', 0.0123456) }]);
+  const out = await OR.reply({ fetchImpl: f, key: KEY, system: 'CTX', prompt: 'a castle', files });
+  assert.deepEqual(out, { text: 'Lovely silhouette.', costMicro: 12346 });
+  const c = f.calls[0];
+  assert.equal(c.url, OR.ENDPOINT);
+  assert.equal(c.init.headers.authorization, `Bearer ${KEY}`);
+  assert.ok(!c.init.body.includes(KEY), 'the key is never in the request body');
+  assert.deepEqual(c.body.usage, { include: true });
+  assert.equal(c.body.messages[0].content, 'CTX');
+  const parts = c.body.messages[1].content;
+  assert.equal(parts[1].type, 'image_url');
+  assert.equal(parts[2].type, 'file');
+});
+
+test('the image call returns the images and leaves PDFs out of the drawing brief', async () => {
+  const f = fakeFetch([{ json: imageJson(0.04) }]);
+  const out = await OR.images({ fetchImpl: f, key: KEY, system: 'CTX', brief: 'draw', files });
+  assert.equal(out.costMicro, 40000);
+  assert.equal(out.images.length, 1);
+  assert.equal(out.images[0].content_type, 'image/png');
+  assert.deepEqual(f.calls[0].body.modalities, ['image', 'text']);
+  assert.equal(f.calls[0].body.messages[1].content.filter((p) => p.type === 'file').length, 0);
+});
+
+test('a provider answer with no cost, an error, or no images fails, and no failure echoes the key', async () => {
+  const cases = [
+    [() => OR.reply({ fetchImpl: fakeFetch([{ json: { choices: [{ message: { content: 'x' } }] } }]), key: KEY, system: '', prompt: 'p', files: [] }), 'provider_cost_unknown'],
+    [() => OR.reply({ fetchImpl: fakeFetch([{ status: 401, json: { error: { message: `bad key ${KEY}` } } }]), key: KEY, system: '', prompt: 'p', files: [] }), 'provider_error'],
+    [() => OR.reply({ fetchImpl: fakeFetch([new Error(`socket ${KEY}`)]), key: KEY, system: '', prompt: 'p', files: [] }), 'provider_unreachable'],
+    [() => OR.images({ fetchImpl: fakeFetch([{ json: replyJson('no pictures', 0.01) }]), key: KEY, system: '', brief: 'b', files: [] }), 'provider_no_images'],
+  ];
+  for (const [call, code] of cases) {
+    await assert.rejects(call, (err) => {
+      assert.equal(err.code, code);
+      assert.ok(!String(err.message).includes(KEY), `${code} leaked the key`);
+      return true;
+    });
+  }
+});
+
+// ---- a whole generation on our key -----------------------------------------
+
+function fakeDb() {
+  const rows = { ledger: [], outputs: [], finished: null, running: null };
+  return {
+    rows,
+    appendLedger: async (r) => { rows.ledger.push(r); },
+    markRunning: async (id, src) => { rows.running = src; },
+    addOutput: async (id, builderId, img) => { rows.outputs.push({ id, builderId, img }); },
+    finishRequest: async (id, f) => { rows.finished = f; },
+  };
+}
+async function funded(usd) {
+  const b = payments.createFakeBackend();
+  if (usd) await b.topUp(7, { chargeMicro: usd * USD + 1, creditedMicro: usd * USD });
+  return b;
+}
+const request = { id: 41, builder_id: 7, prompt: 'a castle at dusk' };
+const okProviders = (calls = []) => ({
+  reply: async (a) => { calls.push(['reply', a]); return { text: 'Strong shapes.', costMicro: 12000 }; },
+  images: async (a) => { calls.push(['images', a]); return { images: [{ content_type: 'image/png', base64: PNG.toString('base64') }], costMicro: 38000 }; },
+});
+
+test('a generation charges exactly cost x 1.08 and records it apart', async () => {
+  const pay = await funded(5);
+  const db = fakeDb();
+  const calls = [];
+  const out = await runOnOurKey(request, files, { db, payments: pay, providers: okProviders(calls), fetchImpl: null, ourKey: KEY, context: 'CTX' });
+  assert.equal(out.status, 'done');
+  const cost = 12000 + 38000;
+  const price = P.priceFor(cost);
+  assert.equal(price.price_micro, 54000);
+  assert.deepEqual(
+    { c: db.rows.finished.provider_cost_micro, m: db.rows.finished.markup_micro, p: db.rows.finished.price_micro },
+    { c: 50000, m: 4000, p: 54000 });
+  assert.equal(db.rows.finished.status, 'done');
+  assert.equal(db.rows.finished.reply_md, 'Strong shapes.');
+  assert.equal(db.rows.outputs.length, 1);
+  assert.equal(db.rows.running, 'ours');
+  assert.deepEqual((await pay.balance(7)), { available_micro: 5 * USD - 54000, held_micro: 0 });
+  assert.deepEqual(db.rows.ledger.map((r) => r.kind), ['hold', 'capture']);
+  assert.ok(db.rows.ledger.every((r) => r.backend === 'fake' && r.requestId === '41'));
+  assert.equal(calls[0][1].system, 'CTX', 'the server-built context is what the provider sees');
+  assert.match(calls[1][1].brief, /Strong shapes\./, 'the image brief carries the reply');
+});
+
+test('a provider failure refunds the whole hold and says so', async () => {
+  const pay = await funded(5);
+  const db = fakeDb();
+  const providers = { ...okProviders(), images: async () => { throw new OR.ProviderError('provider_no_images', 'The AI provider returned no images.'); } };
+  const out = await runOnOurKey(request, files, { db, payments: pay, providers, ourKey: KEY, context: '' });
+  assert.equal(out.status, 'failed');
+  assert.equal(db.rows.finished.status, 'failed');
+  assert.match(db.rows.finished.error, /You were not charged\./);
+  assert.equal(db.rows.finished.price_micro, undefined);
+  assert.deepEqual(await pay.balance(7), { available_micro: 5 * USD, held_micro: 0 });
+  assert.deepEqual(db.rows.ledger.map((r) => r.kind), ['hold', 'release']);
+});
+
+test('a short balance refuses before any provider call', async () => {
+  const pay = await funded(0);
+  const db = fakeDb();
+  const calls = [];
+  const out = await runOnOurKey(request, files, { db, payments: pay, providers: okProviders(calls), ourKey: KEY, context: '' });
+  assert.equal(out.status, 'refused');
+  assert.equal(out.code, 'insufficient_funds');
+  assert.equal(calls.length, 0, 'nothing ran');
+  assert.match(db.rows.finished.error, /balance is too low/);
+  assert.deepEqual(db.rows.ledger, []);
+});
+
+test('with no key of ours configured a request is refused and no money is touched', async () => {
+  const pay = await funded(5);
+  const db = fakeDb();
+  const calls = [];
+  const out = await runOnOurKey(request, files, { db, payments: pay, providers: okProviders(calls), ourKey: '', context: '' });
+  assert.equal(out.status, 'refused');
+  assert.equal(calls.length, 0);
+  assert.equal(db.rows.running, null);
+  assert.deepEqual(await pay.balance(7), { available_micro: 5 * USD, held_micro: 0 });
+});
+
+test('once money was taken a storage failure never claims "not charged"', async () => {
+  const pay = await funded(5);
+  const db = fakeDb();
+  db.addOutput = async () => { throw new Error('disk full'); };
+  const out = await runOnOurKey(request, files, { db, payments: pay, providers: okProviders(), ourKey: KEY, context: '' });
+  assert.equal(out.status, 'failed');
+  assert.equal(out.code, 'store_failed');
+  assert.doesNotMatch(db.rows.finished.error, /not charged/);
+  assert.equal(db.rows.finished.price_micro, 54000, 'the receipt still shows what was paid');
+  assert.deepEqual(db.rows.ledger.map((r) => r.kind), ['hold', 'capture']);
+});
+
+// ---- the builder's own key (task 1004918) ----------------------------------
+
+test('which key runs: theirs whenever they have one, unless they ask for ours', () => {
+  const K = require('../modules/ai-studio/keys.js');
+  assert.deepEqual(K.chooseKey([], undefined), { source: 'ours' });
+  assert.deepEqual(K.chooseKey(['gemini'], undefined), { source: 'own', provider: 'gemini' });
+  assert.deepEqual(K.chooseKey(['gemini', 'openrouter'], undefined), { source: 'own', provider: 'openrouter' }, 'OpenRouter first: it reports its cost');
+  assert.deepEqual(K.chooseKey(['openrouter'], 'ours'), { source: 'ours' });
+  assert.deepEqual(K.chooseKey([], 'own'), { error: 'no_own_key' });
+  assert.deepEqual(K.chooseKey(['openrouter'], 'free'), { error: 'bad_pay_with' });
+});
+
+test('on their own key no money moves: one own_key row, price 0, cost noted', async () => {
+  const { runOnOwnKey } = require('../modules/ai-studio/generate.js');
+  const db = fakeDb();
+  const out = await runOnOwnKey(request, files, { db, providers: okProviders(), key: 'their-key', provider: 'openrouter', context: '' });
+  assert.equal(out.status, 'done');
+  assert.equal(db.rows.running, 'own');
+  assert.deepEqual([db.rows.finished.provider_cost_micro, db.rows.finished.markup_micro, db.rows.finished.price_micro], [50000, 0, 0]);
+  assert.equal(db.rows.ledger.length, 1);
+  assert.deepEqual([db.rows.ledger[0].kind, db.rows.ledger[0].amountMicro, db.rows.ledger[0].providerCostMicro], ['own_key', 0, 50000]);
+});
+
+test('a failure on their own key records no ledger row and says we charged nothing', async () => {
+  const { runOnOwnKey } = require('../modules/ai-studio/generate.js');
+  const db = fakeDb();
+  const providers = { ...okProviders(), reply: async () => { throw new OR.ProviderError('provider_error', 'The AI provider refused the request (HTTP 401).'); } };
+  const out = await runOnOwnKey(request, files, { db, providers, key: 'their-key', provider: 'openrouter', context: '' });
+  assert.equal(out.status, 'failed');
+  assert.match(db.rows.finished.error, /Nothing was charged by us/);
+  assert.deepEqual(db.rows.ledger, []);
+  assert.equal(db.rows.outputs.length, 0);
+});
+
+// ---- the key never leaves the server ---------------------------------------
+
+test('the routes never send our key or log a request body', () => {
+  const src = fs.readFileSync(new URL('../modules/ai-studio/routes/ai-studio.js', import.meta.url), 'utf8');
+  const mentions = src.split('\n').filter((l) => l.includes('OPENROUTER_API_KEY') && !/^\s*\/\//.test(l));
+  assert.equal(mentions.length, 1, 'our key is read in exactly one place');
+  assert.match(mentions[0], /ourKey: process\.env\.OPENROUTER_API_KEY/);
+  assert.doesNotMatch(src, /log\.\w+\([^)]*req\.body/, 'no log line carries a request body');
+  assert.doesNotMatch(src, /res\.json\([^)]*ourKey/);
+});