@bongos/core 1.19.1059 → 1.19.1061

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

@@ -1,5 +1,6 @@
-// modules/copy-desk/page-status.js — the three Tweak Mode READS, derived
-// (task 1004316 / BV2.TW05, ADR 0341 D7 and D8).
+// modules/copy-desk/page-status.js — the Tweak Mode READS, derived
+// (task 1004316 / BV2.TW05, and the recommendation, task 1004318 / BV2.TW07;
+// 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
@@ -13,7 +14,7 @@
 //   * 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:
+// The four reads:
 //
 //   PER PAGE      status (Untweaked / Text tweaked / UI tweaked / Both) with its
 //                 count ("Text tweaked 2x"), the changelog, and the lines changed
@@ -22,6 +23,8 @@
 //                 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.
+//   NEXT          the recommendation (TW07): the page to tweak next, its why,
+//                 and the next few for "pick another" (composeNext, below).
 //
 // Pure: no fs, no DB, no clock (the caller passes `now`). The route owns the I/O.
 
@@ -340,8 +343,179 @@ function composeTally({ builderId, tasks, creditRows, now }) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// The recommendation, "what should I tweak next" (task 1004318 / BV2.TW07,
+// ADR 0341 D8). The fourth read, over the same ledger rows as the other three
+// plus one more signal: the open page asks (flags.pageAskSummary()).
+//
+// WHO MAY BE RECOMMENDED A PAGE. Exactly the pages the claim route would hand
+// the caller, decided by the claim's own rule (modules/lifecycle/
+// page-tweak-claim.js) over the same fields, so "take next" on the answer can
+// never be refused for a reason this read already knew:
+//
+//   no open round                      free: the claim creates round n+1
+//   open, held by someone else         SKIPPED (page_held)
+//   open, the caller's own web claim   RESUME, reported apart, never a
+//                                      recommendation (the caller is already
+//                                      writing it)
+//   open, the caller's own CLI claim   SKIPPED: they are applying it (in flight)
+//   open, unheld, roundOpenForWriting  free: an unheld draft, taken over
+//   open, unheld, anything else        SKIPPED (page_in_flight)
+//
+// THE ORDER (D8). Four tiers, and within each its own ties, then the base
+// order (surface landing, builders, status, then inventory order):
+//
+//   asked      open asks: most distinct askers first, then the OLDEST ask
+//   changed    tweaked and drifted: most changed lines first
+//   untweaked  count 0
+//   tweaked    tweaked with no drift, or drift unknown: last
+//
+// The mock's sample list puts an untweaked page before a changed one; the
+// spec's order wins and the mock's list is sample data (ADR 0341 pick 8).
+// ---------------------------------------------------------------------------
+
+const NEXT_ALTERNATIVES = 4; // the mock's "pick another" row holds four
+const NEXT_TIERS = Object.freeze(['asked', 'changed', 'untweaked', 'tweaked']);
+
+function plural(n, one, many) { return `${n} ${n === 1 ? one : many}`; }
+
+// Where the caller stands with one page, by the claim route's own rule.
+function availability(rounds, builderId) {
+  const open = [...(rounds || [])].reverse().find((r) => !TERMINAL.has(r.status)) || null;
+  if (!open) return { kind: 'free', open: null };
+  if (open.holder_id != null) {
+    if (String(open.holder_id) !== String(builderId)) {
+      return { kind: 'held', open, holder: person(open.holder_id, open.holder_login) };
+    }
+    return open.holder_worktree ? { kind: 'in_flight', open } : { kind: 'resume', open };
+  }
+  return pages.roundOpenForWriting(open) ? { kind: 'free', open } : { kind: 'in_flight', open };
+}
+
+function surfaceWord(id) {
+  return (SURFACE_LABELS[id] || id).toLowerCase();
+}
+
+function candidateFor({ page, rounds, readingPage, readingsOk, ask, builderId, avail }) {
+  const counts = countsFor(rounds);
+  const drift = driftFor(readingPage, rounds, readingsOk);
+  const askers = ask ? ask.askers : 0;
+  // "Lines changed": a reworded line is one line that differs on each side of
+  // the multiset, so it counts once; a line only added, or only removed, still
+  // counts. The larger side is that number.
+  const changedLines = drift.known && drift.changed ? Math.max(drift.changed_count, drift.removed_count) : 0;
+  const last = latestShipped(rounds);
+  const yours = !!last && last.artist_id != null && String(last.artist_id) === String(builderId);
+
+  const parts = [];
+  if (askers > 0) parts.push(`${plural(askers, 'person', 'people')} asked for it`);
+  if (counts.count === 0) parts.push('untweaked');
+  else if (changedLines > 0) parts.push(`${plural(changedLines, 'line', 'lines')} changed since ${yours ? 'your' : 'the'} last pass`);
+  else parts.push(drift.known ? `${counts.status_label.toLowerCase()}, nothing changed since` : counts.status_label.toLowerCase());
+
+  let tier = 'tweaked';
+  if (askers > 0) tier = 'asked';
+  else if (changedLines > 0) tier = 'changed';
+  else if (counts.count === 0) tier = 'untweaked';
+
+  return {
+    page_id: page.id,
+    surface: page.surface,
+    title: page.title || page.id,
+    path: page.path || null,
+    tier,
+    why: parts[0],
+    why_line: [surfaceWord(page.surface), ...parts].join(' · '),
+    askers,
+    oldest_ask_at: ask ? iso(ask.oldest_ask_at) : null,
+    changed_lines: changedLines,
+    drift_known: drift.known,
+    count: counts.count,
+    status_label: counts.status_label,
+    // An unheld draft the claim takes over, so the take is honest about it.
+    draft_round: avail.open ? { task_id: String(avail.open.id), round: avail.open.round } : null,
+    take: { method: 'POST', path: `/copy-desk/pages/${page.id}/claim` },
+  };
+}
+
+function compareCandidates(a, b) {
+  const t = NEXT_TIERS.indexOf(a.tier) - NEXT_TIERS.indexOf(b.tier);
+  if (t) return t;
+  if (a.tier === 'asked') {
+    if (a.askers !== b.askers) return b.askers - a.askers;
+    const at = a.oldest_ask_at ? Date.parse(a.oldest_ask_at) : Infinity;
+    const bt = b.oldest_ask_at ? Date.parse(b.oldest_ask_at) : Infinity;
+    if (at !== bt) return at - bt;
+  }
+  if (a.tier === 'changed' && a.changed_lines !== b.changed_lines) return b.changed_lines - a.changed_lines;
+  return a._base - b._base;
+}
+
+// GET /copy-desk/next — the recommended page for `builderId`, its why, and
+// the next few for "pick another". `asks` is flags.pageAskSummary()'s rows.
+function composeNext({ inventory, readings, tasks, asks, builderId, alternatives = NEXT_ALTERNATIVES }) {
+  const byPage = indexRounds(tasks);
+  const readingsOk = !!readings;
+  const rIdx = readingIndex(readings);
+  const askIdx = new Map();
+  for (const a of asks || []) if (a && a.page_id && Number(a.askers) > 0) askIdx.set(a.page_id, { askers: Number(a.askers), oldest_ask_at: a.oldest_ask_at });
+
+  const surfaceRank = new Map(orderedSurfaces(inventory).map((id, i) => [id, i]));
+  const invPages = ((inventory && inventory.pages) || []).filter((p) => p && p.id);
+  const base = new Map(invPages
+    .map((p, i) => ({ id: p.id, s: surfaceRank.has(p.surface) ? surfaceRank.get(p.surface) : surfaceRank.size, i }))
+    .sort((a, b) => a.s - b.s || a.i - b.i)
+    .map((x, k) => [x.id, k]));
+
+  let resume = null;
+  const skipped = [];
+  const candidates = [];
+  for (const page of invPages) {
+    const rounds = byPage.get(page.id) || [];
+    const avail = availability(rounds, builderId);
+    if (avail.kind === 'resume') {
+      resume = {
+        page_id: page.id, surface: page.surface, title: page.title || page.id, path: page.path || null,
+        task_id: String(avail.open.id), round: avail.open.round,
+        take: { method: 'POST', path: `/copy-desk/pages/${page.id}/claim` },
+      };
+      continue;
+    }
+    if (avail.kind === 'held' || avail.kind === 'in_flight') {
+      skipped.push({
+        page_id: page.id,
+        reason: avail.kind === 'held' ? 'page_held' : 'page_in_flight',
+        state: roundState(avail.open),
+        ...(avail.holder ? { holder: avail.holder } : {}),
+      });
+      continue;
+    }
+    const c = candidateFor({ page, rounds, readingPage: rIdx.get(page.id), readingsOk, ask: askIdx.get(page.id), builderId, avail });
+    c._base = base.get(page.id);
+    candidates.push(c);
+  }
+  candidates.sort(compareCandidates);
+  for (const c of candidates) delete c._base;
+
+  const n = Math.max(0, Math.floor(Number(alternatives) || 0));
+  return {
+    builder_id: String(builderId),
+    resume,
+    recommended: candidates[0] || null,
+    alternatives: candidates.slice(1, 1 + n),
+    candidates: candidates.length,
+    // "4 pages have been asked for" (the mock's Artist Review Status line):
+    // every inventory page with an open ask, held or not.
+    asked_pages: invPages.filter((p) => askIdx.has(p.id)).length,
+    skipped,
+  };
+}
+
 module.exports = {
   TALLY_REASON_PREFIX,
+  NEXT_ALTERNATIVES,
+  NEXT_TIERS,
+  composeNext,
   SURFACE_ORDER,
   SURFACE_LABELS,
   STATUS,

package/modules/copy-desk/pages.js

@@ -215,6 +215,196 @@ function roundOpenForWriting(task) {
   return !!task && task.status === 'ready' && !blockPresence(task.description).batch;
 }
 
+// ---------------------------------------------------------------------------
+// The draft and the submit (task 1004319 / BV2.TW08, ADR 0341 D4).
+//
+// Both resolve every TARGET from the page reading (docs/page-readings.json),
+// never from the request body (ADR 0233 §7). A draft save sends only
+// { reading_hash, lines: [{ key, after }] }; the line's section, its current
+// text (`before`) and its placement are copied from the reading. The submit
+// re-resolves each draft line against the CURRENT reading, so a line the page
+// no longer shows is refused by name (`target_gone`) instead of being frozen
+// against a sentence that is not there.
+// ---------------------------------------------------------------------------
+
+// The interpolation hole the inventory writes for `${...}` (proposals.js's
+// PLACEHOLDER; restated here because this file requires nothing).
+const PLACEHOLDER = '{…}';
+// One rewritten line. The longest line any page shows today is 760 characters,
+// so 1000 leaves room to rewrite it and still bounds a draft.
+const MAX_LINE_CHARS = 1000;
+// A draft holds changed lines only, and the longest page has under 500 lines.
+const MAX_DRAFT_LINES = 1000;
+const UNPLACED_SOURCE = 'page-tweak-unplaced';
+const LINE_KEY_RE = /^L[0-9]{4,}$/;
+
+// The inventory's own whitespace rule (proposals.js tidy): a line is measured
+// and compared in the form the reading records it.
+function tidy(raw) {
+  return String(raw == null ? '' : raw).replace(/\s+/g, ' ').trim();
+}
+
+function placeholderCount(text) {
+  return String(text || '').split(PLACEHOLDER).length - 1;
+}
+
+// Replace the ONE block of a fence in a description, or append it when there is
+// none. A description carrying two is refused rather than guessed at.
+function replaceBlock(markdown, fence, block) {
+  const src = String(markdown || '');
+  const re = new RegExp('```' + fence.replace(/-/g, '\\-') + '[ \\t]*\\r?\\n[\\s\\S]*?\\r?\\n```', 'g');
+  const hits = src.match(re) || [];
+  if (hits.length > 1) return fail('multiple_blocks', { fence, count: hits.length });
+  if (hits.length === 1) return { ok: true, description: src.replace(re, () => block) };
+  return { ok: true, description: src.trimEnd() + (src.trim() ? '\n\n' : '') + block };
+}
+
+// resolveDraft({ readingPage, body, savedAt }) -> { ok, draft } | refusal
+//
+// A WHOLE-DRAFT replace: the body is every changed line the artist has, and the
+// draft becomes exactly that. A line whose `after` equals the page's current
+// text is not a change and is dropped, so only changed lines are stored (D4).
+// Placeholder arithmetic is NOT checked here: an autosave lands mid-sentence,
+// and the check belongs to the submit (and again to the applier).
+function resolveDraft({ readingPage, body, savedAt }) {
+  if (!readingPage || !Array.isArray(readingPage.lines)) return fail('reading_missing');
+  const b = body || {};
+  if (String(b.reading_hash || '') !== String(readingPage.reading_hash || '')) {
+    return fail('reading_moved', { reading_hash: readingPage.reading_hash || null, sent: b.reading_hash || null });
+  }
+  const list = Array.isArray(b.lines) ? b.lines : [];
+  if (list.length > MAX_DRAFT_LINES) return fail('too_many_lines', { max: MAX_DRAFT_LINES, was: list.length });
+  const byKey = new Map(readingPage.lines.map((l) => [l.key, l]));
+  const seen = new Set();
+  const unknown = [];
+  const tooLong = [];
+  const empty = [];
+  const out = [];
+  for (const raw of list) {
+    const key = raw && typeof raw.key === 'string' ? raw.key : '';
+    if (!LINE_KEY_RE.test(key) || typeof raw.after !== 'string') return fail('line_malformed', { line: raw == null ? null : raw });
+    if (seen.has(key)) return fail('duplicate_line', { key });
+    seen.add(key);
+    const at = byKey.get(key);
+    if (!at) { unknown.push(key); continue; }
+    const after = tidy(raw.after);
+    if (after === tidy(at.text)) continue;
+    if (!after) { empty.push(key); continue; }
+    if (after.length > MAX_LINE_CHARS) { tooLong.push(key); continue; }
+    out.push({ key, section: at.section == null ? null : at.section, before: at.text, after, placement: at.placement });
+  }
+  if (unknown.length) return fail('unknown_line', { keys: unknown });
+  if (empty.length) return fail('line_empty', { keys: empty });
+  if (tooLong.length) return fail('line_too_long', { keys: tooLong, max: MAX_LINE_CHARS });
+  // Page order, whatever order the editor sent them in.
+  const order = new Map(readingPage.lines.map((l, i) => [l.key, i]));
+  out.sort((x, y) => order.get(x.key) - order.get(y.key));
+  return { ok: true, draft: { page_id: readingPage.id, reading_hash: readingPage.reading_hash, saved_at: savedAt, lines: out } };
+}
+
+// Is a newly resolved draft the one already saved? Then the save writes
+// nothing: an autosave that changed nothing must not touch the task.
+function sameDraft(saved, next) {
+  if (!saved || !next) return false;
+  const pick = (d) => JSON.stringify([d.page_id, d.reading_hash,
+    (d.lines || []).map((l) => [l.key, l.section == null ? null : l.section, l.before, l.after, l.placement])]);
+  return pick(saved) === pick(next);
+}
+
+// Find a draft line on the CURRENT reading: the same key showing the same text,
+// else the one line showing that text in the same section, else the one line
+// showing it anywhere on the page. Anything else is gone, or too ambiguous to
+// pick for the artist.
+function locateLine(lines, draftLine) {
+  const same = (l) => l.text === draftLine.before;
+  const byKey = lines.find((l) => l.key === draftLine.key);
+  if (byKey && same(byKey)) return { line: byKey };
+  const inSection = lines.filter((l) => same(l) && l.section === draftLine.section);
+  if (inSection.length === 1) return { line: inSection[0] };
+  const anywhere = lines.filter(same);
+  if (anywhere.length === 1) return { line: anywhere[0] };
+  return { code: anywhere.length > 1 ? 'ambiguous_target' : 'target_gone' };
+}
+
+// A line the applier cannot place goes to an engineer (spec decision 7). That
+// is every `unplaced` line, and a `shared` line the registry has no row for:
+// shell text with no file behind it cannot be applied mechanically either.
+function goesToEngineer(line) {
+  return line.placement === 'unplaced' || (line.placement === 'shared' && !line.file);
+}
+
+// freezeBatch({ readingPage, draft, submittedAt }) -> { ok, batch, unplaced } | refusal
+//
+// The submit's pure half. Every draft line is re-resolved on the current
+// reading; a refused line (`target_gone`, `ambiguous_target`,
+// `placeholder_mismatch`) refuses the submit, naming each line, and nothing is
+// frozen: the artist fixes those lines and submits again. `batch` is the
+// `page-tweak` block's content without its `unplaced_tasks` (the lifecycle
+// transaction fills those in once the engineer tasks exist). `unplaced` is the
+// lines taken out of it.
+function freezeBatch({ readingPage, draft, submittedAt }) {
+  if (!readingPage || !Array.isArray(readingPage.lines)) return fail('reading_missing');
+  if (!draft || !Array.isArray(draft.lines) || !draft.lines.length) return fail('nothing_to_submit');
+  const refused = [];
+  const placed = [];
+  const unplaced = [];
+  const keys = new Set();
+  for (const d of draft.lines) {
+    const found = locateLine(readingPage.lines, d);
+    if (!found.line) { refused.push({ key: d.key, section: d.section == null ? null : d.section, before: d.before, code: found.code }); continue; }
+    const at = found.line;
+    if (keys.has(at.key)) { refused.push({ key: d.key, section: d.section == null ? null : d.section, before: d.before, code: 'ambiguous_target' }); continue; }
+    keys.add(at.key);
+    const line = { key: at.key, section: at.section == null ? null : at.section, before: at.text, after: d.after, placement: at.placement };
+    if (goesToEngineer(at)) { unplaced.push(line); continue; }
+    const want = placeholderCount(at.text);
+    const got = placeholderCount(d.after);
+    if (want !== got) { refused.push({ key: at.key, section: line.section, before: at.text, code: 'placeholder_mismatch', expected: want, got }); continue; }
+    placed.push({ ...line, file: at.file, line: at.line == null ? null : at.line, string_id: at.string_id == null ? null : at.string_id });
+  }
+  if (refused.length) return fail('lines_refused', { refused });
+  const order = new Map(readingPage.lines.map((l, i) => [l.key, i]));
+  const byOrder = (x, y) => order.get(x.key) - order.get(y.key);
+  return {
+    ok: true,
+    batch: { page_id: readingPage.id, reading_hash: readingPage.reading_hash, submitted_at: submittedAt, lines: placed.sort(byOrder) },
+    unplaced: unplaced.sort(byOrder),
+  };
+}
+
+// The engineer task an unplaced rewrite files (ADR 0341 D4): one per line,
+// keyed so a repeated submit finds the task it already filed.
+function unplacedSourceRef(roundTaskId, key) {
+  return `${UNPLACED_SOURCE}/${roundTaskId}/${key}`;
+}
+
+function clip(text, n) {
+  const s = String(text || '');
+  return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+
+function unplacedTaskTitle(page, line) {
+  return `Place and reword "${clip(line.before, 60)}" (${page.id})`;
+}
+
+function unplacedTaskBody(page, line, roundTaskId) {
+  const where = line.placement === 'shared'
+    ? 'It is shared shell text (it shows on every page of the surface), and the copy registry has no row for it.'
+    : 'The copy registry cannot place it: the string is built somewhere the inventory does not read (data from an API, a string assembled in code, or markup the extractors miss).';
+  return [
+    `An artist rewrote a line on **${String(page.title || page.id)}** (\`${page.id}\`${page.path ? `, ${page.path}` : ''}) that the applier cannot change mechanically, so it comes to an engineer (ADR 0341 D4, spec decision 7).`,
+    '',
+    where,
+    '',
+    `- Section: ${line.section == null ? '(none)' : line.section}`,
+    `- Line: ${line.key} in the page reading`,
+    `- It says now: ${JSON.stringify(line.before)}`,
+    `- The artist's wording: ${JSON.stringify(line.after)}`,
+    '',
+    `Find where this text is rendered and change it to the artist's wording, or make it a string the copy registry can place so the next tweak can change it directly. The page's tweak round (task ${roundTaskId}) does not wait for this.`,
+  ].join('\n');
+}
+
 module.exports = {
   SCHEMA,
   SOURCE,
@@ -235,4 +425,14 @@ module.exports = {
   parseSentBackBlocks,
   blockPresence,
   roundOpenForWriting,
+  MAX_LINE_CHARS,
+  MAX_DRAFT_LINES,
+  UNPLACED_SOURCE,
+  replaceBlock,
+  resolveDraft,
+  sameDraft,
+  freezeBatch,
+  unplacedSourceRef,
+  unplacedTaskTitle,
+  unplacedTaskBody,
 };