@bongos/core 1.19.1058 → 1.19.1060

package/modules/copy-desk/tests/copy_page_next.mjs

@@ -0,0 +1,184 @@
+// modules/copy-desk/tests/copy_page_next.mjs — the recommendation, pure
+// (task 1004318 / BV2.TW07, ADR 0341 D8).
+//
+// The done-when: the recommendation follows the order on a fixture and skips
+// held pages. The fixture below has a page in every tier and every way a page
+// can be left out:
+//
+//   asked      builders:work (2 askers), landing:privacy (1, the OLDER ask),
+//              builders:tasks (1, the newer ask)
+//   changed    builders:goals (4 lines, alice's pass), status:board (1 line,
+//              bob's pass)
+//   untweaked  landing:index, builders:ideas (an unheld draft, taken over),
+//              status:explore: surface order, though the inventory lists
+//              builders first
+//   tweaked    landing:projects (twice, no drift): last
+//   skipped    builders:studio (held by bob, and asked for), landing:about
+//              (submitted: in flight)
+//
+// "Take next" through the real claim is tests/copy_desk_page_next.mjs (root).
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const pages = require('../pages.js');
+const status = require('../page-status.js');
+const F = require('./fixtures/page-tweak.cjs');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+// --- the fixture: F's four pages plus six more -----------------------------
+const page = (id, title) => ({ id, surface: id.split(':')[0], title, path: `/${id.split(':')[1]}`, files: [`${id}.html`] });
+const INVENTORY = {
+  schema: 1,
+  surfaces: F.INVENTORY.surfaces,
+  pages: [
+    ...F.INVENTORY.pages,
+    page('builders:work', 'Work'),
+    page('builders:goals', 'Goals'),
+    page('builders:tasks', 'Tasks'),
+    page('builders:ideas', 'Ideas'),
+    page('landing:privacy', 'Privacy'),
+    page('landing:about', 'About'),
+    page('status:board', 'Board'),
+  ],
+};
+const line = (key, text, placement = 'placed') => ({ key, section: 'body', text, placement });
+const READINGS = {
+  schema: 1,
+  pages: [
+    ...F.READINGS.pages,
+    { id: 'builders:goals', lines: [line('L0001', 'Nav', 'shared'), line('L0002', 'A'), line('L0003', 'W'), line('L0004', 'X'), line('L0005', 'Y'), line('L0006', 'Z')] },
+    { id: 'status:board', lines: [line('L0001', 'One'), line('L0002', 'Two, reworded')] },
+  ],
+};
+const shipped = (id, pageId, n, artist, linesAfter, at) => F.row({
+  id, status: 'shipped', source_ref: pages.roundSourceRef(pageId, n), shipped_at: new Date(at), grade_passed: true,
+  artist_id: artist.id, artist_login: artist.login,
+  description: F.describe({ pageId, submittedAt: at, lines: [{ key: 'L0002', section: 'body', before: 'b', after: 'a' }], appliedAt: at, linesAfter }),
+});
+const TASKS = [
+  ...F.TASKS,
+  shipped('401', 'builders:goals', 1, F.ALICE, ['A', 'B', 'C', 'D', 'E'], '2026-09-10T10:00:00Z'),
+  shipped('402', 'status:board', 1, F.BOB, ['One', 'Two'], '2026-09-11T10:00:00Z'),
+  // An unheld draft: released without submitting. The claim takes it over.
+  F.row({
+    id: '403', status: 'ready', source_ref: pages.roundSourceRef('builders:ideas', 1),
+    description: F.describe({ pageId: 'builders:ideas', submittedAt: '2026-09-20T10:00:00Z', draft: true, lines: [] }),
+  }),
+  // Submitted: a frozen batch, no holder. In flight.
+  F.row({
+    id: '404', status: 'ready', source_ref: pages.roundSourceRef('landing:about', 1),
+    description: F.describe({ pageId: 'landing:about', submittedAt: '2026-09-21T10:00:00Z', lines: [{ key: 'L0002', section: 'body', before: 'x', after: 'y' }] }),
+  }),
+];
+const ASKS = [
+  { page_id: 'builders:work', askers: 2, oldest_ask_at: new Date('2026-09-15T00:00:00Z') },
+  { page_id: 'landing:privacy', askers: 1, oldest_ask_at: new Date('2026-09-01T00:00:00Z') },
+  { page_id: 'builders:tasks', askers: 1, oldest_ask_at: new Date('2026-09-20T00:00:00Z') },
+  { page_id: 'builders:studio', askers: 3, oldest_ask_at: new Date('2026-08-01T00:00:00Z') },
+  { page_id: 'landing:gone', askers: 5, oldest_ask_at: new Date('2026-08-01T00:00:00Z') }, // not in the inventory
+];
+
+const next = (builderId, over = {}) => status.composeNext({ inventory: INVENTORY, readings: READINGS, tasks: TASKS, asks: ASKS, builderId, alternatives: 99, ...over });
+const order = (out) => [out.recommended, ...out.alternatives].filter(Boolean).map((c) => c.page_id);
+
+const EXPECTED = [
+  'builders:work', 'landing:privacy', 'builders:tasks',
+  'builders:goals', 'status:board',
+  'landing:index', 'builders:ideas', 'status:explore',
+  'landing:projects',
+];
+
+await test('the order on the fixture: asked, changed, untweaked (surface order), tweaked last', () => {
+  const out = next(F.ALICE.id);
+  assert.deepEqual(order(out), EXPECTED);
+  assert.deepEqual([...new Set([out.recommended, ...out.alternatives].map((c) => c.tier))], ['asked', 'changed', 'untweaked', 'tweaked']);
+  assert.equal(out.candidates, EXPECTED.length);
+});
+
+await test('held and in-flight pages are never recommended, and are named in skipped', () => {
+  const out = next(F.ALICE.id);
+  assert.ok(!order(out).includes('builders:studio'), 'held by bob, though three people asked for it');
+  assert.ok(!order(out).includes('landing:about'), 'submitted: in flight');
+  assert.deepEqual(out.skipped.map((s) => [s.page_id, s.reason]), [['builders:studio', 'page_held'], ['landing:about', 'page_in_flight']]);
+  assert.deepEqual(out.skipped[0].holder, { id: F.BOB.id, login: 'bob' });
+  assert.equal(out.skipped[1].state, 'submitted');
+  assert.equal(out.resume, null);
+});
+
+await test("the caller's own held page is Resume, not a recommendation", () => {
+  const out = next(F.BOB.id);
+  assert.equal(out.resume.page_id, 'builders:studio');
+  assert.equal(out.resume.task_id, '202');
+  assert.equal(out.resume.take.path, '/copy-desk/pages/builders:studio/claim');
+  assert.ok(!order(out).includes('builders:studio'));
+  assert.ok(!out.skipped.some((s) => s.page_id === 'builders:studio'));
+});
+
+await test("the caller's own CLI claim (applying) is in flight, not Resume", () => {
+  const tasks = TASKS.map((t) => (t.id === '202' ? { ...t, holder_worktree: true } : t));
+  const out = next(F.BOB.id, { tasks });
+  assert.equal(out.resume, null);
+  assert.deepEqual(out.skipped.find((s) => s.page_id === 'builders:studio').reason, 'page_in_flight');
+});
+
+await test('each candidate carries its why, in the mock\'s words', () => {
+  const out = next(F.ALICE.id);
+  const by = (id) => [out.recommended, ...out.alternatives].find((c) => c.page_id === id);
+  assert.equal(out.recommended.why, '2 people asked for it');
+  assert.equal(out.recommended.why_line, 'builders hall · 2 people asked for it · untweaked');
+  assert.equal(by('landing:privacy').why_line, 'landing · 1 person asked for it · untweaked');
+  assert.equal(by('builders:goals').why, '4 lines changed since your last pass', 'alice made the last pass');
+  assert.equal(by('builders:goals').changed_lines, 4, 'shared lines never count');
+  assert.equal(by('status:board').why, '1 line changed since the last pass', 'bob made it, not the caller');
+  assert.equal(by('status:explore').why_line, 'status · untweaked');
+  assert.equal(by('landing:projects').why, 'text tweaked 2x, nothing changed since');
+  assert.equal(by('builders:ideas').draft_round.task_id, '403', 'the draft the claim takes over is named');
+  assert.equal(out.recommended.take.path, '/copy-desk/pages/builders:work/claim');
+});
+
+await test('ties: more askers first, then the oldest ask; more changed lines first', () => {
+  const asks = [
+    { page_id: 'landing:privacy', askers: 1, oldest_ask_at: new Date('2026-09-25T00:00:00Z') },
+    { page_id: 'builders:tasks', askers: 1, oldest_ask_at: new Date('2026-09-02T00:00:00Z') },
+  ];
+  assert.deepEqual(order(next(F.ALICE.id, { asks })).slice(0, 2), ['builders:tasks', 'landing:privacy'], 'oldest ask wins the tie');
+  const more = [{ page_id: 'builders:tasks', askers: 3, oldest_ask_at: new Date('2026-09-26T00:00:00Z') }, ...asks];
+  assert.equal(next(F.ALICE.id, { asks: more }).recommended.page_id, 'builders:tasks');
+});
+
+await test('asked_pages counts every inventory page with an open ask, held ones too', () => {
+  assert.equal(next(F.ALICE.id).asked_pages, 4);
+});
+
+await test('pick another: the next few, four by default', () => {
+  const out = status.composeNext({ inventory: INVENTORY, readings: READINGS, tasks: TASKS, asks: ASKS, builderId: F.ALICE.id });
+  assert.equal(out.alternatives.length, status.NEXT_ALTERNATIVES);
+  assert.equal(status.NEXT_ALTERNATIVES, 4);
+  assert.deepEqual(order(out), EXPECTED.slice(0, 5));
+});
+
+await test('no readings: drift is unknown, so no page is "changed", and tweaked pages sort last', () => {
+  const out = next(F.ALICE.id, { readings: null });
+  assert.ok(![out.recommended, ...out.alternatives].some((c) => c.tier === 'changed'));
+  assert.deepEqual(order(out).slice(-3), ['landing:projects', 'builders:goals', 'status:board']);
+  assert.equal(out.alternatives.find((c) => c.page_id === 'builders:goals').why, 'text tweaked 1x');
+});
+
+await test('nothing left to take: recommended is null, never a held page', () => {
+  const inventory = { ...INVENTORY, pages: INVENTORY.pages.filter((p) => ['builders:studio', 'landing:about'].includes(p.id)) };
+  const out = next(F.ALICE.id, { inventory });
+  assert.equal(out.recommended, null);
+  assert.deepEqual(out.alternatives, []);
+  assert.equal(out.skipped.length, 2);
+});
+
+console.log(`\ncopy_page_next: ${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);

package/modules/lifecycle/lifecycle.js

@@ -25,6 +25,7 @@ const taskRecommendations = require('./task-recommendations');
 const activity = require('./activity');
 const mingle = require('./mingle');
 const pageTweakReads = require('./page-tweak-reads');
+const pageTweakClaim = require('./page-tweak-claim');
 
 module.exports = {
   // --- retired doorway leaks (ADR 0093 §3) ---------------------------------
@@ -111,6 +112,12 @@ module.exports = {
   // drift and the tally from these; there is no status table.
   listPageTweakTasks: (...a) => pageTweakReads.listPageTweakTasks(...a),
   shippedTasksTouchingSince: (...a) => pageTweakReads.shippedTasksTouchingSince(...a),
+  // The page claim (task 1004317 / BV2.TW06, ADR 0341 D2, D5): find or create a
+  // page's open tweak round and web-claim it, in one transaction under an
+  // advisory lock on the page. ADR 0341 D11 names this port entry webClaimTask;
+  // it is page-shaped because the find-or-create has to share the claim's
+  // transaction. See modules/lifecycle/page-tweak-claim.js.
+  webClaimPageTweak: (...a) => pageTweakClaim.webClaimPageTweak(...a),
   listVersions: (...a) => db.listVersions(...a),
   versionProgress: (...a) => db.versionProgress(...a),
   recentShippedTasks: (...a) => db.recentShippedTasks(...a),

package/modules/lifecycle/page-tweak-claim.js

@@ -0,0 +1,184 @@
+// modules/lifecycle/page-tweak-claim.js — the page claim: find or create a page's
+// open tweak round and WEB-claim it, in one transaction (task 1004317 / BV2.TW06,
+// ADR 0341 D2 and D5).
+//
+// On the `lifecycle` port because tasks and claims are this module's tables and
+// copy-desk may only cross the wall through a port (ADR 0083, ADR 0093 §2). What
+// a round IS (its source ref, title, body, and which unheld rounds a writer may
+// take over) is copy-desk's, and is handed in; the transaction is lifecycle's.
+//
+// THE LOCK. Everything runs under pg_advisory_xact_lock(hashtext('page-tweak/' ||
+// page_id)), so two artists claiming the same page serialise: the second reads
+// the round the first created, and is refused `held` naming the first. The page's
+// existing rounds are also read FOR UPDATE, which is the lock every other claim
+// path takes (claimTask), so a CLI claim of the same task cannot interleave.
+//
+// A WEB CLAIM (ADR 0341 D5): worktree_name NULL and creator_session_id NULL, the
+// bind_session=false claim the hall's Claim button already takes. Migration
+// core_204's one-bound-claim-per-(session, worktree) index excludes NULL sessions,
+// so a web claim never collides with the artist's CLI work, and the reads
+// (page-tweak-reads.js) recognise it by exactly those two NULLs.
+//
+// WHAT THIS DOES NOT RUN, and why. claimTask's gates are for a builder taking
+// CODE work into a worktree: the rank floor, goal membership, the owed-rebase
+// gate, dependency and touches checks. A page round is not that. Its one gate is
+// the craft (ADR 0341 D5: `builders.preferred_disciplines` includes artist, read
+// here through help-requests' own reader, never from the request), plus the
+// inactive-builder refusal every claim carries. The round has no rank floor
+// (D2), no dependencies, and its applier later takes an ordinary CLI claim
+// through claimTask with every gate intact.
+//
+// Outcomes are returned, not thrown, so the route maps each to its named answer:
+//   created | claimed | resumed        the caller now holds the round (writing)
+//   held          another builder holds it (holder named)
+//   in_flight     the round is past writing (submitted, applying, waiting for
+//                 the artist, landing), so a writing claim would pull it back
+//   not_an_artist / builder_inactive / no_open_version
+
+'use strict';
+
+const api = require('../../src/module-api');
+const db = require('./db');
+const helpRequests = require('./help-requests');
+
+const SOURCE = 'page-tweak';
+const TERMINAL = Object.freeze(['shipped', 'abandoned']);
+
+function lockKey(pageId) { return `${SOURCE}/${pageId}`; }
+
+// The claim projection the route answers with.
+const CLAIM_COLS = 'id, task_id, builder_id, worktree_name, creator_session_id, claimed_at';
+
+async function insertWebClaim(client, taskId, builderId) {
+  const { rows } = await client.query(
+    `INSERT INTO claims (task_id, builder_id, worktree_name, requested_worktree_name, head_sha, creator_session_id)
+     VALUES ($1, $2, NULL, NULL, NULL, NULL)
+     RETURNING ${CLAIM_COLS}`,
+    [taskId, builderId]
+  );
+  await client.query(`UPDATE tasks SET status = 'active', updated_at = now() WHERE id = $1`, [taskId]);
+  return rows[0];
+}
+
+// 'page-tweak/landing:index/r2' -> 2 (0 when the ref carries no round).
+function roundNumber(sourceRef) {
+  const m = /\/r([1-9][0-9]*)$/.exec(String(sourceRef || ''));
+  return m ? Number(m[1]) : 0;
+}
+
+// webClaimPageTweak({ pageId, builderId, versionId, round }, deps)
+//
+//   round.title(n), round.description(n), round.sourceRef(n)   copy-desk's format
+//   round.touches, round.creditsReward
+//   round.canTakeOver(task)   may a writer take over this UNHELD open round?
+//   versionId                 where a NEW round lands (null: nothing is building)
+//
+// deps.pool is honoured only under NODE_ENV=test (the #538 test seam).
+async function webClaimPageTweak({ pageId, builderId, versionId = null, round }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : api.pool;
+  const createTask = deps.createTask || db.createTask;
+  const prefix = `${SOURCE}/${pageId}/`;
+  const client = await activePool.connect();
+  try {
+    await client.query('BEGIN');
+    await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', [lockKey(pageId)]);
+
+    const { rows: builderRows } = await client.query(
+      'SELECT id, status, github_login, display_name FROM builders WHERE id = $1', [builderId]
+    );
+    if (!builderRows[0] || builderRows[0].status === 'inactive') {
+      await client.query('ROLLBACK');
+      return { outcome: 'builder_inactive' };
+    }
+    const crafts = await helpRequests.craftsForBuilder(builderId, { pool: client });
+    if (!crafts.includes('artist')) {
+      await client.query('ROLLBACK');
+      return { outcome: 'not_an_artist' };
+    }
+
+    // Every round of this page, oldest first. `left(...) = prefix` rather than
+    // LIKE: a page id is [a-z0-9-:], and LIKE would read an `_` as a wildcard
+    // the day the id rule widens.
+    const { rows: rounds } = await client.query(
+      `SELECT id, status, title, description, source_ref, touches, credits_reward, goal_id, version_id
+         FROM tasks
+        WHERE source = $1 AND left(source_ref, length($2)) = $2
+        ORDER BY id ASC
+        FOR UPDATE`,
+      [SOURCE, prefix]
+    );
+    const open = [...rounds].reverse().find((t) => !TERMINAL.includes(t.status)) || null;
+
+    if (open) {
+      const { rows: held } = await client.query(
+        `SELECT c.${CLAIM_COLS.split(', ').join(', c.')}, b.github_login, b.display_name
+           FROM claims c JOIN builders b ON b.id = c.builder_id
+          WHERE c.task_id = $1 AND c.released_at IS NULL
+          LIMIT 1`,
+        [open.id]
+      );
+      const claim = held[0] || null;
+      const roundNo = roundNumber(open.source_ref);
+      if (claim) {
+        const web = claim.worktree_name == null && claim.creator_session_id == null;
+        if (String(claim.builder_id) !== String(builderId)) {
+          await client.query('ROLLBACK');
+          return {
+            outcome: 'held',
+            task: open,
+            round: roundNo,
+            holder: { id: String(claim.builder_id), login: claim.github_login || null, name: claim.display_name || null },
+            holder_is_writing: web,
+          };
+        }
+        await client.query('ROLLBACK');
+        // The caller's own web claim is Resume. Their own CLI claim means they
+        // are APPLYING this round (a self-applied tweak): not writing it.
+        return web
+          ? { outcome: 'resumed', task: open, round: roundNo, claim }
+          : { outcome: 'in_flight', task: open, round: roundNo, status: open.status };
+      }
+      if (!round.canTakeOver(open)) {
+        await client.query('ROLLBACK');
+        return { outcome: 'in_flight', task: open, round: roundNo, status: open.status };
+      }
+      const taken = await insertWebClaim(client, open.id, builderId);
+      await client.query('COMMIT');
+      return { outcome: 'claimed', task: { ...open, status: 'active' }, round: roundNo, claim: taken };
+    }
+
+    if (versionId == null) {
+      await client.query('ROLLBACK');
+      return { outcome: 'no_open_version' };
+    }
+    // n = one plus the earlier rounds, whatever their status (ADR 0341 D2); the
+    // max guards the never-repeat rule if a round row was ever removed.
+    const n = Math.max(rounds.length, ...rounds.map((t) => roundNumber(t.source_ref))) + 1;
+    const task = await createTask({
+      versionId,
+      // ADR 0341 D2: a round lands in the building version's catch-all goal,
+      // exactly as a copy proposal does. Declared out loud (BV1.R11).
+      allowCatchAll: true,
+      title: round.title(n),
+      description: round.description(n),
+      status: 'ready',
+      kind: 'feature',
+      discipline: 'artist',
+      creditsReward: round.creditsReward,
+      touches: round.touches,
+      source: SOURCE,
+      sourceRef: round.sourceRef(n),
+      createdBy: builderId,
+    }, { client });
+    const claim = await insertWebClaim(client, task.id, builderId);
+    await client.query('COMMIT');
+    return { outcome: 'created', task: { ...task, status: 'active' }, round: n, claim };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+module.exports = { webClaimPageTweak, lockKey, roundNumber };

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1058",
+  "version": "1.19.1060",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.1058",
+      "version": "1.19.1060",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1058",
+  "version": "1.19.1060",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -7649,5 +7649,17 @@
       "id": "1004316",
       "text": "Every page now has a status that is worked out from the project's own record, with nothing new to keep in sync. For each page you can see whether it is untweaked or text tweaked and how many times, a history of each round (who"
     }
+  ],
+  "1.19.1059": [
+    {
+      "id": "1004317",
+      "text": "An artist can now claim a whole page to rewrite in one step. If the page has no open round, one is created for them. If someone else is already on it, they are told who. Anyone, artist or not, can ask for a page to be worked o"
+    }
+  ],
+  "1.19.1060": [
+    {
+      "id": "1004318",
+      "text": "An artist can now ask \"what should I tweak next?\" and get one page back, with the reason in plain words, such as \"2 people asked for it\". Pages people asked for come first, then pages whose words changed since their last tweak"
+    }
   ]
 }

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.1058'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1060'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/copy_desk_flags_db.mjs

@@ -78,6 +78,10 @@ await pool.query('INSERT INTO tasks (id) VALUES ($1) ON CONFLICT (id) DO NOTHING
 // migrated DB has already run it.
 const MIGRATION = fs.readFileSync(path.join(ROOT, 'modules/copy-desk/migrations/copy_desk_001_flags.sql'), 'utf8');
 await pool.query(MIGRATION);
+// TW06 (task 1004317): the page-ask widening, applied on top, twice (idempotent).
+const MIGRATION_002 = fs.readFileSync(path.join(ROOT, 'modules/copy-desk/migrations/copy_desk_002_page_asks.sql'), 'utf8');
+await pool.query(MIGRATION_002);
+await pool.query(MIGRATION_002);
 
 // Every row this test writes carries a surface nothing else uses, so cleanup is
 // exact and it can never delete a real flag.
@@ -241,6 +245,58 @@ await test('closeFlag returns null on a second call — the route answers 409 fr
   assert.equal(second, null);
 });
 
+// --- page asks (task 1004317 / TW06, copy_desk_002) -----------------------
+// A page ask's surface IS its page id, so these use SURF as the page id and the
+// cleanup above still catches every row.
+console.log('copy_desk_flags — page asks (copy_desk_002)');
+
+const pageIns = (o = {}) => pool.query(
+  `INSERT INTO copy_desk_flags (scope, surface, string_id, page_id, reason, flagged_by)
+   VALUES ($1,$2,$3,$4,$5,$6) RETURNING *`,
+  [o.scope ?? 'page', o.surface ?? SURF, o.string_id ?? null, 'page_id' in o ? o.page_id : SURF, REASON, o.by ?? B]
+);
+
+await test('a page ask inserts through the real write, pointing at its page', async () => {
+  const norm = flagsLib.normalizePageAsk({ reason: REASON }, SURF);
+  const row = await flagsLib.insertFlag(norm.value, B);
+  assert.deepEqual([row.scope, row.page_id, row.surface, row.status], ['page', SURF, SURF, 'open']);
+  assert.equal((await flagsLib.findOpenPageAsk(SURF, B)).id, row.id);
+  assert.equal(await flagsLib.countPageAskers(SURF), 1);
+});
+
+await test('the same builder cannot hold two open asks on one page (the 001 index)', async () => {
+  await assert.rejects(() => pageIns(), (e) => e.code === '23505');
+});
+
+await test("scope 'page' needs a page_id, and only scope 'page' may carry one", async () => {
+  await assert.rejects(() => pageIns({ page_id: null, by: A }), (e) => e.code === '23514');
+  await assert.rejects(() => pageIns({ scope: 'string', string_id: 'pg1', by: A }), (e) => e.code === '23514');
+});
+
+await test("a page ask's surface must be its page id", async () => {
+  await assert.rejects(() => pageIns({ page_id: 'landing:index', by: A }), (e) => e.code === '23514');
+});
+
+await test('resolvePageAsks closes the open asks filed before the ship, stamped with the task', async () => {
+  const ids = await flagsLib.resolvePageAsks({ pageId: SURF, taskId: T, resolvedBy: A, shippedAt: new Date(Date.now() + 60000).toISOString() });
+  assert.equal(ids.length, 1);
+  const { rows } = await pool.query("SELECT status, resolved_task_id, resolved_by FROM copy_desk_flags WHERE scope = 'page' AND page_id = $1", [SURF]);
+  assert.deepEqual(rows.map((r) => [r.status, String(r.resolved_task_id), String(r.resolved_by)]), [['resolved', String(T), String(A)]]);
+  assert.equal(await flagsLib.countPageAskers(SURF), 0);
+});
+
+// The recommendation's read (task 1004318 / TW07): one grouped row per page
+// with an open ask, distinct askers and the oldest open ask.
+await test('pageAskSummary groups open asks by page: distinct askers, the oldest ask', async () => {
+  assert.equal((await flagsLib.pageAskSummary()).some((r) => r.page_id === SURF), false, 'resolved asks are not counted');
+  const first = (await pageIns({ by: B })).rows[0];
+  await pool.query("UPDATE copy_desk_flags SET flagged_at = now() - interval '2 days' WHERE id = $1", [first.id]);
+  await pageIns({ by: A });
+  const row = (await flagsLib.pageAskSummary()).find((r) => r.page_id === SURF);
+  assert.equal(row.askers, 2);
+  assert.equal(new Date(row.oldest_ask_at).getTime(), new Date((await pool.query('SELECT flagged_at FROM copy_desk_flags WHERE id = $1', [first.id])).rows[0].flagged_at).getTime());
+});
+
 // --- cleanup --------------------------------------------------------------
 await clean();
 await pool.query('DELETE FROM builders WHERE id = ANY($1)', [[A, B]]).catch(() => {});