@bongos/core 1.19.1057 → 1.19.1058

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,
+};

package/modules/copy-desk/pages.js

@@ -0,0 +1,204 @@
+// 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;
+}
+
+// ---------------------------------------------------------------------------
+// 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,
+  };
+}
+
+module.exports = {
+  SCHEMA,
+  SOURCE,
+  FENCES,
+  PAGE_ID_RE,
+  roundSourceRef,
+  parseRoundRef,
+  composeDraftBlock,
+  parseDraftBlock,
+  composeBatchBlock,
+  parseBatchBlock,
+  composeAppliedBlock,
+  parseAppliedBlock,
+  composeSentBackBlock,
+  parseSentBackBlocks,
+  blockPresence,
+};