@bongos/core 1.19.1058 → 1.19.1060

package/tests/copy_desk_page_claim.mjs

@@ -0,0 +1,219 @@
+// tests/copy_desk_page_claim.mjs — claim a page, and ask for one, the WHOLE path
+// (task 1004317 / BV2.TW06, ADR 0341 D2, D5, D6).
+//
+// The done-when: an artist claims a page; a second artist is refused with the
+// holder named; a non-artist can ask but not claim.
+//
+// Driven through the real copy-desk routes, the real lifecycle port
+// (webClaimPageTweak, and the real createTask under it), the real flag SQL and
+// the real error envelope, against a STATEFUL fake pool: a small in-memory
+// tasks / claims / builders / copy_desk_flags ledger that answers the SQL those
+// paths send. The fake models the page's advisory lock as a real mutex, so the
+// "two artists at once" case is a race the lock has to win, not two calls in a
+// row.
+
+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';
+import { makeRunner } from './helpers.mjs';
+import { installPageLedger } from './fixtures/page-ledger.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const F = require('../modules/copy-desk/tests/fixtures/page-tweak.cjs');
+const api = require('../src/module-api.js');
+
+// --- the ledger: the shared stateful fake (tests/fixtures/page-ledger.mjs) ---
+const { db, seen } = installPageLedger(api, {
+  builders: [
+    { id: '7', github_login: 'alice', display_name: 'Alice', preferred_disciplines: ['artist'] },
+    { id: '8', github_login: 'bob', display_name: 'Bob', preferred_disciplines: ['engineer', 'artist'] },
+    { id: '9', github_login: 'carol', display_name: 'Carol', preferred_disciplines: ['engineer'] },
+  ],
+});
+const ALICE = '7';
+const BOB = '8';
+const CAROL = '9';
+
+api.requireBuilder = (req, res, next) => {
+  req.builder = { id: String(req.headers['x-builder'] || ALICE), rank: 'metic' };
+  next();
+};
+
+const seams = require('../src/module-seams.js');
+const lifecyclePort = require('../modules/lifecycle/lifecycle.js');
+if (!seams.hasProvider('lifecycle')) seams.registerProvider('lifecycle', lifecyclePort);
+
+const pageData = require('../modules/copy-desk/page-data.js');
+const express = require('express');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const buildRouter = require('../modules/copy-desk/routes/copy-desk.js');
+
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use(buildRouter());
+const server = await new Promise((resolve) => { const s = app.listen(0, '127.0.0.1', () => resolve(s)); });
+const base = `http://127.0.0.1:${server.address().port}`;
+
+async function post(p, builder, body = {}) {
+  const r = await fetch(base + p, { method: 'POST', headers: { 'content-type': 'application/json', 'x-builder': builder }, body: JSON.stringify(body) });
+  return { status: r.status, body: await r.json() };
+}
+const errCode = (b) => (b && b.error && b.error.code) || null;
+const errDetail = (b) => (b && b.error && b.error.details) || {};
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'page-claim-'));
+fs.mkdirSync(path.join(tmp, 'docs'), { recursive: true });
+fs.writeFileSync(path.join(tmp, 'docs/page-inventory.json'), JSON.stringify(F.INVENTORY));
+
+const { test, summary } = makeRunner();
+const STUDIO = '/copy-desk/pages/builders:studio';
+
+try {
+  pageData._setRoot(tmp);
+
+  await test('an artist claims a page: one round is created and web-claimed, in the building version', async () => {
+    const { status, body } = await post(`${STUDIO}/claim`, ALICE);
+    assert.equal(status, 201, JSON.stringify(body));
+    assert.equal(body.outcome, 'created');
+    assert.equal(body.round.state, 'writing');
+    assert.equal(body.round.round, 1);
+    assert.equal(body.round.source_ref, 'page-tweak/builders:studio/r1');
+    const t = db.tasks[0];
+    assert.equal(db.tasks.length, 1);
+    assert.deepEqual(
+      [t.source, t.source_ref, t.title, t.kind, t.discipline, t.credits_reward, t.version_id, t.goal_id, t.status],
+      ['page-tweak', 'page-tweak/builders:studio/r1', 'Tweak: Studio (builders:studio)', 'feature', 'artist', 30, 'V9', '77', 'active']
+    );
+    assert.deepEqual(t.touches, F.STUDIO_FILES, 'touches are the inventory page files');
+    const c = db.claims[0];
+    assert.deepEqual([c.builder_id, c.worktree_name, c.creator_session_id], [ALICE, null, null], 'a web claim: no worktree, no session');
+  });
+
+  await test('the holder claiming again is Resume: the same round, nothing new', async () => {
+    const { status, body } = await post(`${STUDIO}/claim`, ALICE);
+    assert.equal(status, 200);
+    assert.equal(body.outcome, 'resumed');
+    assert.equal(body.round.task_id, db.tasks[0].id);
+    assert.equal(db.tasks.length, 1);
+    assert.equal(db.claims.length, 1);
+  });
+
+  await test('a second artist is refused page_held, with the holder named', async () => {
+    const { status, body } = await post(`${STUDIO}/claim`, BOB);
+    assert.equal(status, 409);
+    assert.equal(errCode(body), 'page_held');
+    assert.deepEqual(errDetail(body).holder, { id: ALICE, login: 'alice', name: 'Alice' });
+    assert.match(errDetail(body).what_this_means, /Alice is writing this page/);
+    assert.equal(db.tasks.length, 1);
+    assert.equal(db.claims.length, 1);
+  });
+
+  await test('a non-artist is refused not_an_artist and offered the ask, and nothing is written', async () => {
+    const before = seen.length;
+    const { status, body } = await post('/copy-desk/pages/landing:index/claim', CAROL);
+    assert.equal(status, 403);
+    assert.equal(errCode(body), 'not_an_artist');
+    assert.ok(errDetail(body).your_options.some((o) => /asks/.test(o)));
+    assert.equal(seen.slice(before).some((q) => /^INSERT/.test(q)), false);
+  });
+
+  await test('a non-artist CAN ask: a page-scoped flag row, and a second ask returns the first', async () => {
+    const first = await post('/copy-desk/pages/landing:index/asks', CAROL, { reason: 'The hero says nothing about what this is.' });
+    assert.equal(first.status, 201, JSON.stringify(first.body));
+    assert.equal(first.body.created, true);
+    assert.deepEqual([first.body.ask.scope, first.body.ask.page_id, first.body.ask.surface], ['page', 'landing:index', 'landing:index']);
+    assert.equal(first.body.askers, 1);
+    const again = await post('/copy-desk/pages/landing:index/asks', CAROL, { reason: 'Asking a second time, same page.' });
+    assert.equal(again.status, 200);
+    assert.equal(again.body.created, false);
+    assert.equal(again.body.ask.id, first.body.ask.id);
+    const other = await post('/copy-desk/pages/landing:index/asks', BOB, { reason: 'Agreed, the hero needs a line.' });
+    assert.equal(other.status, 201);
+    assert.equal(other.body.askers, 2, 'distinct askers');
+    // One builder may ask for several pages of one surface (the reason surface = page id).
+    const second = await post('/copy-desk/pages/landing:projects/asks', CAROL, { reason: 'The project cards read the same.' });
+    assert.equal(second.status, 201);
+  });
+
+  await test('an ask keeps the reason floor; an unknown page is unknown_page; the body is strict', async () => {
+    const thin = await post('/copy-desk/pages/landing:index/asks', BOB, { reason: 'fix' });
+    assert.equal(errCode(thin.body), 'reason_too_thin');
+    const unknown = await post('/copy-desk/pages/landing:nope/claim', ALICE);
+    assert.equal(unknown.status, 404);
+    assert.equal(errCode(unknown.body), 'unknown_page');
+    const smuggled = await post('/copy-desk/pages/landing:index/claim', ALICE, { builder_id: BOB });
+    assert.equal(errCode(smuggled.body), 'validation_failed');
+  });
+
+  await test('two artists claiming one page at once: exactly one round, the other named as held', async () => {
+    const [a, b] = await Promise.all([
+      post('/copy-desk/pages/status:explore/claim', ALICE),
+      post('/copy-desk/pages/status:explore/claim', BOB),
+    ]);
+    const statuses = [a.status, b.status].sort();
+    assert.deepEqual(statuses, [201, 409]);
+    const loser = a.status === 409 ? a : b;
+    assert.equal(errCode(loser.body), 'page_held');
+    assert.equal(db.tasks.filter((t) => t.source_ref.startsWith('page-tweak/status:explore/')).length, 1);
+  });
+
+  await test('an unheld draft is taken over; a submitted round is page_in_flight', async () => {
+    // Alice releases her studio round without submitting: it is a draft.
+    const studio = db.tasks[0];
+    db.claims.find((c) => c.task_id === studio.id).released_at = new Date().toISOString();
+    studio.status = 'ready';
+    studio.description += '\n\n' + require('../modules/copy-desk/pages.js').composeDraftBlock({ page_id: 'builders:studio', reading_hash: 'h', saved_at: 'x', lines: [] });
+    const taken = await post(`${STUDIO}/claim`, BOB);
+    assert.equal(taken.status, 200, JSON.stringify(taken.body));
+    assert.equal(taken.body.outcome, 'claimed');
+    assert.equal(taken.body.round.task_id, studio.id, 'the same round: the draft stays');
+    assert.match(studio.description, /```page-tweak-draft/);
+
+    // Bob submits: the claim is released and a batch is frozen.
+    db.claims.find((c) => c.task_id === studio.id && c.released_at == null).released_at = new Date().toISOString();
+    studio.status = 'ready';
+    studio.description += '\n\n```page-tweak\n{"schema":1}\n```';
+    const refused = await post(`${STUDIO}/claim`, ALICE);
+    assert.equal(refused.status, 409);
+    assert.equal(errCode(refused.body), 'page_in_flight');
+  });
+
+  await test('after a round ships, the next claim opens round 2, and the open asks resolve', async () => {
+    const studio = db.tasks[0];
+    studio.status = 'shipped';
+    studio.shipped_by = BOB;
+    studio.shipped_at = new Date(Date.now() + 1000).toISOString();
+    await post('/copy-desk/pages/builders:studio/asks', CAROL, { reason: 'Studio greeting reads cold.' });
+    // The ship event: the port's getTask is the one read it needs.
+    const resolved = await buildRouter.resolveAsksOnShip({ id: studio.id }, {
+      lifecycle: { getTask: async () => ({ ...studio }) },
+    });
+    assert.equal(resolved.length, 1);
+    const ask = db.flags.find((x) => x.page_id === 'builders:studio');
+    assert.deepEqual([ask.status, ask.resolved_task_id, ask.resolved_by], ['resolved', studio.id, BOB]);
+    // Not a page tweak: nothing is touched.
+    assert.deepEqual(await buildRouter.resolveAsksOnShip({ id: '1' }, { lifecycle: { getTask: async () => ({ id: '1', source: 'copy-proposal', status: 'shipped' }) } }), []);
+
+    const next = await post(`${STUDIO}/claim`, ALICE);
+    assert.equal(next.status, 201);
+    assert.equal(next.body.round.source_ref, 'page-tweak/builders:studio/r2');
+  });
+
+  await test('nothing building: a new round is no_open_version, and nothing is created', async () => {
+    db.building = false;
+    const before = db.tasks.length;
+    const r = await post('/copy-desk/pages/landing:projects/claim', ALICE);
+    assert.equal(r.status, 503);
+    assert.equal(errCode(r.body), 'no_open_version');
+    assert.equal(db.tasks.length, before);
+    db.building = true;
+  });
+} finally {
+  server.close();
+  pageData._setRoot(null);
+}
+summary();

package/tests/copy_desk_page_next.mjs

@@ -0,0 +1,172 @@
+// tests/copy_desk_page_next.mjs — "recommend the next page" and "take next",
+// the WHOLE path (task 1004318 / BV2.TW07, ADR 0341 D5, D8, D11).
+//
+// The done-when: the recommendation follows the order on a fixture, skips held
+// pages, and "take next" claims the recommended page in one call.
+//
+// modules/copy-desk/tests/copy_page_next.mjs proves the order on hand-shaped
+// rows. This drives the path those rows travel: GET /copy-desk/next through
+// the real route, the real lifecycle read (listPageTweakTasks) and the real
+// page-ask summary SQL, then POST the recommendation's own `take` path through
+// the real page claim (webClaimPageTweak, createTask), all against one stateful
+// fake ledger (tests/fixtures/page-ledger.mjs). So a claim made by "take next"
+// is what the next read sees, with no hand-built rows in between.
+
+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';
+import { makeRunner } from './helpers.mjs';
+import { installPageLedger } from './fixtures/page-ledger.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const F = require('../modules/copy-desk/tests/fixtures/page-tweak.cjs');
+const pages = require('../modules/copy-desk/pages.js');
+const api = require('../src/module-api.js');
+
+const { db } = installPageLedger(api, {
+  builders: [
+    { id: '7', github_login: 'alice', display_name: 'Alice', preferred_disciplines: ['artist'] },
+    { id: '8', github_login: 'bob', display_name: 'Bob', preferred_disciplines: ['artist'] },
+    { id: '9', github_login: 'carol', display_name: 'Carol', preferred_disciplines: ['engineer'] },
+  ],
+});
+const ALICE = '7';
+const BOB = '8';
+const CAROL = '9';
+
+api.requireBuilder = (req, res, next) => {
+  req.builder = { id: String(req.headers['x-builder'] || ALICE), rank: 'thetes' };
+  next();
+};
+
+const seams = require('../src/module-seams.js');
+if (!seams.hasProvider('lifecycle')) seams.registerProvider('lifecycle', require('../modules/lifecycle/lifecycle.js'));
+
+const pageData = require('../modules/copy-desk/page-data.js');
+const express = require('express');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const buildRouter = require('../modules/copy-desk/routes/copy-desk.js');
+
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use(buildRouter());
+const server = await new Promise((resolve) => { const s = app.listen(0, '127.0.0.1', () => resolve(s)); });
+const base = `http://127.0.0.1:${server.address().port}`;
+
+async function call(method, p, builder, body) {
+  const r = await fetch(base + p, {
+    method, headers: { 'content-type': 'application/json', 'x-builder': builder },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  });
+  return { status: r.status, body: await r.json() };
+}
+const getNext = (builder) => call('GET', '/copy-desk/next', builder);
+const errCode = (b) => (b && b.error && b.error.code) || null;
+const order = (b) => [b.recommended, ...b.alternatives].filter(Boolean).map((c) => c.page_id);
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'page-next-'));
+fs.mkdirSync(path.join(tmp, 'docs'), { recursive: true });
+fs.writeFileSync(path.join(tmp, 'docs/page-inventory.json'), JSON.stringify(F.INVENTORY));
+fs.writeFileSync(path.join(tmp, 'docs/page-readings.json'), JSON.stringify(F.READINGS));
+
+// The world before anyone asks: builders:studio was tweaked once by alice
+// (her web claim, released at submit), and has drifted since ("Welcome home"
+// became "Welcome back"). Every other page is untweaked.
+db.tasks.push({
+  id: '4001', status: 'shipped', title: 'Tweak: Studio (builders:studio)', source: 'page-tweak',
+  source_ref: pages.roundSourceRef('builders:studio', 1), touches: F.STUDIO_FILES,
+  shipped_at: '2026-09-20T10:00:00.000Z',
+  description: F.describe({
+    pageId: 'builders:studio', submittedAt: '2026-09-19T10:00:00Z',
+    lines: [{ key: 'L0002', section: 'greeting', before: 'Welcome', after: 'Welcome home' }],
+    appliedAt: '2026-09-19T18:00:00Z', linesAfter: ['Welcome home', 'Resume'],
+  }),
+});
+db.claims.push({ id: '8001', task_id: '4001', builder_id: ALICE, worktree_name: null, creator_session_id: null, claimed_at: '2026-09-18T10:00:00.000Z', released_at: '2026-09-19T10:00:00.000Z' });
+db.grades.set('4001', true);
+
+const { test, summary } = makeRunner();
+
+try {
+  pageData._setRoot(tmp);
+
+  await test('anyone asks; the recommendation reads asked, then changed, then untweaked', async () => {
+    assert.equal((await call('POST', '/copy-desk/pages/landing:projects/asks', CAROL, { reason: 'The project cards all read the same.' })).status, 201);
+    assert.equal((await call('POST', '/copy-desk/pages/landing:projects/asks', BOB, { reason: 'Agreed, the cards need a line each.' })).status, 201);
+    assert.equal((await call('POST', '/copy-desk/pages/status:explore/asks', CAROL, { reason: 'Explore does not say what it shows.' })).status, 201);
+
+    const { status, body } = await getNext(ALICE);
+    assert.equal(status, 200, JSON.stringify(body));
+    assert.deepEqual(order(body), ['landing:projects', 'status:explore', 'builders:studio', 'landing:index']);
+    assert.equal(body.recommended.why, '2 people asked for it');
+    assert.equal(body.recommended.why_line, 'landing · 2 people asked for it · untweaked');
+    assert.equal(body.alternatives[1].why, '1 line changed since your last pass', 'the round artist is the web claim, alice');
+    assert.equal(body.asked_pages, 2);
+    assert.equal(body.resume, null);
+    assert.deepEqual(body.skipped, []);
+    assert.equal(body.readings.ok, true);
+  });
+
+  await test('"take next" claims the recommended page in one call', async () => {
+    const { body: next } = await getNext(ALICE);
+    const before = db.tasks.length;
+    const take = await call(next.recommended.take.method, next.recommended.take.path, ALICE, {});
+    assert.equal(take.status, 201, JSON.stringify(take.body));
+    assert.equal(take.body.outcome, 'created');
+    assert.equal(take.body.page_id, next.recommended.page_id);
+    assert.equal(take.body.round.source_ref, 'page-tweak/landing:projects/r1');
+    assert.equal(db.tasks.length, before + 1);
+    const claim = db.claims.find((c) => c.task_id === take.body.round.task_id && c.released_at == null);
+    assert.deepEqual([claim.builder_id, claim.worktree_name, claim.creator_session_id], [ALICE, null, null], 'a web claim');
+  });
+
+  await test('the held page is Resume for its holder, and skipped (holder named) for everyone else', async () => {
+    const mine = (await getNext(ALICE)).body;
+    assert.equal(mine.resume.page_id, 'landing:projects');
+    assert.ok(!order(mine).includes('landing:projects'));
+    assert.equal(mine.recommended.page_id, 'status:explore');
+
+    const bobs = (await getNext(BOB)).body;
+    assert.equal(bobs.resume, null);
+    assert.ok(!order(bobs).includes('landing:projects'), 'never a page someone else holds, however many asked');
+    assert.deepEqual(bobs.skipped, [{ page_id: 'landing:projects', reason: 'page_held', state: 'writing', holder: { id: ALICE, login: 'alice' } }]);
+    assert.equal(bobs.recommended.page_id, 'status:explore');
+    assert.equal(bobs.alternatives[0].why, '1 line changed since the last pass', 'bob did not make that pass');
+  });
+
+  await test('take next for a second artist gets the next page, not the held one', async () => {
+    const { body: next } = await getNext(BOB);
+    const take = await call('POST', next.recommended.take.path, BOB, {});
+    assert.equal(take.status, 201, JSON.stringify(take.body));
+    assert.equal(take.body.page_id, 'status:explore');
+    const after = (await getNext(CAROL)).body;
+    assert.deepEqual(after.skipped.map((s) => s.page_id).sort(), ['landing:projects', 'status:explore']);
+    assert.deepEqual(order(after), ['builders:studio', 'landing:index']);
+  });
+
+  await test('a submitted round is in flight: skipped, and the claim agrees', async () => {
+    const round = db.tasks.find((t) => t.source_ref === 'page-tweak/status:explore/r1');
+    db.claims.find((c) => c.task_id === round.id && c.released_at == null).released_at = new Date().toISOString();
+    round.status = 'ready';
+    round.description += '\n\n' + pages.composeBatchBlock({ page_id: 'status:explore', reading_hash: 'h', submitted_at: 'x', lines: [{ key: 'L0001', section: 'hero', before: 'Explore', after: 'Look around', placement: 'placed', file: 'x', line: 1, string_id: 'a' }] });
+    const next = (await getNext(ALICE)).body;
+    assert.deepEqual(next.skipped, [{ page_id: 'status:explore', reason: 'page_in_flight', state: 'submitted' }]);
+    const refused = await call('POST', '/copy-desk/pages/status:explore/claim', ALICE, {});
+    assert.equal(errCode(refused.body), 'page_in_flight');
+  });
+
+  await test('no page inventory: a named 503, never a crash', async () => {
+    pageData._setRoot(fs.mkdtempSync(path.join(os.tmpdir(), 'page-next-empty-')));
+    const r = await getNext(ALICE);
+    assert.equal(r.status, 503);
+    assert.equal(errCode(r.body), 'page_inventory_missing');
+  });
+} finally {
+  server.close();
+  pageData._setRoot(null);
+}
+summary();

package/tests/fixtures/page-ledger.mjs

@@ -0,0 +1,175 @@
+// tests/fixtures/page-ledger.mjs — a STATEFUL fake pool for Tweak Mode's
+// whole-path tests: a small in-memory tasks / claims / builders /
+// copy_desk_flags ledger that answers the SQL the real copy-desk routes and the
+// real lifecycle port send (the page claim, task 1004317 / TW06; the page reads
+// and the recommendation, task 1004318 / TW07).
+//
+// The page's advisory lock is modelled as a real mutex, so a "two artists at
+// once" case is a race the lock has to win, not two calls in a row. Every
+// statement yields first, so concurrent requests really interleave.
+//
+// An unknown statement THROWS: a route that sends SQL this ledger does not
+// model fails loudly instead of reading an empty answer.
+//
+// Shared by tests/copy_desk_page_claim.mjs and tests/copy_desk_page_next.mjs
+// (a fixture, not a test: the runner discovers tests/*.mjs only).
+
+import { strict as assert } from 'node:assert';
+
+const flat = (sql) => String(sql).replace(/\s+/g, ' ').trim();
+
+export function installPageLedger(api, { builders }) {
+  const db = {
+    builders: new Map(builders.map((b) => [String(b.id), { status: 'active', ...b, id: String(b.id) }])),
+    tasks: [],
+    claims: [],
+    flags: [],
+    grades: new Map(),
+    seq: { task: 5000, claim: 9000, flag: 100 },
+    building: true,
+  };
+  const seen = [];
+
+  // The advisory lock, as a mutex per key: a second locker waits until the
+  // first commits or rolls back.
+  const locks = new Map();
+  async function lock(key, owner) {
+    while (locks.has(key)) await locks.get(key).done;
+    let release;
+    const done = new Promise((r) => { release = r; });
+    locks.set(key, { owner, done, release });
+  }
+  function unlockAll(owner) {
+    for (const [k, v] of [...locks]) if (v.owner === owner) { locks.delete(k); v.release(); }
+  }
+
+  const activeClaim = (taskId) => db.claims.find((x) => String(x.task_id) === String(taskId) && x.released_at == null) || null;
+  const isWeb = (c) => c.worktree_name == null && c.creator_session_id == null;
+
+  // listPageTweakTasks' row, column for column (modules/lifecycle/page-tweak-reads.js).
+  function pageTweakRow(t) {
+    const ac = activeClaim(t.id);
+    const web = db.claims.filter((c) => String(c.task_id) === String(t.id) && isWeb(c)).slice(-1)[0] || null;
+    const hb = ac ? db.builders.get(String(ac.builder_id)) : null;
+    const ab = web ? db.builders.get(String(web.builder_id)) : null;
+    return {
+      id: t.id, status: t.status, title: t.title, description: t.description, source_ref: t.source_ref, touches: t.touches,
+      shipped_at: t.shipped_at || null, created_at: t.created_at || null, updated_at: t.updated_at || null,
+      grade_passed: db.grades.has(String(t.id)) ? db.grades.get(String(t.id)) : null,
+      holder_id: ac ? ac.builder_id : null, holder_login: hb ? hb.github_login : null,
+      holder_worktree: ac ? ac.worktree_name != null : null,
+      artist_id: web ? web.builder_id : null, artist_login: ab ? ab.github_login : null,
+    };
+  }
+
+  async function answer(q, p, owner) {
+    seen.push(q);
+    await new Promise((r) => setImmediate(r));
+    if (/^(BEGIN|COMMIT|ROLLBACK)$/.test(q)) {
+      if (q !== 'BEGIN') unlockAll(owner);
+      return { rows: [] };
+    }
+    if (/pg_advisory_xact_lock\(hashtext\(\$1\)\)/.test(q)) {
+      assert.ok(owner, 'the page lock must be taken on the transaction client');
+      await lock(p[0], owner);
+      return { rows: [] };
+    }
+    if (/^SELECT id, status, github_login, display_name FROM builders WHERE id = \$1/.test(q)) {
+      const b = db.builders.get(String(p[0]));
+      return { rows: b ? [b] : [] };
+    }
+    if (/^SELECT preferred_disciplines FROM builders WHERE id = \$1/.test(q)) {
+      const b = db.builders.get(String(p[0]));
+      return { rows: b ? [{ preferred_disciplines: b.preferred_disciplines }] : [] };
+    }
+    if (/FROM tasks WHERE source = \$1 AND left\(source_ref, length\(\$2\)\) = \$2 ORDER BY id ASC FOR UPDATE/.test(q)) {
+      return { rows: db.tasks.filter((t) => t.source === p[0] && String(t.source_ref).startsWith(p[1])).map((t) => ({ ...t })) };
+    }
+    if (/FROM claims c JOIN builders b ON b\.id = c\.builder_id WHERE c\.task_id = \$1 AND c\.released_at IS NULL/.test(q)) {
+      const c = activeClaim(p[0]);
+      if (!c) return { rows: [] };
+      const b = db.builders.get(String(c.builder_id));
+      return { rows: [{ ...c, github_login: b.github_login, display_name: b.display_name }] };
+    }
+    if (/^INSERT INTO claims \(task_id, builder_id, worktree_name, requested_worktree_name, head_sha, creator_session_id\) VALUES \(\$1, \$2, NULL, NULL, NULL, NULL\)/.test(q)) {
+      if (activeClaim(p[0])) {
+        throw Object.assign(new Error('duplicate key'), { code: '23505', constraint: 'uniq_active_claim_per_task' });
+      }
+      const c = { id: String(++db.seq.claim), task_id: String(p[0]), builder_id: String(p[1]), worktree_name: null, creator_session_id: null, claimed_at: new Date().toISOString(), released_at: null };
+      db.claims.push(c);
+      return { rows: [{ ...c }] };
+    }
+    if (/^UPDATE tasks SET status = 'active', updated_at = now\(\) WHERE id = \$1/.test(q)) {
+      db.tasks.find((t) => String(t.id) === String(p[0])).status = 'active';
+      return { rows: [] };
+    }
+    // createTask's reads: the catch-all goal of the version, and its scope.
+    if (/FROM goals g JOIN versions v ON v\.id = g\.version_id WHERE g\.version_id = \$1 AND g\.title = \$2/.test(q)) {
+      return { rows: [{ id: '77', version_status: 'building' }] };
+    }
+    if (/^SELECT scope_modules FROM goals WHERE id = \$1/.test(q)) return { rows: [{ scope_modules: [] }] };
+    if (/^INSERT INTO tasks \(version_id, title, description, status, touches,/.test(q)) {
+      assert.ok(owner, 'the round must be created inside the claim transaction');
+      const t = {
+        id: String(++db.seq.task), version_id: p[0], title: p[1], description: p[2], status: p[3], touches: p[4],
+        credits_reward: p[10], source: p[11], source_ref: p[12], kind: p[14], discipline: p[15], requires_rank: p[20], goal_id: p[22], created_by: p[23],
+      };
+      db.tasks.push(t);
+      return { rows: [{ ...t }] };
+    }
+    if (/^SELECT id, name, status, scope_doc_path, started_at, shipped_at, done_when FROM versions/.test(q)) {
+      return { rows: db.building ? [{ id: 'V9', name: 'V9', status: 'building' }] : [{ id: 'V8', name: 'V8', status: 'shipped' }] };
+    }
+    // The page reads (listPageTweakTasks), computed from the ledger's state.
+    if (/FROM tasks t LEFT JOIN task_grades g/.test(q)) {
+      assert.match(q, /WHERE t\.source = 'page-tweak'/);
+      return { rows: db.tasks.filter((t) => t.source === 'page-tweak').map(pageTweakRow) };
+    }
+    // The flag SQL (the page ask).
+    if (/FROM copy_desk_flags f WHERE f\.scope = 'page' AND f\.page_id = \$1 AND f\.flagged_by = \$2 AND f\.status = 'open'/.test(q)) {
+      return { rows: db.flags.filter((x) => x.scope === 'page' && x.page_id === p[0] && String(x.flagged_by) === String(p[1]) && x.status === 'open').slice(0, 1) };
+    }
+    if (/^INSERT INTO copy_desk_flags/.test(q)) {
+      const [scope, surface, stringId, reason, kind, , , , , by, pageId] = p;
+      // The CHECKs of copy_desk_002, so the fake refuses what Postgres would.
+      assert.equal((scope === 'page'), (pageId != null), 'copy_desk_flags_target_chk');
+      if (scope === 'page') assert.equal(surface, pageId, 'copy_desk_flags_page_surface_chk');
+      const dup = db.flags.find((x) => x.status === 'open' && String(x.flagged_by) === String(by) && x.surface === surface && (x.string_id || '') === (stringId || ''));
+      if (dup) throw Object.assign(new Error('dup'), { code: '23505' });
+      const row = { id: String(++db.seq.flag), scope, surface, string_id: stringId, page_id: pageId, reason, kind, flagged_by: String(by), flagged_at: new Date().toISOString(), status: 'open' };
+      db.flags.push(row);
+      return { rows: [{ ...row }] };
+    }
+    if (/COUNT\(DISTINCT flagged_by\)::int AS askers FROM copy_desk_flags WHERE scope = 'page' AND page_id = \$1 AND status = 'open'/.test(q)) {
+      return { rows: [{ askers: new Set(db.flags.filter((x) => x.scope === 'page' && x.page_id === p[0] && x.status === 'open').map((x) => x.flagged_by)).size }] };
+    }
+    // flags.pageAskSummary: open asks grouped by page.
+    if (/^SELECT page_id, COUNT\(DISTINCT flagged_by\)::int AS askers, MIN\(flagged_at\) AS oldest_ask_at FROM copy_desk_flags WHERE scope = 'page' AND status = 'open' GROUP BY page_id$/.test(q)) {
+      const by = new Map();
+      for (const x of db.flags) {
+        if (x.scope !== 'page' || x.status !== 'open') continue;
+        const g = by.get(x.page_id) || { page_id: x.page_id, who: new Set(), oldest: null };
+        g.who.add(String(x.flagged_by));
+        if (!g.oldest || new Date(x.flagged_at) < new Date(g.oldest)) g.oldest = x.flagged_at;
+        by.set(x.page_id, g);
+      }
+      return { rows: [...by.values()].map((g) => ({ page_id: g.page_id, askers: g.who.size, oldest_ask_at: g.oldest })) };
+    }
+    if (/^UPDATE copy_desk_flags SET status = 'resolved', resolved_task_id = \$2, resolved_by = \$3/.test(q)) {
+      const hit = db.flags.filter((x) => x.scope === 'page' && x.page_id === p[0] && x.status === 'open' && new Date(x.flagged_at) <= new Date(p[3]));
+      for (const x of hit) Object.assign(x, { status: 'resolved', resolved_task_id: String(p[1]), resolved_by: String(p[2]), resolution_note: p[4] });
+      return { rows: hit.map((x) => ({ id: x.id })) };
+    }
+    throw new Error(`unexpected SQL: ${q.slice(0, 160)}`);
+  }
+
+  let clientSeq = 0;
+  api.pool = {
+    query: (sql, params = []) => answer(flat(sql), params, null),
+    async connect() {
+      const owner = ++clientSeq;
+      return { query: (sql, params = []) => answer(flat(sql), params, owner), release() { unlockAll(owner); } };
+    },
+  };
+  return { db, seen };
+}