@bongos/core 1.23.22 → 1.24.1

package/modules/ai-studio/billing.js

@@ -0,0 +1,67 @@
+// modules/ai-studio/billing.js — paying for one AI generation on our key
+// (task 1004920, goal 1000136, ADR 0392 decision 5).
+//
+// The order is the guarantee the owner asked for:
+//
+//   1. HOLD the most the call can cost (its cost ceiling x the multiplier) on the
+//      processor-held balance. Short balance -> refuse; nothing runs.
+//   2. RUN the provider call, which reports what it really cost.
+//   3. CAPTURE the real price (cost x multiplier, never more than the hold); the
+//      rest of the hold goes back to the balance.
+//   On any failure in step 2 the whole hold is RELEASED.
+//
+// Every step writes a ledger row (amount, provider cost, markup, processor fee
+// apart). A ledger write that fails after money moved is logged, never thrown
+// past the money step, so a builder is never charged twice by a retry.
+//
+// The payments backend and the ledger writer are handed in, so this is tested
+// with no processor and no DB.
+
+'use strict';
+
+const P = require('./pricing');
+
+class BillingRefusal extends Error {
+  constructor(code, message, extra) { super(message); this.code = code; Object.assign(this, extra); }
+}
+
+// runPaid({ builderId, requestId, maxCostMicro, run, payments, ledger, log })
+//   run() -> Promise<{ costMicro, result }>   the provider call
+// Resolves { result, charge } where charge = priceFor(cost) plus the hold id.
+async function runPaid({ builderId, requestId, maxCostMicro, run, payments, ledger, log }) {
+  const ceiling = P.priceFor(maxCostMicro).price_micro;
+  const hold = await payments.hold(builderId, ceiling);
+  if (!hold.ok) {
+    const msg = hold.reason === 'insufficient_funds'
+      ? 'Your balance is too low for this generation. Top up to continue.'
+      : 'Paid generations are not set up here yet. Add your own key in Settings to use yours.';
+    throw new BillingRefusal(hold.reason, msg, { needed_micro: ceiling, available_micro: hold.available_micro });
+  }
+  await safeLedger(ledger, log, { builderId, requestId, kind: 'hold', amountMicro: ceiling, ref: hold.holdId });
+
+  let outcome;
+  try {
+    outcome = await run();
+  } catch (err) {
+    const released = await payments.release(hold.holdId);
+    await safeLedger(ledger, log, { builderId, requestId, kind: 'release', amountMicro: released.released_micro, ref: hold.holdId, note: 'provider failed' });
+    throw err;
+  }
+
+  const cost = Math.min(Math.max(0, Math.round(outcome.costMicro || 0)), maxCostMicro);
+  const charge = P.priceFor(cost);
+  const captured = await payments.capture(hold.holdId, Math.min(charge.price_micro, ceiling));
+  await safeLedger(ledger, log, {
+    builderId, requestId, kind: 'capture', amountMicro: captured.captured_micro,
+    providerCostMicro: charge.provider_cost_micro, markupMicro: charge.markup_micro, ref: hold.holdId,
+  });
+  return { result: outcome.result, charge: { ...charge, hold_id: hold.holdId } };
+}
+
+async function safeLedger(ledger, log, row) {
+  try { await ledger(row); } catch (err) {
+    if (log) log.error({ err: err.message, kind: row.kind, request_id: row.requestId }, 'ai-studio ledger write failed after money moved');
+  }
+}
+
+module.exports = { runPaid, BillingRefusal };

package/modules/ai-studio/context.js

@@ -0,0 +1,29 @@
+// modules/ai-studio/context.js — reading the project context a generation is
+// given (task 1004917, goal 1000136, ADR 0392 decision 9): the branding pack,
+// the project context doc and DESIGN.md, all read on the SERVER from the
+// instance's own files. The browser never sends context, so an artist cannot
+// steer the AI away from the project by editing a request.
+//
+// The project doc is the instance's filled-in docs/project-context.md; a
+// project that has not written one yet falls back to the template beside it.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const api = require('../../src/module-api');
+const S = require('./studio');
+
+async function readOptional(file) {
+  try { return await fs.promises.readFile(file, 'utf8'); } catch (_) { return ''; }
+}
+
+// Returns the system prompt string. `root` and `branding` are for tests.
+async function projectContext({ root = api.resolveInstanceRoot(), branding = api.clientBranding() } = {}) {
+  const projectDoc = (await readOptional(path.join(root, 'docs', 'project-context.md')))
+    || (await readOptional(path.join(root, 'docs', 'project-context.template.md')));
+  const designDoc = await readOptional(path.join(root, 'DESIGN.md'));
+  return S.buildContext({ branding, projectDoc, designDoc });
+}
+
+module.exports = { projectContext };

package/modules/ai-studio/db.js

@@ -0,0 +1,172 @@
+// modules/ai-studio/db.js — the thin SQL behind the AI studio (goal 1000136).
+// Every function takes an optional executor so a test can hand in a fake query
+// function; the default is the shared pool.
+
+'use strict';
+
+const { pool } = require('../../src/module-api');
+
+const exec = (executor) => executor || ((text, params) => pool.query(text, params));
+
+// ---- provider keys (task 1004919) -------------------------------------------
+
+// The builder's stored keys WITHOUT the ciphertext: what Settings lists.
+async function listKeyMeta(builderId, executor) {
+  const { rows } = await exec(executor)(
+    `SELECT provider, last4, set_at, true AS key_enc
+       FROM ai_studio_provider_keys WHERE builder_id = $1`, [builderId]);
+  return rows;
+}
+
+// The ciphertext for one provider, for the server's own provider call only.
+async function getKeyEnc(builderId, provider, executor) {
+  const { rows } = await exec(executor)(
+    'SELECT key_enc FROM ai_studio_provider_keys WHERE builder_id = $1 AND provider = $2', [builderId, provider]);
+  return rows[0] ? rows[0].key_enc : null;
+}
+
+async function setKey(builderId, provider, keyEnc, last4, executor) {
+  const { rows } = await exec(executor)(
+    `INSERT INTO ai_studio_provider_keys (builder_id, provider, key_enc, last4)
+     VALUES ($1, $2, $3, $4)
+     ON CONFLICT (builder_id, provider)
+       DO UPDATE SET key_enc = EXCLUDED.key_enc, last4 = EXCLUDED.last4, set_at = now()
+     RETURNING provider, last4, set_at, true AS key_enc`, [builderId, provider, keyEnc, last4]);
+  return rows[0];
+}
+
+async function clearKey(builderId, provider, executor) {
+  const { rowCount } = await exec(executor)(
+    'DELETE FROM ai_studio_provider_keys WHERE builder_id = $1 AND provider = $2', [builderId, provider]);
+  return rowCount > 0;
+}
+
+// ---- the ledger (task 1004920) ---------------------------------------------
+// Append-only: there is no update or delete here, and the table's trigger
+// refuses both. No balance is stored; the processor holds it (ADR 0385).
+
+async function appendLedger(row, executor) {
+  const { rows } = await exec(executor)(
+    `INSERT INTO ai_studio_ledger
+       (builder_id, kind, request_id, amount_micro, provider_cost_micro, markup_micro, processor_fee_micro, backend, ref, note)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+     RETURNING id, created_at`,
+    [row.builderId, row.kind, row.requestId || null, row.amountMicro || 0, row.providerCostMicro || 0,
+      row.markupMicro || 0, row.processorFeeMicro || 0, row.backend, row.ref || null, (row.note || '').slice(0, 300)]);
+  return rows[0];
+}
+
+async function recentLedger(builderId, { limit = 50 } = {}, executor) {
+  const { rows } = await exec(executor)(
+    `SELECT id, kind, request_id, amount_micro, provider_cost_micro, markup_micro, processor_fee_micro, backend, note, created_at
+       FROM ai_studio_ledger WHERE builder_id = $1 ORDER BY created_at DESC, id DESC LIMIT $2`,
+    [builderId, Math.min(Math.max(1, limit | 0), 200)]);
+  return rows;
+}
+
+// ---- requests and their files (task 1004917) -------------------------------
+// A file row's bytes are read only by getFile; every other query leaves them out.
+
+const FILE_META = 'id, request_id, role, name, content_type, size_bytes, created_at';
+const REQUEST_COLS = `id, builder_id, prompt, key_source, status, reply_md, provider_cost_micro, markup_micro,
+  price_micro, error, created_at, finished_at`;
+
+async function addUpload(builderId, file, executor) {
+  const { rows } = await exec(executor)(
+    `INSERT INTO ai_studio_files (builder_id, role, name, content_type, size_bytes, bytes)
+     VALUES ($1, 'upload', $2, $3, $4, $5) RETURNING ${FILE_META}`,
+    [builderId, file.name, file.content_type, file.bytes.length, file.bytes]);
+  return rows[0];
+}
+
+// Creates the request and attaches the builder's own, not-yet-used uploads to
+// it in one statement. Returns null (and creates nothing) unless every id is
+// such an upload, so a request can never borrow another builder's file.
+async function createRequest(builderId, prompt, fileIds, executor) {
+  const { rows } = await exec(executor)(
+    `WITH ok AS (
+       SELECT count(*) AS n FROM ai_studio_files
+        WHERE id = ANY($3::bigint[]) AND builder_id = $1 AND role = 'upload' AND request_id IS NULL
+     ), req AS (
+       INSERT INTO ai_studio_requests (builder_id, prompt)
+       SELECT $1, $2 FROM ok WHERE ok.n = cardinality($3::bigint[])
+       RETURNING ${REQUEST_COLS}
+     ), att AS (
+       UPDATE ai_studio_files f SET request_id = req.id FROM req
+        WHERE f.id = ANY($3::bigint[]) AND f.builder_id = $1 AND f.role = 'upload' AND f.request_id IS NULL
+       RETURNING f.id
+     )
+     SELECT req.*, (SELECT count(*) FROM att) AS attached FROM req`,
+    [builderId, prompt, fileIds]);
+  return rows[0] || null;
+}
+
+async function markRunning(requestId, keySource, executor) {
+  await exec(executor)(
+    `UPDATE ai_studio_requests SET status = 'running', key_source = $2 WHERE id = $1`, [requestId, keySource]);
+}
+
+async function finishRequest(requestId, f, executor) {
+  await exec(executor)(
+    `UPDATE ai_studio_requests
+        SET status = $2, reply_md = $3, provider_cost_micro = $4, markup_micro = $5, price_micro = $6,
+            error = $7, finished_at = now()
+      WHERE id = $1`,
+    [requestId, f.status, f.reply_md || null, f.provider_cost_micro ?? null, f.markup_micro ?? null,
+      f.price_micro ?? null, f.error ? String(f.error).slice(0, 500) : null]);
+}
+
+async function addOutput(requestId, builderId, img, executor) {
+  const bytes = Buffer.from(img.base64, 'base64');
+  const ext = img.content_type.split('/')[1];
+  const { rows } = await exec(executor)(
+    `INSERT INTO ai_studio_files (builder_id, request_id, role, name, content_type, size_bytes, bytes)
+     VALUES ($1, $2, 'output', $3, $4, $5, $6) RETURNING ${FILE_META}`,
+    [builderId, requestId, `generated.${ext}`, img.content_type, bytes.length, bytes]);
+  return rows[0];
+}
+
+// The request with its files' metadata, only when it is the builder's own.
+async function getRequest(builderId, requestId, executor) {
+  const q = exec(executor);
+  const { rows } = await q(`SELECT ${REQUEST_COLS} FROM ai_studio_requests WHERE id = $1 AND builder_id = $2`, [requestId, builderId]);
+  if (!rows[0]) return null;
+  const files = await q(`SELECT ${FILE_META} FROM ai_studio_files WHERE request_id = $1 ORDER BY id`, [requestId]);
+  return { ...rows[0], files: files.rows };
+}
+
+async function listRequests(builderId, { limit = 30 } = {}, executor) {
+  const { rows } = await exec(executor)(
+    `SELECT ${REQUEST_COLS} FROM ai_studio_requests WHERE builder_id = $1 ORDER BY created_at DESC, id DESC LIMIT $2`,
+    [builderId, Math.min(Math.max(1, limit | 0), 100)]);
+  return rows;
+}
+
+// How many of the builder's requests are still queued or running (task 1004918).
+// A request stuck past 15 minutes no longer counts, so a crashed run can never
+// lock a builder out.
+async function countActiveRequests(builderId, executor) {
+  const { rows } = await exec(executor)(
+    `SELECT count(*)::int AS n FROM ai_studio_requests
+      WHERE builder_id = $1 AND status IN ('queued', 'running') AND created_at > now() - interval '15 minutes'`, [builderId]);
+  return rows[0] ? rows[0].n : 0;
+}
+
+// One file's bytes, only when it is the builder's own.
+async function getFile(builderId, fileId, executor) {
+  const { rows } = await exec(executor)(
+    'SELECT id, name, content_type, bytes FROM ai_studio_files WHERE id = $1 AND builder_id = $2', [fileId, builderId]);
+  return rows[0] || null;
+}
+
+// The uploads on a request, bytes included, for the provider calls.
+async function requestUploads(requestId, executor) {
+  const { rows } = await exec(executor)(
+    `SELECT name, content_type, bytes FROM ai_studio_files WHERE request_id = $1 AND role = 'upload' ORDER BY id`, [requestId]);
+  return rows;
+}
+
+module.exports = {
+  listKeyMeta, getKeyEnc, setKey, clearKey, appendLedger, recentLedger,
+  addUpload, createRequest, markRunning, finishRequest, addOutput, getRequest, listRequests, getFile, requestUploads, countActiveRequests,
+};

package/modules/ai-studio/gemini.js

@@ -0,0 +1,75 @@
+// modules/ai-studio/gemini.js — the same two calls as openrouter.js, made
+// straight to Google's Gemini API for a builder who brought a Google AI Studio
+// key (task 1004918, goal 1000136, ADR 0392 decision 8).
+//
+// Only ever used on the builder's OWN key: Google's response does not report a
+// price, so it could not be billed at cost x the multiplier, and nothing here
+// pretends to. The cost comes back as null and the request records it as "not
+// reported by the provider".
+//
+// Same interface as openrouter.js (reply / images, { text | images, costMicro }),
+// so generate.js does not care which one it was handed. The key goes only in
+// the x-goog-api-key header, never in the URL, where proxies and logs keep it.
+
+'use strict';
+
+const { ProviderError } = require('./openrouter');
+
+const BASE = 'https://generativelanguage.googleapis.com/v1beta/models';
+const MODELS = { reply: 'gemini-2.5-pro', images: 'gemini-2.5-flash-image' };
+const TIMEOUT_MS = 120000;
+
+function parts(text, files) {
+  return [{ text }, ...(files || []).map((f) => ({ inline_data: { mime_type: f.content_type, data: f.base64 } }))];
+}
+
+async function post(fetchImpl, key, model, body) {
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), TIMEOUT_MS);
+  let res;
+  try {
+    res = await fetchImpl(`${BASE}/${model}:generateContent`, {
+      method: 'POST',
+      headers: { 'x-goog-api-key': key, 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: ctl.signal,
+    });
+  } catch (err) {
+    throw new ProviderError(err.name === 'AbortError' ? 'provider_timeout' : 'provider_unreachable', 'Google could not be reached.');
+  } finally {
+    clearTimeout(timer);
+  }
+  let json = null;
+  try { json = await res.json(); } catch (_) { /* fall through */ }
+  if (!res.ok || !json || json.error) {
+    throw new ProviderError('provider_error', `Google refused the request (HTTP ${res.status}). Check the key in Settings.`);
+  }
+  const cand = json.candidates && json.candidates[0];
+  return (cand && cand.content && Array.isArray(cand.content.parts)) ? cand.content.parts : [];
+}
+
+async function reply({ fetchImpl, key, system, prompt, files }) {
+  const out = await post(fetchImpl, key, MODELS.reply, {
+    systemInstruction: { parts: [{ text: system }] },
+    contents: [{ role: 'user', parts: parts(prompt, files) }],
+  });
+  const text = out.filter((p) => typeof p.text === 'string').map((p) => p.text).join('').trim();
+  if (!text) throw new ProviderError('provider_empty', 'Google returned no reply.');
+  return { text, costMicro: null };
+}
+
+async function images({ fetchImpl, key, system, brief, files }) {
+  const out = await post(fetchImpl, key, MODELS.images, {
+    systemInstruction: { parts: [{ text: system }] },
+    contents: [{ role: 'user', parts: parts(brief, (files || []).filter((f) => f.content_type !== 'application/pdf')) }],
+    generationConfig: { responseModalities: ['TEXT', 'IMAGE'] },
+  });
+  const list = out
+    .map((p) => p.inlineData || p.inline_data)
+    .filter((d) => d && /^image\/(png|jpeg|webp)$/.test(d.mimeType || d.mime_type) && d.data)
+    .map((d) => ({ content_type: d.mimeType || d.mime_type, base64: d.data }));
+  if (!list.length) throw new ProviderError('provider_no_images', 'Google returned no images.');
+  return { images: list, costMicro: null };
+}
+
+module.exports = { BASE, reply, images };

package/modules/ai-studio/generate.js

@@ -0,0 +1,119 @@
+// modules/ai-studio/generate.js — running one submitted generation end to end
+// (task 1004917, goal 1000136, ADR 0392): the Gemini reply, then the images,
+// paid for on our key through billing.runPaid, with the result stored on the
+// request row.
+//
+// Everything with a side effect is handed in (`deps`): the provider calls, the
+// payments backend, the db, the logger, our key. So the whole path runs in a
+// test with fakes, and the route only wires the real ones.
+
+'use strict';
+
+const S = require('./studio');
+const { runPaid, BillingRefusal } = require('./billing');
+
+// deps: { db, payments, providers: { reply, images }, fetchImpl, ourKey, context, log }
+// request: { id, builder_id, prompt }, files: [{ name, content_type, base64 }] (studio.forProvider)
+async function runOnOurKey(request, files, deps) {
+  const { db, payments, providers, fetchImpl, ourKey, context, log } = deps;
+  if (!ourKey) {
+    await db.finishRequest(request.id, { status: 'refused', error: 'Generations on our key are not set up here yet. Add your own key in Settings.' });
+    return { status: 'refused', code: 'our_key_not_configured' };
+  }
+  await db.markRunning(request.id, 'ours');
+  const ledger = (row) => db.appendLedger({ ...row, backend: payments.name });
+
+  let paid;
+  try {
+    paid = await runPaid({
+      builderId: request.builder_id,
+      requestId: String(request.id),
+      maxCostMicro: S.MAX_COST_MICRO,
+      payments,
+      ledger,
+      log,
+      run: async () => {
+        const r = await providers.reply({ fetchImpl, key: ourKey, system: context, prompt: request.prompt, files });
+        const im = await providers.images({ fetchImpl, key: ourKey, system: context, brief: S.imageBrief(request.prompt, r.text), files });
+        return { costMicro: r.costMicro + im.costMicro, result: { reply: r.text, images: im.images } };
+      },
+    });
+  } catch (err) {
+    const refused = err instanceof BillingRefusal;
+    await db.finishRequest(request.id, {
+      status: refused ? 'refused' : 'failed',
+      error: refused ? err.message : `${err.message || 'The generation failed.'} You were not charged.`,
+    });
+    if (!refused && log) log.warn({ request_id: request.id, code: err.code }, 'ai generation failed; hold released');
+    return { status: refused ? 'refused' : 'failed', code: err.code };
+  }
+
+  // Paid from here on: a storage failure must not be reported as "not charged".
+  const { result, charge } = paid;
+  const receipt = { provider_cost_micro: charge.provider_cost_micro, markup_micro: charge.markup_micro, price_micro: charge.price_micro };
+  try {
+    for (const img of result.images) await db.addOutput(request.id, request.builder_id, img);
+    await db.finishRequest(request.id, { status: 'done', reply_md: result.reply, ...receipt });
+    return { status: 'done', charge };
+  } catch (err) {
+    if (log) log.error({ request_id: request.id, err: err.message }, 'ai generation paid but its result could not be stored');
+    await db.finishRequest(request.id, {
+      status: 'failed', reply_md: result.reply, ...receipt,
+      error: 'The images were made and paid for, but could not be saved. Ask the project owner to look into it.',
+    }).catch(() => {});
+    return { status: 'failed', code: 'store_failed', charge };
+  }
+}
+
+// On the builder's OWN key (task 1004918, ADR 0392 decision 8): the same two
+// calls, but no money moves. Nothing is held, captured or released, the
+// payments backend is never even handed in, and the ledger gets one own_key row
+// noting what the provider reported it cost them (null when it reports nothing,
+// as Google does).
+//
+// deps: { db, providers, fetchImpl, key, provider, context, log }
+async function runOnOwnKey(request, files, deps) {
+  const { db, providers, fetchImpl, key, provider, context, log } = deps;
+  await db.markRunning(request.id, 'own');
+  let result;
+  let cost = null;
+  try {
+    const r = await providers.reply({ fetchImpl, key, system: context, prompt: request.prompt, files });
+    const im = await providers.images({ fetchImpl, key, system: context, brief: S.imageBrief(request.prompt, r.text), files });
+    cost = Number.isSafeInteger(r.costMicro) && Number.isSafeInteger(im.costMicro) ? r.costMicro + im.costMicro : null;
+    result = { reply: r.text, images: im.images };
+  } catch (err) {
+    await db.finishRequest(request.id, {
+      status: 'failed',
+      error: `${err.message || 'The generation failed.'} Nothing was charged by us; your provider may bill you for any part that ran.`,
+    });
+    if (log) log.warn({ request_id: request.id, provider, code: err.code }, 'ai generation on own key failed');
+    return { status: 'failed', code: err.code };
+  }
+
+  try {
+    await db.appendLedger({
+      builderId: request.builder_id, requestId: String(request.id), kind: 'own_key', amountMicro: 0,
+      providerCostMicro: cost || 0, backend: 'own_key',
+      note: cost === null ? `on your own ${provider} key; the provider did not report a cost` : `on your own ${provider} key`,
+    });
+  } catch (err) {
+    if (log) log.error({ request_id: request.id, err: err.message }, 'ai-studio own-key ledger write failed');
+  }
+  try {
+    for (const img of result.images) await db.addOutput(request.id, request.builder_id, img);
+    await db.finishRequest(request.id, {
+      status: 'done', reply_md: result.reply, provider_cost_micro: cost, markup_micro: 0, price_micro: 0,
+    });
+    return { status: 'done', costMicro: cost };
+  } catch (err) {
+    if (log) log.error({ request_id: request.id, err: err.message }, 'ai generation on own key ran but its result could not be stored');
+    await db.finishRequest(request.id, {
+      status: 'failed', reply_md: result.reply, provider_cost_micro: cost, markup_micro: 0, price_micro: 0,
+      error: 'The images were made on your key, but could not be saved. Ask the project owner to look into it.',
+    }).catch(() => {});
+    return { status: 'failed', code: 'store_failed' };
+  }
+}
+
+module.exports = { runOnOurKey, runOnOwnKey };

package/modules/ai-studio/keys.js

@@ -0,0 +1,73 @@
+// modules/ai-studio/keys.js — a builder's own AI provider keys (task 1004919,
+// goal 1000136, ADR 0392 decision 8).
+//
+// A key is entered ONLY on the Settings page, stored encrypted with the kernel's
+// secret box, and shown back only as its last four characters. Nothing in this
+// module returns a plaintext key to a route, and `publicKey` is the one shape a
+// route may send: it has no field that could carry the key or its ciphertext.
+//
+// Pure: the encrypt/decrypt functions are handed in, so a test runs it with no
+// master key and no DB.
+
+'use strict';
+
+// The providers a builder may bring a key for. A new one is a new entry here
+// plus whatever calls it; the Settings card renders this list.
+const PROVIDERS = Object.freeze({
+  openrouter: { label: 'OpenRouter', learn_more_url: 'https://openrouter.ai/settings/keys' },
+  gemini: { label: 'Google AI Studio (Gemini)', learn_more_url: 'https://aistudio.google.com/app/apikey' },
+});
+
+const MIN_KEY = 16;
+const MAX_KEY = 512;
+
+function isProvider(p) { return typeof p === 'string' && Object.prototype.hasOwnProperty.call(PROVIDERS, p); }
+
+// Trims and sanity-checks a pasted key. Returns { key } or { error }. It never
+// echoes the key back inside the error.
+function cleanKey(raw) {
+  if (typeof raw !== 'string') return { error: 'key_required' };
+  const key = raw.trim();
+  if (!key) return { error: 'key_required' };
+  if (key.length < MIN_KEY || key.length > MAX_KEY) return { error: 'key_wrong_length' };
+  if (/\s/.test(key)) return { error: 'key_has_spaces' };
+  return { key };
+}
+
+function last4(key) { return key.slice(-4); }
+
+// The only shape a route sends for a stored key: which provider, whether one is
+// set, its last four characters and when. Built field by field from the row so
+// a new column can never leak through a spread.
+function publicKey(provider, row) {
+  return {
+    provider,
+    label: PROVIDERS[provider].label,
+    learn_more_url: PROVIDERS[provider].learn_more_url,
+    set: !!(row && row.key_enc),
+    last4: row && row.key_enc ? row.last4 : null,
+    set_at: row && row.key_enc ? row.set_at : null,
+  };
+}
+
+// Every provider in display order, merged with the builder's stored rows.
+function listPublic(rows) {
+  const byProvider = new Map((rows || []).map((r) => [r.provider, r]));
+  return Object.keys(PROVIDERS).map((p) => publicKey(p, byProvider.get(p)));
+}
+
+// Which key a generation runs on (task 1004918). `stored` is the providers the
+// builder has a key for; `payWith` is what they asked for: 'own', 'ours' or
+// nothing. With nothing asked, their own key wins whenever they have one, so a
+// builder who linked a key is never charged by surprise. OpenRouter is
+// preferred over Gemini when both are set: it reports its cost.
+// Returns { source: 'own', provider } | { source: 'ours' } | { error }.
+function chooseKey(stored, payWith) {
+  const own = ['openrouter', 'gemini'].find((p) => (stored || []).includes(p));
+  if (payWith === 'ours') return { source: 'ours' };
+  if (payWith === 'own' && !own) return { error: 'no_own_key' };
+  if (payWith !== undefined && payWith !== null && payWith !== 'own') return { error: 'bad_pay_with' };
+  return own ? { source: 'own', provider: own } : { source: 'ours' };
+}
+
+module.exports = { PROVIDERS, MIN_KEY, MAX_KEY, isProvider, cleanKey, last4, publicKey, listPublic, chooseKey };

package/modules/ai-studio/migrations/ai_studio_001_keys.sql

@@ -0,0 +1,22 @@
+-- ai_studio_001_keys.sql — a builder's own AI provider keys, encrypted at rest
+-- (task 1004919, goal 1000136, ADR 0388 decision 8).
+--
+-- One row per builder and provider. key_enc is the kernel secret box's blob
+-- ("v1.<iv>.<tag>.<ct>"); the master key lives only in server env, so a database
+-- dump alone decrypts nothing. last4 is shown in Settings ("…ABCD") and is not a
+-- secret. Removing a key deletes the row.
+
+CREATE TABLE IF NOT EXISTS ai_studio_provider_keys (
+  builder_id  BIGINT      NOT NULL REFERENCES builders(id),
+  provider    TEXT        NOT NULL,
+  key_enc     TEXT        NOT NULL,
+  last4       TEXT        NOT NULL,
+  set_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (builder_id, provider),
+  CONSTRAINT ai_studio_provider_keys_provider_chk CHECK (provider IN ('openrouter', 'gemini')),
+  CONSTRAINT ai_studio_provider_keys_last4_chk CHECK (length(last4) = 4),
+  CONSTRAINT ai_studio_provider_keys_enc_chk CHECK (key_enc LIKE 'v1.%')
+);
+
+INSERT INTO schema_migrations (version) VALUES ('ai_studio_001_keys')
+  ON CONFLICT DO NOTHING;

package/modules/ai-studio/migrations/ai_studio_002_ledger.sql

@@ -0,0 +1,48 @@
+-- ai_studio_002_ledger.sql — the append-only record of every AI-studio money
+-- movement (task 1004920, goal 1000136, ADR 0392 decision 6).
+--
+-- Bongos holds no user money (ADR 0385): the balance lives with the payment
+-- processor, so there is deliberately NO balance column anywhere here. What we
+-- keep is the record of each movement and its cause, which that ADR requires:
+--
+--   topup    a card payment credited to the processor-held balance
+--   hold     the full price reserved before a generation runs
+--   capture  the real price taken after it ran (cost and markup apart)
+--   release  a hold returned, e.g. because the provider failed
+--   own_key  a generation on the builder's own key: no money moved, cost noted
+--
+-- Amounts are integer micro-dollars. Rows are never updated or deleted (the
+-- trigger below refuses both), so the record cannot be rewritten.
+
+CREATE TABLE IF NOT EXISTS ai_studio_ledger (
+  id                   BIGSERIAL   PRIMARY KEY,
+  builder_id           BIGINT      NOT NULL REFERENCES builders(id),
+  kind                 TEXT        NOT NULL,
+  request_id           TEXT,
+  amount_micro         BIGINT      NOT NULL DEFAULT 0,
+  provider_cost_micro  BIGINT      NOT NULL DEFAULT 0,
+  markup_micro         BIGINT      NOT NULL DEFAULT 0,
+  processor_fee_micro  BIGINT      NOT NULL DEFAULT 0,
+  backend              TEXT        NOT NULL,
+  ref                  TEXT,
+  note                 TEXT        NOT NULL DEFAULT '',
+  created_at           TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT ai_studio_ledger_kind_chk CHECK (kind IN ('topup', 'hold', 'capture', 'release', 'own_key')),
+  CONSTRAINT ai_studio_ledger_amounts_chk CHECK (amount_micro >= 0 AND provider_cost_micro >= 0 AND markup_micro >= 0 AND processor_fee_micro >= 0),
+  CONSTRAINT ai_studio_ledger_note_chk CHECK (length(note) <= 300)
+);
+CREATE INDEX IF NOT EXISTS ai_studio_ledger_by_builder ON ai_studio_ledger (builder_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS ai_studio_ledger_by_request ON ai_studio_ledger (request_id) WHERE request_id IS NOT NULL;
+
+CREATE OR REPLACE FUNCTION ai_studio_ledger_append_only() RETURNS trigger AS $$
+BEGIN
+  RAISE EXCEPTION 'ai_studio_ledger is append-only';
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS ai_studio_ledger_no_rewrite ON ai_studio_ledger;
+CREATE TRIGGER ai_studio_ledger_no_rewrite BEFORE UPDATE OR DELETE ON ai_studio_ledger
+  FOR EACH ROW EXECUTE FUNCTION ai_studio_ledger_append_only();
+
+INSERT INTO schema_migrations (version) VALUES ('ai_studio_002_ledger')
+  ON CONFLICT DO NOTHING;

package/modules/ai-studio/migrations/ai_studio_003_requests.sql

@@ -0,0 +1,55 @@
+-- ai_studio_003_requests.sql — an artist's generation requests and the files on
+-- them (task 1004917, goal 1000136, ADR 0392).
+--
+--   ai_studio_requests  one submission: the prompt, which key paid (ours or the
+--                       builder's own), where it stands, the reply, and the
+--                       price split into provider cost and markup.
+--   ai_studio_files     the sketches and documents the artist uploaded (role
+--                       'upload') and the images that came back ('output').
+--                       An upload is stored first with no request, then
+--                       attached when the request is sent.
+--
+-- Amounts are integer micro-dollars. The money record itself is the ledger
+-- (ai_studio_002); the price here is the request's own receipt.
+
+CREATE TABLE IF NOT EXISTS ai_studio_requests (
+  id                   BIGSERIAL   PRIMARY KEY,
+  builder_id           BIGINT      NOT NULL REFERENCES builders(id),
+  prompt               TEXT        NOT NULL,
+  key_source           TEXT,
+  status               TEXT        NOT NULL DEFAULT 'queued',
+  reply_md             TEXT,
+  provider_cost_micro  BIGINT,
+  markup_micro         BIGINT,
+  price_micro          BIGINT,
+  error                TEXT,
+  created_at           TIMESTAMPTZ NOT NULL DEFAULT now(),
+  finished_at          TIMESTAMPTZ,
+  CONSTRAINT ai_studio_requests_status_chk CHECK (status IN ('queued', 'running', 'done', 'failed', 'refused')),
+  CONSTRAINT ai_studio_requests_key_chk CHECK (key_source IS NULL OR key_source IN ('ours', 'own')),
+  CONSTRAINT ai_studio_requests_money_chk CHECK (
+    COALESCE(provider_cost_micro, 0) >= 0 AND COALESCE(markup_micro, 0) >= 0 AND COALESCE(price_micro, 0) >= 0)
+);
+
+CREATE INDEX IF NOT EXISTS ai_studio_requests_builder_idx ON ai_studio_requests (builder_id, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS ai_studio_files (
+  id            BIGSERIAL   PRIMARY KEY,
+  builder_id    BIGINT      NOT NULL REFERENCES builders(id),
+  request_id    BIGINT      REFERENCES ai_studio_requests(id) ON DELETE CASCADE,
+  role          TEXT        NOT NULL,
+  name          TEXT        NOT NULL,
+  content_type  TEXT        NOT NULL,
+  size_bytes    INTEGER     NOT NULL,
+  bytes         BYTEA       NOT NULL,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT ai_studio_files_role_chk CHECK (role IN ('upload', 'output')),
+  CONSTRAINT ai_studio_files_type_chk CHECK (content_type IN ('image/png', 'image/jpeg', 'image/gif', 'image/webp', 'application/pdf')),
+  CONSTRAINT ai_studio_files_size_chk CHECK (size_bytes > 0 AND size_bytes <= 8388608)
+);
+
+CREATE INDEX IF NOT EXISTS ai_studio_files_request_idx ON ai_studio_files (request_id);
+CREATE INDEX IF NOT EXISTS ai_studio_files_builder_idx ON ai_studio_files (builder_id, created_at DESC);
+
+INSERT INTO schema_migrations (version) VALUES ('ai_studio_003_requests')
+  ON CONFLICT DO NOTHING;