@bongos/core 1.19.1058 → 1.19.1059

package/modules/copy-desk/flags.js

@@ -28,7 +28,12 @@ const { pool } = require('../../src/module-api');
 // Mirrors of the DB CHECK constraints — enforced here first so a bad payload
 // gets a clean, named 400 instead of a raw constraint violation surfacing as a
 // 500. The DB stays the backstop; this is the error message.
-const SCOPES = Object.freeze(['string', 'surface']);
+// SCOPES mirrors the DB CHECK (widened by copy_desk_002_page_asks.sql). A
+// 'page' row is a PAGE ASK (ADR 0341 D6) and is filed only through
+// POST /copy-desk/pages/:pageId/asks, so the flag route takes FLAG_SCOPES.
+const SCOPES = Object.freeze(['string', 'surface', 'page']);
+const FLAG_SCOPES = Object.freeze(['string', 'surface']);
+const PAGE_SCOPE = 'page';
 const STATUSES = Object.freeze(['open', 'resolved', 'dismissed']);
 const KINDS = Object.freeze(['slop', 'off-voice', 'stale', 'unclear', 'duplicate', 'typo', 'other']);
 // The closing verdicts a person can apply to an open flag. 'open' is not among
@@ -65,7 +70,11 @@ function normalizeFlagPayload(body, registryIndex, registryHelpers) {
   const b = body || {};
 
   const scope = String(b.scope || 'string');
-  if (!SCOPES.includes(scope)) return fail('bad_scope', { allowed: SCOPES });
+  if (!FLAG_SCOPES.includes(scope)) {
+    return fail('bad_scope', scope === PAGE_SCOPE
+      ? { allowed: FLAG_SCOPES, why: 'A page is asked for at POST /copy-desk/pages/:pageId/asks.' }
+      : { allowed: FLAG_SCOPES });
+  }
 
   const surface = String(b.surface || '');
   if (!surface) return fail('surface_required');
@@ -155,6 +164,31 @@ function normalizeResolution(body) {
   return { ok: true, value: { status, resolution_note: note, resolved_task_id: taskId } };
 }
 
+// Validate a PAGE ASK (task 1004317 / TW06, ADR 0341 D6). PURE. The page id is
+// the route's, already checked against the inventory; the body carries only the
+// reason, held to the flag's own floor. `surface` carries the page id too: that
+// is what makes 001's one-open-flag-per-target index mean one open ask per
+// (builder, page) — see copy_desk_002_page_asks.sql.
+function normalizePageAsk(body, pageId) {
+  const b = body || {};
+  const reason = tidy(b.reason);
+  if (reason.length < MIN_REASON_CHARS) {
+    return fail('reason_too_thin', {
+      min_chars: MIN_REASON_CHARS,
+      got: reason.length,
+      why: 'An ask tells an artist why this page, before the others. One line is enough; a word is not.',
+    });
+  }
+  if (reason.length > MAX_REASON_CHARS) return fail('reason_too_long', { max_chars: MAX_REASON_CHARS });
+  return {
+    ok: true,
+    value: {
+      scope: PAGE_SCOPE, surface: pageId, page_id: pageId, string_id: null, reason, kind: 'other',
+      text_at_flag: null, file_at_flag: null, line_at_flag: null, registry_schema: null,
+    },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // SQL. Thin by design — the rules live above and in the migration's constraints.
 // ---------------------------------------------------------------------------
@@ -165,7 +199,7 @@ function normalizeResolution(body) {
 // shape, which is what lets the hall render an insert response and a queue row
 // with one function.
 const FLAG_COL_NAMES = Object.freeze([
-  'id', 'scope', 'surface', 'string_id', 'reason', 'kind',
+  'id', 'scope', 'surface', 'string_id', 'page_id', 'reason', 'kind',
   'text_at_flag', 'file_at_flag', 'line_at_flag', 'registry_schema',
   'flagged_by', 'flagged_at', 'status', 'resolution_note',
   'resolved_task_id', 'resolved_by', 'resolved_at',
@@ -176,11 +210,11 @@ const FLAG_COLS_BARE = FLAG_COL_NAMES.join(', ');
 async function insertFlag(value, builderId) {
   const { rows } = await pool.query(
     `INSERT INTO copy_desk_flags
-       (scope, surface, string_id, reason, kind, text_at_flag, file_at_flag, line_at_flag, registry_schema, flagged_by)
-     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)
+       (scope, surface, string_id, reason, kind, text_at_flag, file_at_flag, line_at_flag, registry_schema, flagged_by, page_id)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)
      RETURNING ${FLAG_COLS_BARE}`,
     [value.scope, value.surface, value.string_id, value.reason, value.kind,
-      value.text_at_flag, value.file_at_flag, value.line_at_flag, value.registry_schema, builderId]
+      value.text_at_flag, value.file_at_flag, value.line_at_flag, value.registry_schema, builderId, value.page_id ?? null]
   );
   return rows[0];
 }
@@ -191,9 +225,12 @@ async function insertFlag(value, builderId) {
 //
 // Joined to builders for the display name: a flag is a judgement by a PERSON,
 // and an artist deciding how much weight to give it needs to know whose it is.
-async function listFlags({ status = 'open', surface = null, stringId = null, limit = 200 } = {}) {
+// `scopes` narrows by scope. The copy queue passes FLAG_SCOPES: page asks are
+// the recommendation's signal (TW07), not rows in the string queue.
+async function listFlags({ status = 'open', surface = null, stringId = null, scopes = null, limit = 200 } = {}) {
   const where = [];
   const args = [];
+  if (Array.isArray(scopes) && scopes.length) { args.push([...scopes]); where.push(`f.scope = ANY($${args.length}::text[])`); }
   if (status && status !== 'all') { args.push(status); where.push(`f.status = $${args.length}`); }
   if (surface) { args.push(surface); where.push(`f.surface = $${args.length}`); }
   if (stringId) { args.push(stringId); where.push(`f.string_id = $${args.length}`); }
@@ -238,8 +275,46 @@ async function closeFlag(id, value, builderId) {
   return rows[0] || null;
 }
 
+// The caller's OPEN ask on a page, if any: a second ask returns the first
+// (ADR 0341 D6), rather than a 409 the person has to read.
+async function findOpenPageAsk(pageId, builderId) {
+  const { rows } = await pool.query(
+    `SELECT ${FLAG_COLS} FROM copy_desk_flags f
+      WHERE f.scope = 'page' AND f.page_id = $1 AND f.flagged_by = $2 AND f.status = 'open'
+      ORDER BY f.id ASC LIMIT 1`,
+    [pageId, builderId]
+  );
+  return rows[0] || null;
+}
+
+// "N people asked for it": distinct askers among a page's OPEN asks.
+async function countPageAskers(pageId) {
+  const { rows } = await pool.query(
+    `SELECT COUNT(DISTINCT flagged_by)::int AS askers FROM copy_desk_flags
+      WHERE scope = 'page' AND page_id = $1 AND status = 'open'`,
+    [pageId]
+  );
+  return rows[0] ? Number(rows[0].askers) : 0;
+}
+
+// An open ask is RESOLVED when the page's next tweak ships (ADR 0341 D6): every
+// ask on the page filed before that ship, stamped with the tweak task. Guarded on
+// status = 'open', so a re-run changes nothing and a dismissed ask stays dismissed.
+async function resolvePageAsks({ pageId, taskId, resolvedBy, shippedAt }) {
+  const { rows } = await pool.query(
+    `UPDATE copy_desk_flags
+        SET status = 'resolved', resolved_task_id = $2, resolved_by = $3, resolved_at = now(),
+            resolution_note = $5
+      WHERE scope = 'page' AND page_id = $1 AND status = 'open' AND flagged_at <= $4::timestamptz
+      RETURNING id`,
+    [pageId, taskId, resolvedBy, shippedAt, `Resolved by the page's tweak shipping (task ${taskId}).`]
+  );
+  return rows.map((r) => r.id);
+}
+
 module.exports = {
-  SCOPES, STATUSES, KINDS, CLOSING_STATUSES, MIN_REASON_CHARS, MAX_REASON_CHARS, MAX_NOTE_CHARS,
-  tidy, normalizeFlagPayload, normalizeResolution,
+  SCOPES, FLAG_SCOPES, PAGE_SCOPE, STATUSES, KINDS, CLOSING_STATUSES, MIN_REASON_CHARS, MAX_REASON_CHARS, MAX_NOTE_CHARS,
+  tidy, normalizeFlagPayload, normalizeResolution, normalizePageAsk,
   insertFlag, listFlags, getFlag, closeFlag,
+  findOpenPageAsk, countPageAskers, resolvePageAsks,
 };

package/modules/copy-desk/migrations/copy_desk_002_page_asks.sql

@@ -0,0 +1,62 @@
+-- copy_desk_002_page_asks.sql — the PAGE ASK: anyone asks for a whole page to be
+-- tweaked, with a one-line reason (task 1004317 / BV2.TW06, ADR 0341 D6).
+--
+-- WHAT CHANGES. copy_desk_flags gains a third scope, 'page', and a nullable
+-- `page_id` naming a page of the page inventory (docs/page-inventory.json,
+-- `<surface>:<page>`). A page ask IS a flag: it keeps the flag's reason floor
+-- (copy_desk_flags_reason_chk, untouched), its open / resolved / dismissed
+-- lifecycle and its closed-stamp rule. It is resolved when the page's next tweak
+-- ships (resolved_task_id = that tweak task), never auto-dismissed.
+--
+-- THE TARGET RULE. `string_id` is present exactly for scope 'string' and
+-- `page_id` exactly for scope 'page'. Both halves of each, as in 001: a page ask
+-- with no page points nowhere, and a string flag carrying a page would be a
+-- second target nobody reads.
+--
+-- WHY `surface` HOLDS THE PAGE ID ON A PAGE ASK. The one-open-flag-per-target
+-- index from 001 keys on (flagged_by, surface, COALESCE(string_id, '')). A page
+-- ask has no string_id, so if its surface were the page's surface ('builders')
+-- one builder could ask for only ONE page per surface: the second ask would
+-- collide with the first. Storing the page id there too makes the existing index
+-- mean "one open ask per (builder, page)", which is the rule ADR 0341 D6 wants,
+-- with no index dropped (a module migration stays additive). A page id always
+-- contains a ':' and a registry surface id never does, so a page ask can never
+-- collide with a surface flag. copy_desk_flags_page_surface_chk pins the pair.
+--
+-- NO LIVE CMS still holds (ADR 0178 §3): the one new column is a POINTER, a page
+-- id. Nothing here can hold replacement text; copy_no_cms.mjs lists page_id as
+-- the only text column this migration adds.
+--
+-- ADDITIVE, per ADR 0083 §Decision #5: the two CHECKs are dropped and re-added
+-- under the SAME names in this file (the widening shape the fitness gate
+-- allows), and existing rows all satisfy the new forms (they are 'string' or
+-- 'surface' rows with page_id NULL). Idempotent: safe to re-run.
+
+BEGIN;
+
+ALTER TABLE copy_desk_flags ADD COLUMN IF NOT EXISTS page_id text;
+
+ALTER TABLE copy_desk_flags DROP CONSTRAINT IF EXISTS copy_desk_flags_scope_chk;
+ALTER TABLE copy_desk_flags
+  ADD CONSTRAINT copy_desk_flags_scope_chk CHECK (scope IN ('string', 'surface', 'page'));
+
+ALTER TABLE copy_desk_flags DROP CONSTRAINT IF EXISTS copy_desk_flags_target_chk;
+ALTER TABLE copy_desk_flags
+  ADD CONSTRAINT copy_desk_flags_target_chk CHECK (
+    ((scope = 'string') = (string_id IS NOT NULL))
+    AND ((scope = 'page') = (page_id IS NOT NULL))
+  );
+
+ALTER TABLE copy_desk_flags DROP CONSTRAINT IF EXISTS copy_desk_flags_page_surface_chk;
+ALTER TABLE copy_desk_flags
+  ADD CONSTRAINT copy_desk_flags_page_surface_chk CHECK (scope <> 'page' OR surface = page_id);
+
+-- The recommendation's read (TW07): open asks per page, counted by distinct
+-- asker, oldest first.
+CREATE INDEX IF NOT EXISTS copy_desk_flags_page_open_idx
+  ON copy_desk_flags (page_id, flagged_at) WHERE scope = 'page' AND status = 'open';
+
+INSERT INTO schema_migrations (version) VALUES ('copy_desk_002_page_asks')
+  ON CONFLICT (version) DO NOTHING;
+
+COMMIT;

package/modules/copy-desk/pages.js

@@ -52,6 +52,27 @@ function parseRoundRef(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
@@ -185,11 +206,23 @@ function blockPresence(markdown) {
   };
 }
 
+// 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,
@@ -201,4 +234,5 @@ module.exports = {
   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.
 //
@@ -66,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 },
@@ -90,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;`.
@@ -140,6 +153,51 @@ function readingsState() {
     : { 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.
@@ -173,6 +231,11 @@ async function tallyCreditRows(builderId) {
 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.
   //
@@ -203,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,
@@ -548,16 +614,9 @@ module.exports = function buildCopyDeskRouter() {
   // -------------------------------------------------------------------------
   router.get('/copy-desk/pages/:pageId', api.requireBuilder, async (req, res) => {
     try {
-      const pageId = String(req.params.pageId || '');
-      if (!pages.PAGE_ID_RE.test(pageId)) {
-        return res.fail('unknown_page', 404, { page_id: pageId, what_this_means: 'A page id is <surface>:<page>, for example landing:index.' });
-      }
-      const inv = inventoryOrFail(res);
-      if (!inv) return;
-      const page = (inv.data.pages || []).find((p) => p && p.id === pageId);
-      if (!page) {
-        return res.fail('unknown_page', 404, { page_id: pageId, what_this_means: 'The page inventory has no page with that id.' });
-      }
+      const found = pageOrFail(req, res);
+      if (!found) return;
+      const { page, pageId } = found;
       const lifecycle = pageReadsOrFail(res);
       if (!lifecycle) return;
       const readings = readingsState();
@@ -604,5 +663,144 @@ module.exports = function buildCopyDeskRouter() {
     }
   });
 
+  // -------------------------------------------------------------------------
+  // 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;

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

@@ -188,15 +188,65 @@ await test('the JS enums match the migration CHECK constraints exactly', async (
   const url = await import('node:url');
   const path = await import('node:path');
   const here = path.dirname(url.fileURLToPath(import.meta.url));
-  const sql = fs.readFileSync(path.join(here, '..', 'migrations', 'copy_desk_001_flags.sql'), 'utf8');
+  // Every migration, oldest first: a later one may widen a CHECK (TW06's
+  // copy_desk_002 widens scope), and the LAST definition is the one in force.
+  const dir = path.join(here, '..', 'migrations');
+  const sql = fs.readdirSync(dir).filter((x) => x.endsWith('.sql')).sort()
+    .map((x) => fs.readFileSync(path.join(dir, x), 'utf8')).join('\n');
   for (const [name, list] of [['kind', flags.KINDS], ['scope', flags.SCOPES], ['status', flags.STATUSES]]) {
-    const m = new RegExp(`CHECK \\(${name} IN \\(([^)]*)\\)\\)`).exec(sql);
+    const all = [...sql.matchAll(new RegExp(`CHECK \\(${name} IN \\(([^)]*)\\)\\)`, 'g'))];
+    const m = all[all.length - 1];
     assert.ok(m, `migration has no CHECK for ${name}`);
     const inSql = m[1].split(',').map((s) => s.trim().replace(/'/g, ''));
     assert.deepEqual(inSql.sort(), [...list].sort(), `${name} enum drifted between flags.js and the migration`);
   }
 });
 
+// ---------------------------------------------------------------------------
+// Page asks (task 1004317 / TW06, ADR 0341 D6).
+// ---------------------------------------------------------------------------
+
+console.log('copy-desk: page asks');
+
+await test('the flag route refuses scope page and points at the ask route', () => {
+  const r = ok({ scope: 'page', surface: 'landing', reason: GOOD_REASON });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'bad_scope');
+  assert.deepEqual([...r.detail.allowed], ['string', 'surface']);
+  assert.ok(/asks/.test(r.detail.why));
+});
+
+await test('a page ask carries the flag reason floor', () => {
+  const thin = flags.normalizePageAsk({ reason: '  do it  ' }, 'landing:index');
+  assert.equal(thin.ok, false);
+  assert.equal(thin.code, 'reason_too_thin');
+  const long = flags.normalizePageAsk({ reason: 'x'.repeat(flags.MAX_REASON_CHARS + 1) }, 'landing:index');
+  assert.equal(long.code, 'reason_too_long');
+});
+
+await test('a page ask is scope page, points at the page twice, and holds no text', () => {
+  const r = flags.normalizePageAsk({ reason: GOOD_REASON }, 'builders:studio');
+  assert.equal(r.ok, true);
+  assert.equal(r.value.scope, 'page');
+  assert.equal(r.value.page_id, 'builders:studio');
+  // surface = page id: what makes 001's one-open-per-target index mean one
+  // open ask per (builder, page), and what copy_desk_flags_page_surface_chk pins.
+  assert.equal(r.value.surface, 'builders:studio');
+  assert.equal(r.value.string_id, null);
+  assert.equal(r.value.text_at_flag, null);
+});
+
+await test('the migration pins the page target both ways and ties surface to the page', async () => {
+  const fs = await import('node:fs');
+  const url = await import('node:url');
+  const path = await import('node:path');
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const sql = fs.readFileSync(path.join(here, '..', 'migrations', 'copy_desk_002_page_asks.sql'), 'utf8');
+  assert.ok(/\(scope = 'page'\) = \(page_id IS NOT NULL\)/.test(sql), 'page_id present exactly for scope page');
+  assert.ok(/\(scope = 'string'\) = \(string_id IS NOT NULL\)/.test(sql), 'the string half of the target rule survives the widening');
+  assert.ok(/scope <> 'page' OR surface = page_id/.test(sql), 'a page ask keeps surface = page_id');
+});
+
 // ---------------------------------------------------------------------------
 // Closing a flag.
 // ---------------------------------------------------------------------------