@bongos/core 1.19.1057 → 1.19.1059

package/modules/copy-desk/pages.js

@@ -0,0 +1,238 @@
+// modules/copy-desk/pages.js — the PAGE TWEAK task format (ADR 0341 D2, D4).
+//
+// A page tweak is an ordinary GDS task (source 'page-tweak', ref
+// 'page-tweak/<page_id>/r<n>'), and the words rest in its DESCRIPTION, never in a
+// table (ADR 0233 §2, amended by ADR 0341 D4). The description carries up to four
+// fenced blocks, and this file is each block's ONE writer and ONE reader, tested
+// against each other:
+//
+//   ```page-tweak-draft      the draft, while the artist writes (TW08 writes it)
+//   ```page-tweak            the batch, frozen at submit (TW08)
+//   ```page-tweak-applied    what the applying session landed (TW11); its
+//                            lines_after is the baseline drift is measured from
+//   ```page-tweak-sent-back  one per send-back, appended, never replaced (TW12)
+//
+// TW05 (task 1004316) is the first reader, so it lands the format whole: the
+// status, changelog and drift reads parse all four, and the later links write
+// through the composers here rather than hand-building a fence.
+//
+// PURE, like proposals.js and for the same reason: this file handles an artist's
+// replacement wording, so it is the file most able to become a copy source by
+// accident. No require, no fs, no DB, no network. copy_no_cms.mjs pins that.
+
+'use strict';
+
+const SCHEMA = 1;
+const SOURCE = 'page-tweak';
+
+const FENCES = Object.freeze({
+  draft: 'page-tweak-draft',
+  batch: 'page-tweak',
+  applied: 'page-tweak-applied',
+  sentBack: 'page-tweak-sent-back',
+});
+
+// The page id shape the inventory's generator enforces: <surface>:<page>, both
+// halves lowercase [a-z0-9-] (docs/page-inventory.json id_rule).
+const PAGE_ID_RE = /^[a-z0-9-]+:[a-z0-9-]+$/;
+
+function fail(code, detail) { return { ok: false, code, detail: detail || {} }; }
+
+// ---------------------------------------------------------------------------
+// The round's identity (ADR 0341 D2).
+// ---------------------------------------------------------------------------
+
+function roundSourceRef(pageId, n) {
+  return `${SOURCE}/${pageId}/r${n}`;
+}
+
+// 'page-tweak/landing:index/r2' -> { page_id: 'landing:index', round: 2 }, or null.
+function parseRoundRef(sourceRef) {
+  const m = /^page-tweak\/([a-z0-9-]+:[a-z0-9-]+)\/r([1-9][0-9]*)$/.exec(String(sourceRef || ''));
+  return m ? { page_id: m[1], round: Number(m[2]) } : null;
+}
+
+// The round's task, as the claim route creates it (ADR 0341 D2; task 1004317 /
+// TW06). The title is `Tweak: <inventory title> (<page_id>)`. The body says what
+// the round is and where its words will rest; it carries NO wording and no block
+// yet, since the draft block is written by the autosave (TW08), never here.
+const ROUND_CREDITS = 30;
+
+function roundTaskTitle(page) {
+  const title = String((page && page.title) || (page && page.id) || '').trim();
+  return `Tweak: ${title} (${page.id})`;
+}
+
+function roundTaskBody(page, round) {
+  return [
+    `Page tweak round ${round} for **${String(page.title || page.id)}** (\`${page.id}\`${page.path ? `, ${page.path}` : ''}).`,
+    '',
+    'An artist rewrites every line of this page as one document in the studio. The draft rests in this description as a fenced `page-tweak-draft` block while they write, and is frozen into a `page-tweak` block when they submit. A session running `/tweak` then applies the batch, and the artist approves the rendered page before it ships (ADR 0341).',
+    '',
+    'This task was opened by the page claim (`POST /copy-desk/pages/:pageId/claim`). It is web-claimed by the artist while they write: there is no worktree until an applier claims it.',
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Fences. A block is ```<fence>\n<json>\n```, and the fence name must be followed
+// by the end of its line: 'page-tweak' is a prefix of 'page-tweak-draft', so a
+// looser match would read a draft as a batch.
+// ---------------------------------------------------------------------------
+
+function fenceBlock(fence, value) {
+  return ['```' + fence, JSON.stringify(value, null, 2), '```'].join('\n');
+}
+
+function findBlocks(markdown, fence) {
+  const re = new RegExp('```' + fence.replace(/-/g, '\\-') + '[ \\t]*\\r?\\n([\\s\\S]*?)\\r?\\n```', 'g');
+  return [...String(markdown || '').matchAll(re)].map((m) => m[1]);
+}
+
+// Parse the ONE block a description may carry for a single-writer fence. A second
+// block is a named refusal, never a coin flip (the proposals.js rule).
+function parseSingle(markdown, fence) {
+  const found = findBlocks(markdown, fence);
+  if (!found.length) return fail('no_block', { fence });
+  if (found.length > 1) return fail('multiple_blocks', { fence, count: found.length });
+  let value;
+  try { value = JSON.parse(found[0]); } catch (err) { return fail('block_unreadable', { fence, reason: err.message }); }
+  if (!value || Number(value.schema) !== SCHEMA) return fail('block_schema_unknown', { fence, expected: SCHEMA, got: value && value.schema });
+  return { ok: true, value };
+}
+
+function linesOk(lines) {
+  return Array.isArray(lines) && lines.every((l) => l && typeof l.key === 'string'
+    && typeof l.before === 'string' && typeof l.after === 'string');
+}
+
+// ---------------------------------------------------------------------------
+// The four blocks.
+// ---------------------------------------------------------------------------
+
+function composeDraftBlock(d) {
+  return fenceBlock(FENCES.draft, {
+    schema: SCHEMA,
+    page_id: d.page_id,
+    reading_hash: d.reading_hash,
+    saved_at: d.saved_at,
+    lines: (d.lines || []).map((l) => ({ key: l.key, section: l.section, before: l.before, after: l.after, placement: l.placement })),
+  });
+}
+
+function parseDraftBlock(markdown) {
+  const r = parseSingle(markdown, FENCES.draft);
+  if (!r.ok) return r;
+  if (!PAGE_ID_RE.test(String(r.value.page_id || ''))) return fail('block_field_missing', { fence: FENCES.draft, field: 'page_id' });
+  if (!linesOk(r.value.lines)) return fail('block_field_missing', { fence: FENCES.draft, field: 'lines' });
+  return { ok: true, draft: r.value };
+}
+
+// The batch. `kind` is reserved for visual tweaks (ADR 0341 D8: the UI count
+// reads batches whose kind is 'ui'); it is written only when given, so a text
+// batch today carries no such field and reads as text.
+function composeBatchBlock(b) {
+  const out = {
+    schema: SCHEMA,
+    page_id: b.page_id,
+    reading_hash: b.reading_hash,
+    submitted_at: b.submitted_at,
+  };
+  if (b.kind) out.kind = b.kind;
+  out.lines = (b.lines || []).map((l) => ({
+    key: l.key, section: l.section, before: l.before, after: l.after, placement: l.placement,
+    file: l.file == null ? null : l.file, line: l.line == null ? null : l.line, string_id: l.string_id == null ? null : l.string_id,
+  }));
+  out.unplaced_tasks = Array.isArray(b.unplaced_tasks) ? b.unplaced_tasks : [];
+  return fenceBlock(FENCES.batch, out);
+}
+
+function parseBatchBlock(markdown) {
+  const r = parseSingle(markdown, FENCES.batch);
+  if (!r.ok) return r;
+  if (!PAGE_ID_RE.test(String(r.value.page_id || ''))) return fail('block_field_missing', { fence: FENCES.batch, field: 'page_id' });
+  if (!linesOk(r.value.lines)) return fail('block_field_missing', { fence: FENCES.batch, field: 'lines' });
+  return { ok: true, batch: r.value };
+}
+
+function composeAppliedBlock(a) {
+  return fenceBlock(FENCES.applied, {
+    schema: SCHEMA,
+    page_id: a.page_id,
+    applied_at: a.applied_at,
+    reading_hash_after: a.reading_hash_after,
+    lines_after: (a.lines_after || []).map(String),
+    refused: (a.refused || []).map((x) => ({ key: x.key, code: x.code })),
+  });
+}
+
+function parseAppliedBlock(markdown) {
+  const r = parseSingle(markdown, FENCES.applied);
+  if (!r.ok) return r;
+  const lines = r.value.lines_after;
+  if (!Array.isArray(lines) || !lines.every((t) => typeof t === 'string')) {
+    return fail('block_field_missing', { fence: FENCES.applied, field: 'lines_after' });
+  }
+  return { ok: true, applied: r.value };
+}
+
+// Send-backs APPEND, so this block has no schema of its own and many may exist.
+function composeSentBackBlock(s) {
+  return fenceBlock(FENCES.sentBack, { at: s.at, by: s.by, note: s.note });
+}
+
+function parseSentBackBlocks(markdown) {
+  const out = [];
+  for (const raw of findBlocks(markdown, FENCES.sentBack)) {
+    try {
+      const v = JSON.parse(raw);
+      if (v && typeof v.at === 'string') out.push({ at: v.at, by: v.by == null ? null : v.by, note: String(v.note || '') });
+    } catch { /* an unreadable send-back is skipped; the rest still count */ }
+  }
+  return out;
+}
+
+// Which blocks a description carries, without failing on any one of them. The
+// round-state derivation (ADR 0341 D7) reads presence and times, not contents.
+function blockPresence(markdown) {
+  const sent = parseSentBackBlocks(markdown);
+  const applied = parseAppliedBlock(markdown);
+  return {
+    draft: findBlocks(markdown, FENCES.draft).length > 0,
+    batch: findBlocks(markdown, FENCES.batch).length > 0,
+    applied: findBlocks(markdown, FENCES.applied).length > 0,
+    applied_at: applied.ok ? (applied.applied.applied_at || null) : null,
+    sent_back_count: sent.length,
+    last_sent_back_at: sent.length ? sent.map((s) => s.at).sort().pop() : null,
+  };
+}
+
+// May an artist's claim take over an UNHELD open round (ADR 0341 D5)? Only one
+// still being written: `ready`, with no frozen batch. That is the `draft` state
+// (released without submitting; the draft stays) and a round released before
+// any draft was saved. A round with a batch is `submitted`: it belongs to the
+// /tweak queue, and a writing claim would pull it back out of it.
+function roundOpenForWriting(task) {
+  return !!task && task.status === 'ready' && !blockPresence(task.description).batch;
+}
+
+module.exports = {
+  SCHEMA,
+  SOURCE,
+  FENCES,
+  PAGE_ID_RE,
+  ROUND_CREDITS,
+  roundTaskTitle,
+  roundTaskBody,
+  roundSourceRef,
+  parseRoundRef,
+  composeDraftBlock,
+  parseDraftBlock,
+  composeBatchBlock,
+  parseBatchBlock,
+  composeAppliedBlock,
+  parseAppliedBlock,
+  composeSentBackBlock,
+  parseSentBackBlocks,
+  blockPresence,
+  roundOpenForWriting,
+};

package/modules/copy-desk/routes/copy-desk.js

@@ -10,6 +10,11 @@
 //   POST /copy-desk/proposals        — propose new wording. Creates a TASK carrying
 //                                 the patch; writes no file and stores no copy.
 //
+// Tweak Mode (ADR 0341) adds the page reads (TW05) and two page writes (TW06,
+// task 1004317): POST /copy-desk/pages/:pageId/claim opens or takes a page's
+// tweak round as a TASK with a web claim, and POST /copy-desk/pages/:pageId/asks
+// files a page ask, a flag row whose target is a page id. Neither stores copy.
+//
 // THE RANK SHAPE, AND WHY IT IS ASYMMETRIC:
 //
 //   FILING is open to every rank, deliberately. "Sourced by everyone else" is the
@@ -31,7 +36,7 @@
 // produce a TASK carrying a patch, never a write. A flag is a work request; a
 // proposal is a work request with a suggested fix attached. Neither reaches a
 // reader. modules/copy-desk/tests/copy_no_cms.mjs pins that by asserting this
-// router's write surface stays exactly these three verbs, that none of them
+// router's write surface stays exactly the listed verbs, that none of them
 // touches the filesystem, and that the one place a proposed wording is allowed
 // to rest is the GDS ledger.
 //
@@ -45,6 +50,9 @@ const api = require('../../../src/module-api');
 const flags = require('../flags');
 const registry = require('../registry');
 const proposals = require('../proposals');
+const pageData = require('../page-data');
+const pageStatus = require('../page-status');
+const pages = require('../pages');
 
 const { validateOrRespond } = api;
 
@@ -63,7 +71,7 @@ const log = api.logger('copy-desk');
 // lookups, the scope/string_id coupling — live in flags.normalize*, so the DB
 // constraint, the pure validator and this schema each say one thing once.
 const FLAG_BODY_SCHEMA = Object.freeze({
-  scope:       { type: 'string', enum: [...flags.SCOPES] },
+  scope:       { type: 'string', enum: [...flags.FLAG_SCOPES] },
   surface:     { required: true, type: 'string', maxLength: 128, minLength: 1 },
   string_id:   { type: 'string', maxLength: 64 },
   reason:      { required: true, type: 'string', maxLength: flags.MAX_REASON_CHARS, minLength: 1 },
@@ -87,6 +95,14 @@ const PROPOSAL_BODY_SCHEMA = Object.freeze({
   line:          { type: 'integer', min: 1 },
   flag_id:       { type: 'integer', min: 1 },
 });
+// The page claim (task 1004317 / TW06) takes nothing: who claims is the
+// session and what is claimed is the path. Strict, so a caller cannot smuggle
+// a builder, a version or a round in.
+const CLAIM_BODY_SCHEMA = Object.freeze({});
+// The page ask: a reason and nothing else. The target is the path's page id.
+const ASK_BODY_SCHEMA = Object.freeze({
+  reason: { required: true, type: 'string', maxLength: flags.MAX_REASON_CHARS, minLength: 1 },
+});
 
 // Load the registry or answer the named "no registry" state. Returns null when
 // it has already responded, so every handler is `if (!reg) return;`.
@@ -106,9 +122,120 @@ function registryOrFail(res) {
   return loaded;
 }
 
+// ---------------------------------------------------------------------------
+// Tweak Mode's reads (task 1004316 / BV2.TW05, ADR 0341 D8 and D11).
+//
+// The page inventory is REQUIRED: without it there is no page to speak of, so
+// its absence is a named 503 carrying the generator command, the registry's own
+// rule. The page readings are OPTIONAL: status, count and changelog come from
+// the ledger and read true without them, so a missing readings file only marks
+// drift unknown (`readings_missing`). Both files ship in the publish manifest
+// (ADR 0341 D1); these branches are for an instance on an older core or a
+// checkout that has not run the generators.
+// ---------------------------------------------------------------------------
+
+function inventoryOrFail(res) {
+  const loaded = pageData.loadInventory();
+  if (!loaded.ok) {
+    res.fail(loaded.code, 503, {
+      ...loaded.detail,
+      what_this_means: 'Tweak Mode keys every record on a page from the committed page inventory. Without it there is no list of pages to report on.',
+    });
+    return null;
+  }
+  return loaded;
+}
+
+function readingsState() {
+  const loaded = pageData.loadReadings();
+  return loaded.ok
+    ? { data: loaded.data, info: { ok: true, at: loaded.at } }
+    : { data: null, info: { ok: false, code: loaded.code, run: loaded.detail.run } };
+}
+
+// Resolve :pageId against the inventory, or answer `unknown_page` (ADR 0341
+// D1). Returns null when it has already responded.
+function pageOrFail(req, res) {
+  const pageId = String(req.params.pageId || '');
+  if (!pages.PAGE_ID_RE.test(pageId)) {
+    res.fail('unknown_page', 404, { page_id: pageId, what_this_means: 'A page id is <surface>:<page>, for example landing:index.' });
+    return null;
+  }
+  const inv = inventoryOrFail(res);
+  if (!inv) return null;
+  const page = (inv.data.pages || []).find((p) => p && p.id === pageId);
+  if (!page) {
+    res.fail('unknown_page', 404, { page_id: pageId, what_this_means: 'The page inventory has no page with that id.' });
+    return null;
+  }
+  return { page, pageId, inv };
+}
+
+// An open page ask is RESOLVED when the page's next tweak ships (ADR 0341 D6).
+// Runs on the kernel's task.shipped event, after the ship has committed, so it
+// can never fail the ship: every error is logged and swallowed. The event
+// payload carries no source, so the task is read back through the port.
+async function resolveAsksOnShip(shipped, deps = {}) {
+  try {
+    const lifecycle = deps.lifecycle || (api.resolveOptional && api.resolveOptional('lifecycle'));
+    const flagsLib = deps.flags || flags;
+    if (!shipped || shipped.id == null || !lifecycle || typeof lifecycle.getTask !== 'function') return [];
+    const task = await lifecycle.getTask(shipped.id);
+    if (!task || task.source !== pages.SOURCE || task.status !== 'shipped') return [];
+    const ref = pages.parseRoundRef(task.source_ref);
+    if (!ref) return [];
+    const resolvedBy = task.shipped_by != null ? task.shipped_by : shipped.shipped_by;
+    // copy_desk_flags_closed_chk: a closed flag names who closed it. With no
+    // shipper on record the asks stay open rather than be closed by nobody.
+    if (resolvedBy == null) return [];
+    return await flagsLib.resolvePageAsks({
+      pageId: ref.page_id, taskId: task.id, resolvedBy, shippedAt: task.shipped_at || new Date().toISOString(),
+    });
+  } catch (err) {
+    log.warn({ err, task_id: shipped && shipped.id }, 'resolving page asks on ship failed (non-blocking)');
+    return [];
+  }
+}
+let _askListenerOff = null;
+
+// The ledger reads come through the lifecycle port. copy-desk consumes
+// lifecycle, so the port is always there on a booted instance; the check is for
+// a core whose lifecycle predates these reads.
+function pageReadsOrFail(res) {
+  const lifecycle = api.resolveOptional && api.resolveOptional('lifecycle');
+  if (!lifecycle || typeof lifecycle.listPageTweakTasks !== 'function') {
+    res.fail('lifecycle_unavailable', 503, {
+      what_this_means: 'Page status is derived from the task ledger, and this instance cannot read it.',
+    });
+    return null;
+  }
+  return lifecycle;
+}
+
+// Every `tweak.page_approved:` credit row the caller has, through the reward
+// port (credit_log is economy's table). No reward port, or no rows yet (TW13
+// has not built the payout), reads as none: a tally of 0 is the truth then.
+//
+// ONE bounded query. An approved page books one row, so the cap is thousands of
+// pages for one artist; past it the tally says `truncated` (creditLedger's
+// `total` is the unpaginated count) rather than paging in a loop.
+const TALLY_ROW_CAP = 5000;
+async function tallyCreditRows(builderId) {
+  const reward = api.resolveOptional && api.resolveOptional('reward');
+  if (!reward || typeof reward.creditLedger !== 'function') return { rows: [], truncated: false };
+  const { rows, total } = await reward.creditLedger(builderId, { reasonPrefix: pageStatus.TALLY_REASON_PREFIX, limit: TALLY_ROW_CAP });
+  const list = rows || [];
+  return { rows: list, truncated: Number(total) > list.length };
+}
+
 module.exports = function buildCopyDeskRouter() {
   const router = express.Router();
 
+  // Page asks resolve when the page's tweak ships (ADR 0341 D6). Re-registered
+  // on every router build (tests rebuild it), never stacked.
+  if (_askListenerOff) _askListenerOff();
+  _askListenerOff = api.on('task.shipped', (task) => resolveAsksOnShip(task));
+
   // -------------------------------------------------------------------------
   // GET /copy-desk/queue — the artist's working list.
   //
@@ -139,8 +266,11 @@ module.exports = function buildCopyDeskRouter() {
       // re-surfaces every already-dismissed duplicate as untouched work.
       // composeQueue owns that rule; this just feeds it both sets. When the
       // caller asked for everything the two are the same query, so it runs once.
-      const shown = await flags.listFlags({ status, surface });
-      const allFlags = status === 'all' ? shown : await flags.listFlags({ status: 'all', surface });
+      // Page asks (scope 'page', task 1004317) are the recommendation's signal,
+      // not rows in this string queue, so the queue reads the two flag scopes.
+      const scopes = flags.FLAG_SCOPES;
+      const shown = await flags.listFlags({ status, surface, scopes });
+      const allFlags = status === 'all' ? shown : await flags.listFlags({ status: 'all', surface, scopes });
 
       const queue = registry.composeQueue({
         registry: loaded.registry,
@@ -449,5 +579,228 @@ module.exports = function buildCopyDeskRouter() {
     }
   });
 
+  // -------------------------------------------------------------------------
+  // GET /copy-desk/pages — every page's status, count and drift, plus the
+  // per-surface rollup, Artist Review Status ("N of M tweaked").
+  //
+  // rank: any signed-in builder. Page status is a work list, like the queue;
+  // an artist is a craft, not a rank.
+  // -------------------------------------------------------------------------
+  router.get('/copy-desk/pages', api.requireBuilder, async (req, res) => {
+    try {
+      const inv = inventoryOrFail(res);
+      if (!inv) return;
+      const lifecycle = pageReadsOrFail(res);
+      if (!lifecycle) return;
+      const readings = readingsState();
+      const tasks = await lifecycle.listPageTweakTasks();
+      const out = pageStatus.composePages({ inventory: inv.data, readings: readings.data, tasks });
+      out.inventory = { at: inv.at };
+      out.readings = readings.info;
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) {
+      log.error({ err }, 'GET /copy-desk/pages failed');
+      if (!res.headersSent) res.fail('copy_pages_failed', 500);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // GET /copy-desk/pages/:pageId — one page: status, changelog, the lines
+  // changed since its last tweak and the ships that changed them, and the open
+  // round with its state (ADR 0341 D7).
+  //
+  // An id the inventory does not know is `unknown_page` (ADR 0341 D1).
+  // -------------------------------------------------------------------------
+  router.get('/copy-desk/pages/:pageId', api.requireBuilder, async (req, res) => {
+    try {
+      const found = pageOrFail(req, res);
+      if (!found) return;
+      const { page, pageId } = found;
+      const lifecycle = pageReadsOrFail(res);
+      if (!lifecycle) return;
+      const readings = readingsState();
+      const readingPage = readings.data ? (readings.data.pages || []).find((p) => p && p.id === pageId) : null;
+      const tasks = await lifecycle.listPageTweakTasks();
+      // The ships since the page's last round are read first, so the page is
+      // composed once with everything it shows.
+      const since = pageStatus.lastRoundShippedAt(tasks, pageId);
+      const ships = since && typeof lifecycle.shippedTasksTouchingSince === 'function'
+        ? await lifecycle.shippedTasksTouchingSince({ files: page.files, since })
+        : [];
+      const out = pageStatus.composePage({ page, tasks, readingPage, readingsOk: !!readings.data, ships });
+      out.readings = readings.info;
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) {
+      log.error({ err }, 'GET /copy-desk/pages/:pageId failed');
+      if (!res.headersSent) res.fail('copy_page_failed', 500);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // GET /copy-desk/tally — the caller's corner tally in the studio: credits
+  // from approved pages, pages tweaked, and this week's gain (trailing 7 days).
+  //
+  // Always the CALLER's own tally; there is no builder parameter to widen it.
+  // Needs no inventory: it reads the ledger only.
+  // -------------------------------------------------------------------------
+  router.get('/copy-desk/tally', api.requireBuilder, async (req, res) => {
+    try {
+      const lifecycle = pageReadsOrFail(res);
+      if (!lifecycle) return;
+      const [tasks, credit] = await Promise.all([
+        lifecycle.listPageTweakTasks(),
+        tallyCreditRows(req.builder.id),
+      ]);
+      const out = pageStatus.composeTally({ builderId: req.builder.id, tasks, creditRows: credit.rows, now: new Date() });
+      out.truncated = credit.truncated;
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) {
+      log.error({ err }, 'GET /copy-desk/tally failed');
+      if (!res.headersSent) res.fail('copy_tally_failed', 500);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // POST /copy-desk/pages/:pageId/claim — claim a page's tweak (task 1004317 /
+  // BV2.TW06, ADR 0341 D2 and D5). Also Resume and "Take next".
+  //
+  // Body: {} (nothing — who claims is the session, what is claimed is the path).
+  // rank: any signed-in builder; the gate is the CRAFT, read server-side
+  //       (builders.preferred_disciplines includes artist), never the request.
+  //
+  // One call finds the page's open round or creates it (source_ref
+  // page-tweak/<page_id>/r<n>, 30 credits, the building version's catch-all
+  // goal) and WEB-claims it: no worktree, no session. The lifecycle port runs it
+  // in one transaction under an advisory lock on the page, so two artists cannot
+  // both open a round.
+  //
+  //   201 created   a new round, held by the caller
+  //   200 claimed   an unheld round still being written (a draft released
+  //                 without submitting) taken over; the draft stays
+  //   200 resumed   the caller already holds it
+  //   409 page_held       another builder holds it; the holder is named
+  //   409 page_in_flight  the round is past writing (submitted, applying,
+  //                       waiting for the artist, landing)
+  //   403 not_an_artist   the caller's crafts do not include artist; they are
+  //                       offered the ask
+  // -------------------------------------------------------------------------
+  router.post('/copy-desk/pages/:pageId/claim', api.requireBuilder, async (req, res) => {
+    try {
+      if (validateOrRespond(req, res, CLAIM_BODY_SCHEMA)) return;
+      const found = pageOrFail(req, res);
+      if (!found) return;
+      const { page, pageId } = found;
+      const lifecycle = api.resolveOptional && api.resolveOptional('lifecycle');
+      if (!lifecycle || typeof lifecycle.webClaimPageTweak !== 'function') {
+        return res.fail('lifecycle_unavailable', 503, {
+          what_this_means: 'A page claim opens a task in the ledger, and this instance cannot. Nothing was recorded.',
+        });
+      }
+      // Where a NEW round lands: the version being built, as a copy proposal
+      // lands (no fallback to another version; see resolveTargetVersion).
+      const building = proposals.resolveTargetVersion(await lifecycle.listVersions());
+      const r = await lifecycle.webClaimPageTweak({
+        pageId,
+        builderId: req.builder.id,
+        versionId: building ? building.id : null,
+        round: {
+          title: () => pages.roundTaskTitle(page),
+          description: (n) => pages.roundTaskBody(page, n),
+          sourceRef: (n) => pages.roundSourceRef(pageId, n),
+          touches: Array.isArray(page.files) ? page.files : [],
+          creditsReward: pages.ROUND_CREDITS,
+          canTakeOver: pages.roundOpenForWriting,
+        },
+      });
+      const round = r.task ? { task_id: String(r.task.id), round: r.round, source_ref: r.task.source_ref, status: r.task.status } : null;
+      switch (r.outcome) {
+        case 'created':
+        case 'claimed':
+        case 'resumed':
+          return res.status(r.outcome === 'created' ? 201 : 200).json({
+            ok: true, outcome: r.outcome, page_id: pageId, round: { ...round, state: 'writing' },
+            claim: r.claim ? { id: String(r.claim.id), claimed_at: r.claim.claimed_at } : null,
+          });
+        case 'held':
+          return res.fail('page_held', 409, {
+            page_id: pageId, round, holder: r.holder,
+            what_this_means: r.holder_is_writing
+              ? `${r.holder.name || r.holder.login || 'Another artist'} is writing this page now. Ask for it instead, or take another.`
+              : `${r.holder.name || r.holder.login || 'Another builder'} is applying this page's submitted words. It comes back when it ships or is sent back.`,
+          });
+        case 'in_flight':
+          return res.fail('page_in_flight', 409, {
+            page_id: pageId, round,
+            what_this_means: 'This page\'s round has been submitted and is on its way to the site. It can be claimed again once it ships or is sent back.',
+          });
+        case 'not_an_artist':
+          return res.fail('not_an_artist', 403, {
+            page_id: pageId,
+            what_this_means: 'Only a builder whose crafts include artist can claim a page. Anyone can ask for one.',
+            your_options: [`POST /copy-desk/pages/${pageId}/asks with a one-line reason`, 'Add artist to your crafts in Settings'],
+          });
+        case 'builder_inactive':
+          return res.fail('builder_inactive', 403);
+        case 'no_open_version':
+          return res.fail('no_open_version', 503, {
+            what_this_means: 'No version is currently being built, so there is nowhere for a new page round to land. Nothing was recorded.',
+          });
+        default:
+          throw new Error(`webClaimPageTweak: unknown outcome ${r.outcome}`);
+      }
+    } catch (err) {
+      log.error({ err }, 'POST /copy-desk/pages/:pageId/claim failed');
+      if (!res.headersSent) res.fail('copy_page_claim_failed', 500);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // POST /copy-desk/pages/:pageId/asks — ask for a page (task 1004317 / TW06,
+  // ADR 0341 D6).
+  //
+  // Body: { reason } — one line, the flag's own floor (10 characters).
+  // rank: any signed-in builder, any craft. A page ask is a copy_desk_flags row
+  //       with scope 'page'; it carries a judgement and a page id, never text.
+  //
+  //   201 a new ask · 200 the caller's open ask on this page already (the first
+  //   one comes back; a double ask is not a second signal)
+  // Both carry `askers`: distinct builders with an open ask on the page.
+  // -------------------------------------------------------------------------
+  router.post('/copy-desk/pages/:pageId/asks', api.requireBuilder, async (req, res) => {
+    try {
+      if (validateOrRespond(req, res, ASK_BODY_SCHEMA)) return;
+      const found = pageOrFail(req, res);
+      if (!found) return;
+      const { pageId } = found;
+      const norm = flags.normalizePageAsk(req.body, pageId);
+      if (!norm.ok) return res.fail(norm.code, 400, norm.detail);
+
+      let ask = await flags.findOpenPageAsk(pageId, req.builder.id);
+      let created = false;
+      if (!ask) {
+        try {
+          ask = await flags.insertFlag(norm.value, req.builder.id);
+          created = true;
+        } catch (err) {
+          // 23505: a concurrent ask by the same builder won the one-open-per-
+          // (builder, page) index. Same answer as the read above.
+          if (!(err && err.code === '23505')) throw err;
+          ask = await flags.findOpenPageAsk(pageId, req.builder.id);
+          if (!ask) throw err;
+        }
+      }
+      const askers = await flags.countPageAskers(pageId);
+      res.status(created ? 201 : 200).json({ ok: true, created, ask, page_id: pageId, askers });
+    } catch (err) {
+      log.error({ err }, 'POST /copy-desk/pages/:pageId/asks failed');
+      if (!res.headersSent) res.fail('copy_page_ask_failed', 500);
+    }
+  });
+
   return router;
 };
+
+module.exports.resolveAsksOnShip = resolveAsksOnShip;