@bongos/core 1.19.1057 → 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/page-data.js

@@ -0,0 +1,79 @@
+// modules/copy-desk/page-data.js — the READ side of the two committed page
+// artifacts Tweak Mode keys on (task 1004316 / BV2.TW05, ADR 0341 D1 and D3).
+//
+//   docs/page-inventory.json   every page, its surface, title and files
+//                              (scripts/gds/page-inventory.js, TW02)
+//   docs/page-readings.json    every page's visible lines, in page order
+//                              (scripts/gds/page-reader.js, TW04)
+//
+// This is the first SERVER path that reads either, so both now ship in the
+// publish manifest (scripts/gds/publish-manifest.js, the copy-registry
+// precedent of ADR 0178). Same rules as registry.js, for the same reasons:
+//
+//   * READ, never written or regenerated here. The reader opens a browser; a GET
+//     that did that would make two replicas disagree about what a page says.
+//   * (mtime, size) cache: the files change at deploy, not per request.
+//   * A MISSING OR CORRUPT FILE IS A NAMED STATE, NEVER A CRASH. An instance on
+//     an older core, or a checkout that has not run the generator, gets
+//     { ok: false, code, detail } with the command that fixes it. The routes
+//     answer a missing inventory with a named 503 (there is no page to speak
+//     of), and a missing reading by marking drift unknown, because status,
+//     count and changelog come from the ledger and still read true without it.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+const ARTIFACTS = Object.freeze({
+  inventory: Object.freeze({
+    rel: 'docs/page-inventory.json',
+    run: 'node scripts/gds/page-inventory.js',
+    missing: 'page_inventory_missing',
+    unreadable: 'page_inventory_unreadable',
+  }),
+  readings: Object.freeze({
+    rel: 'docs/page-readings.json',
+    run: 'node scripts/gds/page-reader.js --stale',
+    missing: 'page_readings_missing',
+    unreadable: 'page_readings_unreadable',
+  }),
+});
+
+const _cache = new Map();
+
+// Test seam: point a loader at another root (a temp dir holding fixture files,
+// or an empty one to prove the degrade). Never called by the routes.
+let _root = ROOT;
+function _setRoot(dir) { _root = dir || ROOT; _cache.clear(); }
+
+function load(which) {
+  const a = ARTIFACTS[which];
+  const abs = path.join(_root, a.rel);
+  let st;
+  try { st = fs.statSync(abs); } catch {
+    return { ok: false, code: a.missing, detail: { expected_at: a.rel, run: a.run } };
+  }
+  const key = `${abs}:${st.mtimeMs}:${st.size}`;
+  const hit = _cache.get(which);
+  if (hit && hit.key === key) return hit.value;
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(abs, 'utf8'));
+  } catch (err) {
+    return { ok: false, code: a.unreadable, detail: { expected_at: a.rel, reason: err.message, run: a.run } };
+  }
+  if (!parsed || !Array.isArray(parsed.pages)) {
+    return { ok: false, code: a.unreadable, detail: { expected_at: a.rel, reason: 'no pages[] array', run: a.run } };
+  }
+  const value = { ok: true, data: parsed, at: a.rel };
+  _cache.set(which, { key, value });
+  return value;
+}
+
+function loadInventory() { return load('inventory'); }
+function loadReadings() { return load('readings'); }
+
+module.exports = { ARTIFACTS, loadInventory, loadReadings, _setRoot };

package/modules/copy-desk/page-status.js

@@ -0,0 +1,357 @@
+// modules/copy-desk/page-status.js — the three Tweak Mode READS, derived
+// (task 1004316 / BV2.TW05, ADR 0341 D7 and D8).
+//
+// There is NO status table, by the planning session's ruling: a table would be a
+// second record of what the task ledger already says. Everything here is a pure
+// function over
+//
+//   * the page-tweak tasks (source 'page-tweak'), as the lifecycle port's
+//     listPageTweakTasks() returns them: status, description (the fenced blocks
+//     of pages.js), shipped_at, the latest grade, the active claim and the
+//     round's artist;
+//   * docs/page-inventory.json (which pages exist, their surface and files);
+//   * docs/page-readings.json (what each page says now), for drift only;
+//   * the caller's `tweak.page_approved:` credit rows, for the tally.
+//
+// The three reads:
+//
+//   PER PAGE      status (Untweaked / Text tweaked / UI tweaked / Both) with its
+//                 count ("Text tweaked 2x"), the changelog, and the lines changed
+//                 since the last tweak (drift).
+//   PER SURFACE   Artist Review Status: "N of M tweaked". N counts pages with a
+//                 shipped round, and drift does not lower it.
+//   PER ARTIST    the studio corner's tally: credits from approved pages, pages
+//                 tweaked, and this week's gain.
+//
+// Pure: no fs, no DB, no clock (the caller passes `now`). The route owns the I/O.
+
+'use strict';
+
+const pages = require('./pages');
+
+const TERMINAL = new Set(['shipped', 'abandoned']);
+
+// The credit reason ADR 0341 D10 books an approved page under. TW13 writes it;
+// until then no row carries it and every tally reads 0, which is the truth.
+const TALLY_REASON_PREFIX = 'tweak.page_approved:';
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+
+// Surface order and names, the mock's (docs/design/mocks/tweak-mode/Main.dc.html:
+// Landing, Builders hall, Status). A surface the inventory adds later sorts after
+// these, in inventory order, under its own id.
+const SURFACE_ORDER = Object.freeze(['landing', 'builders', 'status']);
+const SURFACE_LABELS = Object.freeze({ landing: 'Landing', builders: 'Builders hall', status: 'Status' });
+
+const STATUS = Object.freeze({
+  untweaked: 'Untweaked',
+  text: 'Text tweaked',
+  ui: 'UI tweaked',
+  both: 'Both',
+});
+
+function iso(v) {
+  if (v == null) return null;
+  const d = v instanceof Date ? v : new Date(v);
+  return Number.isNaN(d.getTime()) ? null : d.toISOString();
+}
+
+function person(id, login) {
+  if (id == null) return null;
+  return { id: String(id), login: login || null };
+}
+
+// ---------------------------------------------------------------------------
+// Grouping the ledger by page.
+// ---------------------------------------------------------------------------
+
+// rounds by page id, each list in round order. A task whose source_ref does not
+// parse (a hand-made row) belongs to no page and is skipped, not guessed at.
+function indexRounds(tasks) {
+  const byPage = new Map();
+  for (const t of tasks || []) {
+    const ref = pages.parseRoundRef(t && t.source_ref);
+    if (!ref) continue;
+    const round = { ...t, page_id: ref.page_id, round: ref.round };
+    const list = byPage.get(ref.page_id);
+    if (list) list.push(round); else byPage.set(ref.page_id, [round]);
+  }
+  for (const list of byPage.values()) list.sort((a, b) => a.round - b.round || Number(a.id) - Number(b.id));
+  return byPage;
+}
+
+// ---------------------------------------------------------------------------
+// Count and status (D8).
+// ---------------------------------------------------------------------------
+
+// A shipped round counts as TEXT unless its batch says kind 'ui'. While Tweak
+// Mode is text only no batch carries a kind, so the UI count reads 0 — the field
+// is reserved, not invented. A shipped round whose batch cannot be read is still
+// a shipped round, and still text.
+function roundKind(round) {
+  const b = pages.parseBatchBlock(round.description);
+  return b.ok && b.batch.kind === 'ui' ? 'ui' : 'text';
+}
+
+function countsFor(rounds) {
+  const shipped = (rounds || []).filter((r) => r.status === 'shipped');
+  let ui = 0;
+  for (const r of shipped) if (roundKind(r) === 'ui') ui++;
+  const count = shipped.length;
+  const text = count - ui;
+  let status = STATUS.untweaked;
+  if (text > 0 && ui > 0) status = STATUS.both;
+  else if (text > 0) status = STATUS.text;
+  else if (ui > 0) status = STATUS.ui;
+  return {
+    count,
+    text_count: text,
+    ui_count: ui,
+    status,
+    status_label: count === 0 ? STATUS.untweaked : `${status} ${count}x`,
+  };
+}
+
+function latestShipped(rounds) {
+  const shipped = (rounds || []).filter((r) => r.status === 'shipped');
+  return shipped.length ? shipped[shipped.length - 1] : null;
+}
+
+// When the page's latest shipped round landed (ISO), or null for an untweaked
+// page: the `since` the detail route reads the later ships from.
+function lastRoundShippedAt(tasks, pageId) {
+  const last = latestShipped(indexRounds(tasks).get(pageId));
+  return last ? iso(last.shipped_at) : null;
+}
+
+// ---------------------------------------------------------------------------
+// Drift, "changed since last tweak" (D8, spec decision 8).
+//
+// The page's current NON-SHARED reading lines, compared as a MULTISET of texts
+// with lines_after of its latest shipped round. Shared shell lines are left out
+// on both sides (builder pick 7): a shell change must not mark all 30 hall pages
+// changed. A multiset, not a set, because a page may say "Save" twice and lose
+// one of them.
+// ---------------------------------------------------------------------------
+
+function driftFor(readingPage, rounds, readingsOk) {
+  const last = latestShipped(rounds);
+  if (!last) return { known: true, since_task_id: null, changed: false, changed_count: 0, removed_count: 0, changed_lines: [], removed_lines: [] };
+  const base = { since_task_id: String(last.id), since: iso(last.shipped_at) };
+  if (!readingsOk) return { known: false, reason: 'readings_missing', ...base };
+  if (!readingPage) return { known: false, reason: 'page_not_read', ...base };
+  const applied = pages.parseAppliedBlock(last.description);
+  if (!applied.ok) return { known: false, reason: 'no_applied_block', ...base };
+
+  const left = new Map();
+  for (const t of applied.applied.lines_after) left.set(t, (left.get(t) || 0) + 1);
+  const changed = [];
+  for (const l of readingPage.lines || []) {
+    if (!l || l.placement === 'shared') continue;
+    const n = left.get(l.text) || 0;
+    if (n > 0) left.set(l.text, n - 1);
+    else changed.push({ key: l.key, section: l.section, text: l.text });
+  }
+  const removed = [];
+  for (const [text, n] of left) for (let i = 0; i < n; i++) removed.push(text);
+  return {
+    known: true,
+    ...base,
+    changed: changed.length > 0 || removed.length > 0,
+    changed_count: changed.length,
+    removed_count: removed.length,
+    changed_lines: changed,
+    removed_lines: removed,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The open round and its state (D7). Derived, never stored.
+// ---------------------------------------------------------------------------
+
+function roundState(round) {
+  const p = pages.blockPresence(round.description);
+  switch (round.status) {
+    case 'active':
+      if (round.holder_id == null) return 'unknown';
+      return round.holder_worktree ? 'applying' : 'writing';
+    case 'ready':
+      if (p.batch) {
+        // submitted = a batch, and no applied block newer than the latest
+        // send-back. A sent-back round reads submitted again (the mock's
+        // "it comes back to the queue once it is re-applied").
+        if (!p.applied) return 'submitted';
+        if (p.last_sent_back_at && (!p.applied_at || p.applied_at <= p.last_sent_back_at)) return 'submitted';
+        return 'unknown';
+      }
+      return p.draft ? 'draft' : 'unknown';
+    case 'completed':
+      // A held pass waits for the artist; a failed grade stays with the applier.
+      return round.grade_passed === true ? 'waiting_for_artist' : 'applying';
+    case 'confirmed':
+      return 'landing';
+    default:
+      return 'unknown';
+  }
+}
+
+function openRound(rounds) {
+  const open = (rounds || []).filter((r) => !TERMINAL.has(r.status));
+  if (!open.length) return null;
+  const r = open[open.length - 1];
+  return {
+    task_id: String(r.id),
+    round: r.round,
+    status: r.status,
+    state: roundState(r),
+    holder: person(r.holder_id, r.holder_login),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The changelog (D8): one entry per shipped round, newest first.
+// ---------------------------------------------------------------------------
+
+function changelogFor(rounds) {
+  const out = [];
+  for (const r of (rounds || []).filter((x) => x.status === 'shipped')) {
+    const b = pages.parseBatchBlock(r.description);
+    const lines = b.ok ? b.batch.lines.map((l) => ({ key: l.key, section: l.section || null, before: l.before, after: l.after })) : [];
+    out.push({
+      task_id: String(r.id),
+      round: r.round,
+      artist: person(r.artist_id, r.artist_login),
+      shipped_at: iso(r.shipped_at),
+      kind: roundKind(r),
+      line_count: lines.length,
+      lines,
+      ...(b.ok ? {} : { batch_unreadable: b.code }),
+    });
+  }
+  return out.reverse();
+}
+
+// ---------------------------------------------------------------------------
+// Composition.
+// ---------------------------------------------------------------------------
+
+function readingIndex(readings) {
+  const m = new Map();
+  for (const p of (readings && readings.pages) || []) if (p && p.id) m.set(p.id, p);
+  return m;
+}
+
+function summaryFor(page, rounds, readingPage, readingsOk) {
+  // The list carries drift's counts; the lines themselves are the detail read's.
+  const drift = { ...driftFor(readingPage, rounds, readingsOk) };
+  delete drift.changed_lines;
+  delete drift.removed_lines;
+  return {
+    id: page.id,
+    surface: page.surface,
+    title: page.title || page.id,
+    path: page.path || null,
+    ...countsFor(rounds),
+    drift,
+    open_round: openRound(rounds),
+  };
+}
+
+function orderedSurfaces(inventory) {
+  const ids = [];
+  for (const s of (inventory && inventory.surfaces) || []) if (s && s.id && !ids.includes(s.id)) ids.push(s.id);
+  for (const p of (inventory && inventory.pages) || []) if (p && p.surface && !ids.includes(p.surface)) ids.push(p.surface);
+  const rank = (id) => { const i = SURFACE_ORDER.indexOf(id); return i === -1 ? SURFACE_ORDER.length : i; };
+  return ids.map((id, i) => ({ id, i })).sort((a, b) => rank(a.id) - rank(b.id) || a.i - b.i).map((x) => x.id);
+}
+
+// GET /copy-desk/pages — every page's status, count and drift, plus the
+// per-surface rollup (Artist Review Status).
+function composePages({ inventory, readings, tasks }) {
+  const byPage = indexRounds(tasks);
+  const readingsOk = !!readings;
+  const rIdx = readingIndex(readings);
+  const list = ((inventory && inventory.pages) || []).map((p) => summaryFor(p, byPage.get(p.id) || [], rIdx.get(p.id), readingsOk));
+
+  const surfaces = orderedSurfaces(inventory).map((id) => {
+    const on = list.filter((p) => p.surface === id);
+    const tweaked = on.filter((p) => p.count >= 1).length;
+    return { id, label: SURFACE_LABELS[id] || id, tweaked, total: on.length, line: `${tweaked} of ${on.length} tweaked` };
+  });
+  const tweaked = list.filter((p) => p.count >= 1).length;
+  return {
+    pages: list,
+    surfaces,
+    totals: { tweaked, total: list.length, line: `${tweaked} of ${list.length} pages tweaked` },
+  };
+}
+
+// The ships that changed a page since its last round, as the payload carries them.
+function shipList(ships) {
+  return (ships || []).map((s) => ({ task_id: String(s.id), title: s.title, shipped_at: iso(s.shipped_at) }));
+}
+
+// GET /copy-desk/pages/:pageId — one page, in full. `ships` is the list the
+// route read for drift attribution: shipped tasks since the last round whose
+// touches meet the page's files.
+function composePage({ page, tasks, readingPage, readingsOk, ships }) {
+  const rounds = indexRounds(tasks).get(page.id) || [];
+  const drift = driftFor(readingPage, rounds, readingsOk);
+  return {
+    id: page.id,
+    surface: page.surface,
+    title: page.title || page.id,
+    path: page.path || null,
+    files: page.files || [],
+    ...countsFor(rounds),
+    changelog: changelogFor(rounds),
+    drift: {
+      ...drift,
+      ships: drift.since_task_id ? shipList(ships) : [],
+    },
+    open_round: openRound(rounds),
+    reading_hash: readingPage ? readingPage.reading_hash || null : null,
+  };
+}
+
+// GET /copy-desk/tally — the caller's corner tally.
+function composeTally({ builderId, tasks, creditRows, now }) {
+  const nowMs = now instanceof Date ? now.getTime() : Number(now);
+  const since = nowMs - WEEK_MS;
+  let credits = 0;
+  let week = 0;
+  for (const row of creditRows || []) {
+    if (!row || !String(row.reason || '').startsWith(TALLY_REASON_PREFIX)) continue;
+    const d = Number(row.delta) || 0;
+    credits += d;
+    const at = new Date(row.recorded_at).getTime();
+    if (!Number.isNaN(at) && at >= since && at <= nowMs) week += d;
+  }
+  let pagesTweaked = 0;
+  for (const t of tasks || []) {
+    if (t && t.status === 'shipped' && pages.parseRoundRef(t.source_ref) && String(t.artist_id) === String(builderId)) pagesTweaked++;
+  }
+  return {
+    builder_id: String(builderId),
+    credits,
+    pages_tweaked: pagesTweaked,
+    this_week: week,
+    week_since: new Date(since).toISOString(),
+    reason_prefix: TALLY_REASON_PREFIX,
+  };
+}
+
+module.exports = {
+  TALLY_REASON_PREFIX,
+  SURFACE_ORDER,
+  SURFACE_LABELS,
+  STATUS,
+  indexRounds,
+  countsFor,
+  driftFor,
+  roundState,
+  changelogFor,
+  composePages,
+  composePage,
+  lastRoundShippedAt,
+  composeTally,
+};