create-pmos 0.55.5 → 0.57.0

package/workspace/lib/doc-sync-store.js

@@ -0,0 +1,322 @@
+'use strict';
+/* doc-sync-store.js — the file side of the docs sync signal (initiative docs-three-way-sync).
+ *
+ * lib/doc-sync.js decides; this module reads and appends. Both the `pmos docs` verb and the /api/docs routes call it,
+ * so the terminal and the Docs place can never hold two opinions about a link.
+ *
+ *   view(root)                                 → { ok, docs, summary, open, last, file }
+ *   addLink(root, { path, kind, target })      → the artifact-link row (four-panel's store — one link store, not two)
+ *   removeLink(root, { path, kind })           → a `retracted` row; nothing is deleted
+ *   checkStart(root, { by, now })              → { ok, run, links } — what the session must read, with each file's hash
+ *   record(root, { run, by, readings, now })   → { ok, recorded, refused }
+ *   checkFinish(root, { run, by, summary, now })
+ *   syncStart(root, { path, kind, use, by, now })     → { ok, run, … } — one open sync per copy (amended 2026-10-06)
+ *   syncFinish(root, { run, by, version, modified_at, url, title, now }) → the reading that makes the copy read Same
+ *   syncFail(root, { run, by, reason, now })
+ *   findFiles(root, q)                         → the repository's markdown files that match, for search and Add copy
+ *   repoInfo(root, rel) · bodyHash(text) · titleOf(text, rel)
+ *
+ * Local git only (log, status): no fetch, no network. Every write is an append through doc-sync.js#checkRow or
+ * four-panel.js's validators, so a refused row is never on disk.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const D = require('./doc-sync');
+const fourPanel = require('./four-panel');
+const consoleState = require('./console-state');
+
+const LEDGER = 'doc-checks.jsonl';
+// A check left open this long is taken to have ended without saying so (the session closed). A new one may start.
+const OPEN_RUN_MS = 2 * 60 * 60 * 1000;
+// A sync left open this long is taken to have ended (the session closed without finishing). The copy may be synced again.
+const OPEN_SYNC_MS = 30 * 60 * 1000;
+
+function stateDir(root) {
+  const e = consoleState.loadEngine();
+  if (!e.ok) return { ok: false, error: e.error };
+  const dir = fourPanel.storeDir(e.engine, root);
+  return dir ? { ok: true, dir } : { ok: false, error: 'this repository has no file-mode state directory' };
+}
+
+/** The body a copy is compared with: the file without its leading frontmatter, line endings and trailing spaces normalised. */
+function bodyOf(text) {
+  let t = String(text || '').replace(/\r\n?/g, '\n');
+  const m = /^---\n[\s\S]*?\n---[ \t]*(?:\n|$)/.exec(t);
+  if (m) t = t.slice(m[0].length);
+  return t.split('\n').map((l) => l.replace(/[ \t]+$/, '')).join('\n').replace(/^\n+/, '').replace(/\n+$/, '');
+}
+function bodyHash(text) {
+  return crypto.createHash('sha256').update(bodyOf(text)).digest('hex').slice(0, 16);
+}
+function titleOf(text, rel) {
+  const t = String(text || '');
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(t);
+  if (fm) {
+    const m = /^title:\s*(.+?)\s*$/m.exec(fm[1]);
+    if (m) return m[1].replace(/^["']|["']$/g, '').slice(0, 200);
+  }
+  const h = /^#\s+(.+)$/m.exec(bodyOf(t));
+  if (h) return h[1].trim().slice(0, 200);
+  return path.basename(rel).replace(/\.[^.]+$/, '');
+}
+
+function git(root, args) {
+  try { return execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'] }).trim(); }
+  catch { return null; }
+}
+
+/** The repository file now: whether it exists, its body hash, its title and when it last changed. */
+function repoInfo(root, rel) {
+  if (!D.okPath(rel)) return { exists: false };
+  const full = path.join(root, rel);
+  let text;
+  try { text = fs.readFileSync(full, 'utf8'); } catch { return { exists: false }; }
+  // The last commit time, unless the file has changes not yet committed: then its own file time is the truth.
+  // Who: the last commit's author, or "You" when that is this repository's git user or the change is not committed yet.
+  let modified_at = null;
+  let modified_by = null;
+  const dirty = git(root, ['status', '--porcelain', '--', rel]);
+  if (!dirty) {
+    const c = git(root, ['log', '-1', '--format=%cI%x09%an', '--', rel]);
+    if (c) {
+      const [when, who] = c.split('\t');
+      modified_at = new Date(when).toISOString();
+      const me = git(root, ['config', 'user.name']);
+      modified_by = who && me && who === me ? 'You' : (who || null);
+    }
+  }
+  if (!modified_at) {
+    try { modified_at = fs.statSync(full).mtime.toISOString(); modified_by = 'You'; } catch { /* none */ }
+  }
+  return { exists: true, hash: bodyHash(text), title: titleOf(text, rel), modified_at, modified_by };
+}
+
+function readRows(root) {
+  const s = stateDir(root);
+  if (!s.ok) return { ok: false, error: s.error, rows: [] };
+  const r = fourPanel.readDeclarations(s.dir, LEDGER);
+  return { ...r, dir: s.dir };
+}
+function append(root, row) {
+  const c = D.checkRow(row);
+  if (!c.ok) return { ok: false, error: c.error };
+  const s = stateDir(root);
+  if (!s.ok) return { ok: false, error: s.error };
+  return fourPanel.appendDeclaration(s.dir, LEDGER, c.row);
+}
+
+/** The links the signal is about: the PM's artifact links to Google Docs and Confluence, latest row per pair. */
+function links(root) {
+  const s = stateDir(root);
+  if (!s.ok) return { ok: false, error: s.error, links: [] };
+  const r = fourPanel.readDeclarations(s.dir, fourPanel.ARTIFACT_LINKS);
+  if (!r.ok) return { ok: false, error: r.error, links: [] };
+  return { ok: true, links: fourPanel.linkView(r.rows).filter((l) => D.KINDS.includes(l.kind) && D.okPath(l.artifact_path)) };
+}
+
+function view(root, { now = Date.now() } = {}) {
+  const L = links(root);
+  if (!L.ok) return { ok: false, error: L.error };
+  const rows = readRows(root);
+  if (!rows.ok) return { ok: false, error: rows.error };
+  const readings = D.readingsByLink(rows.rows);
+  const { open, last, syncs } = D.runsOf(rows.rows);
+  const byPath = new Map();
+  for (const l of L.links) {
+    let doc = byPath.get(l.artifact_path);
+    if (!doc) {
+      const repo = repoInfo(root, l.artifact_path);
+      doc = { path: l.artifact_path, title: repo.title || path.basename(l.artifact_path), initiative_id: l.initiative_id || null,
+        repo: { exists: !!repo.exists, modified_at: repo.modified_at || null, modified_by: repo.modified_by || null }, links: [], _repo: repo };
+      byPath.set(l.artifact_path, doc);
+    }
+    const mine = readings.get(D.keyOf(l.artifact_path, l.kind)) || [];
+    const sig = D.signal({ kind: l.kind, target: l.target }, mine, doc._repo);
+    const st = syncState(syncs, l.artifact_path, l.kind, mine, now);
+    doc.links.push({ ...sig, target: l.target, linked_at: l.at, ...st });
+  }
+  const docs = [...byPath.values()].map(({ _repo, ...d }) => ({
+    ...d, attention: d.links.some((x) => D.ATTENTION.includes(x.signal)),
+  }));
+  const all = docs.flatMap((d) => d.links);
+  const count = (s) => all.filter((x) => x.signal === s).length;
+  const summary = {
+    documents: docs.length, links: all.length,
+    same: count('same'), ahead: count('ahead'), behind: count('behind'), diverged: count('diverged'),
+    unchecked: count('unchecked'), problems: count('unreadable') + count('missing-remote') + count('missing-repo'),
+    attention: docs.filter((d) => d.attention).length,
+  };
+  return { ok: true, docs, summary, open: openRun(open), last, file: rows.file || null };
+}
+const openRun = (open, now = Date.now()) => (open && now - Date.parse(open.started_at) < OPEN_RUN_MS ? open : null);
+
+/** A copy's sync, as the line shows it: one still open (`syncing`), or the last one that failed after the last reading. */
+function syncState(syncs, rel, kind, readings, now = Date.now()) {
+  const mine = (syncs || []).filter((x) => x.path === rel && x.kind === kind);
+  const open = mine.filter((x) => x.state === 'started' && now - Date.parse(x.started_at) < OPEN_SYNC_MS).pop() || null;
+  const lastAt = readings.length ? readings[readings.length - 1].at : '';
+  const failed = mine.filter((x) => x.state === 'failed' && x.ended_at > lastAt).pop() || null;
+  return {
+    syncing: open ? { run: open.run, use: open.use, started_at: open.started_at } : null,
+    sync_failed: !open && failed ? { use: failed.use, reason: failed.reason, at: failed.ended_at } : null,
+  };
+}
+
+function addLink(root, { path: rel, kind, target, initiative_id } = {}) {
+  if (!D.KINDS.includes(kind)) return { ok: false, error: `choose ${D.KINDS.map((k) => D.KIND_LABEL[k]).join(' or ')}` };
+  if (!D.okPath(rel)) return { ok: false, error: 'give the file as a path inside the repository' };
+  if (!fs.existsSync(path.join(root, rel))) return { ok: false, error: `${rel} is not in the repository` };
+  if (!D.remoteIdOf(kind, target)) return { ok: false, error: `that is not a ${D.KIND_LABEL[kind]} link — paste the page's address` };
+  const built = fourPanel.artifactLinkRow({ artifact_path: rel, kind, target, origin: 'typed', initiative_id: initiative_id || null });
+  if (!built.ok) return built;
+  const s = stateDir(root);
+  if (!s.ok) return s;
+  return fourPanel.appendDeclaration(s.dir, fourPanel.ARTIFACT_LINKS, built.row);
+}
+
+function removeLink(root, { path: rel, kind } = {}) {
+  const L = links(root);
+  if (!L.ok) return L;
+  const cur = L.links.find((l) => l.artifact_path === rel && l.kind === kind);
+  if (!cur) return { ok: false, error: `${rel} has no ${D.KIND_LABEL[kind] || kind} link` };
+  const built = fourPanel.artifactLinkRow({ artifact_path: rel, kind, target: cur.target, origin: 'typed', state: 'retracted',
+    initiative_id: cur.initiative_id || null });
+  if (!built.ok) return built;
+  const s = stateDir(root);
+  if (!s.ok) return s;
+  return fourPanel.appendDeclaration(s.dir, fourPanel.ARTIFACT_LINKS, built.row);
+}
+
+function newRunId() { return 'r-' + crypto.randomBytes(6).toString('hex'); }
+
+/** Open a check. Refused while another is open (and not stale). Returns every link with what the session needs. */
+function checkStart(root, { by, now = new Date() } = {}) {
+  if (!by) return { ok: false, error: 'a check must name the session or profile that runs it' };
+  const rows = readRows(root);
+  if (!rows.ok) return rows;
+  const open = openRun(D.runsOf(rows.rows).open, now.getTime());
+  if (open) return { ok: false, error: `a check is already running (${open.run}, started ${open.started_at})`, open };
+  const L = links(root);
+  if (!L.ok) return L;
+  const run = newRunId();
+  const wrote = append(root, { ev: 'run', run, state: 'started', by, at: now.toISOString() });
+  if (!wrote.ok) return wrote;
+  const list = L.links.map((l) => {
+    const repo = repoInfo(root, l.artifact_path);
+    return { path: l.artifact_path, kind: l.kind, target: l.target, remote_id: D.remoteIdOf(l.kind, l.target),
+      repo_exists: !!repo.exists, repo_hash: repo.hash || null, title: repo.title || null };
+  });
+  return { ok: true, run, links: list };
+}
+
+/** Record what the session read. Each reading is checked on its own; a refused one is reported and not written. */
+function record(root, { run, by, readings, now = new Date() } = {}) {
+  if (!Array.isArray(readings)) return { ok: false, error: 'readings is a list' };
+  const rows = readRows(root);
+  if (!rows.ok) return rows;
+  const known = D.runsOf(rows.rows).runs.find((r) => r.run === run);
+  if (!known) return { ok: false, error: `${run || 'that'} is not a check that was started — run pmos docs check-start first` };
+  if (known.finished_at) return { ok: false, error: `${run} is finished — start a new check` };
+  const recorded = []; const refused = [];
+  for (const r of readings) {
+    const wrote = append(root, { ...r, ev: 'reading', run, by, at: now.toISOString() });
+    if (wrote.ok) recorded.push(`${r.path}|${r.kind}`); else refused.push({ path: r && r.path, kind: r && r.kind, error: wrote.error });
+  }
+  return { ok: refused.length === 0, recorded, refused, error: refused.length ? `${refused.length} reading(s) refused` : undefined };
+}
+
+function checkFinish(root, { run, by, summary, now = new Date() } = {}) {
+  const rows = readRows(root);
+  if (!rows.ok) return rows;
+  const known = D.runsOf(rows.rows).runs.find((r) => r.run === run);
+  if (!known) return { ok: false, error: `${run || 'that'} is not a check that was started` };
+  if (known.finished_at) return { ok: true, already: true };
+  return append(root, { ev: 'run', run, state: 'finished', by, summary: summary || null, at: now.toISOString() });
+}
+
+/** Open a sync of one copy, in the direction the PM pressed. Refused while another sync of that copy is open. */
+function syncStart(root, { path: rel, kind, use, by, now = new Date() } = {}) {
+  if (!by) return { ok: false, error: 'a sync must name the session or profile that runs it' };
+  if (!D.USES.includes(use)) return { ok: false, error: 'say which version to use: pmos or copy' };
+  const L = links(root);
+  if (!L.ok) return L;
+  const l = L.links.find((x) => x.artifact_path === rel && x.kind === kind);
+  if (!l) return { ok: false, error: `${rel} has no ${D.KIND_LABEL[kind] || kind} copy` };
+  const rows = readRows(root);
+  if (!rows.ok) return rows;
+  const st = syncState(D.runsOf(rows.rows).syncs, rel, kind, [], now.getTime());
+  if (st.syncing) return { ok: false, error: `that copy is already being synced (${st.syncing.run}, started ${st.syncing.started_at})`, open: st.syncing };
+  const repo = repoInfo(root, rel);
+  if (!repo.exists) return { ok: false, error: `${rel} is not in the repository` };
+  const run = newRunId();
+  const wrote = append(root, { ev: 'run', mode: 'sync', run, state: 'started', by, path: rel, kind, use, at: now.toISOString() });
+  if (!wrote.ok) return wrote;
+  return { ok: true, run, path: rel, kind, label: D.KIND_LABEL[kind], use, target: l.target, remote_id: D.remoteIdOf(kind, l.target),
+    repo_hash: repo.hash, title: repo.title };
+}
+
+function openSync(root, run) {
+  const rows = readRows(root);
+  if (!rows.ok) return rows;
+  const s = D.runsOf(rows.rows).syncs.find((x) => x.run === run);
+  if (!s) return { ok: false, error: `${run || 'that'} is not a sync that was started — run pmos docs sync-start first` };
+  if (s.state !== 'started') return { ok: false, error: `${run} is already ${s.state}` };
+  return { ok: true, sync: s };
+}
+
+/**
+ * Close a sync that wrote one side. The session names the copy's version after the write; the repository hash is read
+ * here, now, so the reading says what is on disk and not what the session thinks it wrote.
+ */
+function syncFinish(root, { run, by, version, modified_at, modified_by, url, title, now = new Date() } = {}) {
+  const o = openSync(root, run);
+  if (!o.ok) return o;
+  const s = o.sync;
+  const repo = repoInfo(root, s.path);
+  if (!repo.exists) return { ok: false, error: `${s.path} is not in the repository — record the sync as failed` };
+  const label = D.KIND_LABEL[s.kind];
+  const reading = { ev: 'reading', run, by, at: now.toISOString(), path: s.path, kind: s.kind,
+    remote_id: null, exists: true, version: version == null ? null : String(version), same: true, repo_hash: repo.hash,
+    modified_at: modified_at || null, modified_by: modified_by || null, url: url || null, title: title || null,
+    note: s.use === 'pmos' ? `PMOS version written to ${label}` : `${label} version written to PMOS` };
+  const L = links(root);
+  const l = L.ok ? L.links.find((x) => x.artifact_path === s.path && x.kind === s.kind) : null;
+  if (l) reading.remote_id = D.remoteIdOf(s.kind, l.target);
+  const r = append(root, reading);
+  if (!r.ok) return r;
+  return append(root, { ev: 'run', mode: 'sync', run, state: 'finished', by, path: s.path, kind: s.kind, use: s.use, at: now.toISOString() });
+}
+
+function syncFail(root, { run, by, reason, now = new Date() } = {}) {
+  const o = openSync(root, run);
+  if (!o.ok) return o;
+  const s = o.sync;
+  return append(root, { ev: 'run', mode: 'sync', run, state: 'failed', by, path: s.path, kind: s.kind, use: s.use,
+    summary: reason || null, at: now.toISOString() });
+}
+
+/** The repository's markdown files whose path or title matches `q`: what search and Add copy offer. */
+function findFiles(root, q, { limit = 20 } = {}) {
+  const words = String(q || '').toLowerCase().split(/\s+/).filter(Boolean);
+  const out = git(root, ['ls-files', '-co', '--exclude-standard', '--', '*.md']);
+  const files = (out ? out.split('\n') : []).filter((f) => f && D.okPath(f) && !/(^|\/)node_modules\//.test(f));
+  const found = [];
+  for (const f of files) {
+    if (found.length >= limit) break;
+    const low = f.toLowerCase();
+    let title = null;
+    const hit = (t) => words.every((w) => t.includes(w));
+    if (!words.length || hit(low)) { found.push(f); continue; }
+    try { title = titleOf(fs.readFileSync(path.join(root, f), 'utf8').slice(0, 4000), f); } catch { continue; }
+    if (hit(title.toLowerCase())) found.push(f);
+  }
+  return found.map((f) => {
+    let title = path.basename(f);
+    try { title = titleOf(fs.readFileSync(path.join(root, f), 'utf8').slice(0, 4000), f); } catch { /* keep the name */ }
+    return { path: f, title };
+  });
+}
+
+module.exports = { LEDGER, OPEN_RUN_MS, OPEN_SYNC_MS, syncStart, syncFinish, syncFail, findFiles, view, addLink, removeLink, checkStart, record, checkFinish, repoInfo, bodyHash, bodyOf, titleOf, links };

package/workspace/lib/doc-sync.js

@@ -0,0 +1,225 @@
+'use strict';
+/* doc-sync.js — the sync SIGNAL for documents linked to Google Docs and Confluence (initiative docs-three-way-sync).
+ *
+ * The PM asked for no automatic sync: "I want signal if synced file on pmos is obsolete or ahead or same as the one of
+ * other services." So this module decides one word per link — same, ahead, behind, diverged — and never a write.
+ *
+ * PURE: no require, no file, no network, no clock. lib/doc-sync-store.js reads the links, the readings and the
+ * repository files and passes them in.
+ *
+ *   checkRow(row)                          → { ok:true, row } | { ok:false, error }   the gate every ledger line passes
+ *   readingsByLink(rows)                   → Map "<path>|<kind>" → readings, oldest first (refused lines skipped)
+ *   runsOf(rows)                           → { runs, open, last, syncs }   checks, and the syncs the PM pressed
+ *   signal(link, readings, repo)           → { signal, words, basis, checked_at, … }
+ *   remoteIdOf(kind, target)               → the Google Doc id or Confluence page id in a pasted link
+ *
+ * ── How a signal is decided ────────────────────────────────────────────────────────────────────────────────────
+ * A READING is what a check session saw for one link: whether the copy exists, its version and modified time, and
+ * whether its text is the same as the repository file's body, with the hash of that file at that moment.
+ * The BASELINE is the latest reading that found the text the same. Against it:
+ *   repo changed   = the file's hash now ≠ the baseline's hash
+ *   remote changed = the latest reading's version ≠ the baseline's version
+ *   neither → same · repo only → ahead · remote only → behind · both → diverged.
+ * With no baseline (the copies have never matched) the newer modified time decides and `basis` says 'date'.
+ *
+ * ── The rule this module carries forward ───────────────────────────────────────────────────────────────────────
+ * A reading cannot be asserted, only evidenced (four-panel.js, `resolved` and `applied`). A reading must name the
+ * session or profile that read, and the check it belongs to. `same: true` must carry the repository hash it was
+ * compared with. No signal but `unchecked` exists without a reading, and nothing here turns a clock into a claim about
+ * a copy.
+ *
+ * ── Sync on the PM's press (amended 2026-10-06) ────────────────────────────────────────────────────────────────
+ * The PM reviewed the mockup and asked to sync one copy at a time, in the direction they pick. A sync is a `run` row
+ * with `mode: 'sync'`, the link it is about and `use` (pmos: the repository text is written to the copy; copy: the
+ * copy's text is written to the repository file). It is started, then finished or failed. A finished sync writes a
+ * reading that says the two sides are the same, so the baseline moves to what was just written. This module still
+ * writes nothing: a session holding the PM's connectors does the write and records it through `pmos docs`.
+ */
+
+const KINDS = Object.freeze(['google', 'confluence']);
+const KIND_LABEL = Object.freeze({ google: 'Google Docs', confluence: 'Confluence' });
+const EVENTS = Object.freeze(['run', 'reading']);
+const SIGNALS = Object.freeze(['same', 'ahead', 'behind', 'diverged', 'unchecked', 'unreadable', 'missing-remote', 'missing-repo']);
+// What needs the PM's eye: everything but `same`. `unchecked` is included — a copy nobody read is not known to match.
+const ATTENTION = Object.freeze(SIGNALS.filter((s) => s !== 'same'));
+const RUN_ID = /^r-[0-9a-z]{6,32}$/;
+const USES = Object.freeze(['pmos', 'copy']);
+const HASH = /^[0-9a-f]{16,64}$/;
+
+const str = (v, n = 300) => (v == null || v === '' ? null : String(v).slice(0, n));
+const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
+const keyOf = (p, kind) => `${p}|${kind}`;
+
+/** A repository path a link may name: relative, inside the repository. */
+function okPath(p) {
+  if (typeof p !== 'string' || !p || p.length > 300) return false;
+  return !(p.startsWith('/') || p.includes('\\') || p.split('/').some((s) => s === '..' || s === '.' || s === ''));
+}
+
+/** The id inside a pasted link, so the same copy pasted in two shapes is one copy. */
+function remoteIdOf(kind, target) {
+  const t = String(target || '').trim();
+  if (!t) return null;
+  if (kind === 'google') {
+    const m = /\/d\/([A-Za-z0-9_-]{10,})/.exec(t) || /[?&]id=([A-Za-z0-9_-]{10,})/.exec(t);
+    if (m) return m[1];
+    return /^[A-Za-z0-9_-]{10,}$/.test(t) ? t : null;
+  }
+  if (kind === 'confluence') {
+    const m = /\/pages\/(?:edit-v2\/)?(\d+)/.exec(t) || /[?&]pageId=(\d+)/.exec(t);
+    if (m) return m[1];
+    return /^\d+$/.test(t) ? t : null;
+  }
+  return null;
+}
+
+/** The one gate every ledger line passes. A refused row is never written, and the readers skip it. */
+function checkRow(input) {
+  if (!isObj(input)) return { ok: false, error: 'a ledger row is an object' };
+  const ev = String(input.ev || '');
+  if (!EVENTS.includes(ev)) return { ok: false, error: `ev must be one of: ${EVENTS.join(', ')}` };
+  const at = str(input.at, 40);
+  if (!at || Number.isNaN(Date.parse(at))) return { ok: false, error: 'at must be an ISO time' };
+  if (!RUN_ID.test(String(input.run || ''))) return { ok: false, error: 'run must name a check (r-…)' };
+  const by = str(input.by, 120);
+  if (!by) return { ok: false, error: `a ${ev === 'run' ? 'check' : 'reading'} must name the session or profile that made it — PMOS read nothing itself` };
+
+  if (ev === 'run') {
+    if (input.mode === 'sync') {
+      if (!['started', 'finished', 'failed'].includes(input.state)) return { ok: false, error: 'a sync state is started, finished or failed' };
+      if (!okPath(input.path)) return { ok: false, error: 'a sync names the repository file it is about' };
+      if (!KINDS.includes(input.kind)) return { ok: false, error: `a sync names its copy: ${KINDS.join(' or ')}` };
+      if (!USES.includes(input.use)) return { ok: false, error: 'a sync says which version it uses: pmos or copy' };
+      const summary = str(input.summary, 400);
+      if (input.state === 'failed' && !summary) return { ok: false, error: 'a failed sync says why' };
+      return { ok: true, row: { ev, at, run: input.run, mode: 'sync', state: input.state, by, path: input.path, kind: input.kind, use: input.use, summary } };
+    }
+    if (!['started', 'finished'].includes(input.state)) return { ok: false, error: 'state must be started or finished' };
+    return { ok: true, row: { ev, at, run: input.run, state: input.state, by, summary: str(input.summary, 400) } };
+  }
+
+  if (!okPath(input.path)) return { ok: false, error: 'path must be a repository-relative path' };
+  if (!KINDS.includes(input.kind)) return { ok: false, error: `kind must be one of: ${KINDS.join(', ')}` };
+  const error = str(input.error, 300);
+  if (!error && typeof input.exists !== 'boolean') return { ok: false, error: 'a reading says exists: true or false, or carries the error' };
+  const exists = error ? null : input.exists;
+  const version = str(input.version, 120);
+  if (exists === true && !version) return { ok: false, error: 'a reading of a copy that exists must carry its version' };
+  let same = null;
+  if (exists === true && input.same != null) {
+    if (typeof input.same !== 'boolean') return { ok: false, error: 'same is true or false' };
+    same = input.same;
+  }
+  const repo_hash = input.repo_hash == null || input.repo_hash === '' ? null : String(input.repo_hash);
+  if (repo_hash && !HASH.test(repo_hash)) return { ok: false, error: 'repo_hash is the hash `pmos docs check-start` gave for the file' };
+  if (same === true && !repo_hash) return { ok: false, error: 'a reading that says the text is the same must carry the repository hash it was compared with' };
+  const modified_at = str(input.modified_at, 40);
+  if (modified_at && Number.isNaN(Date.parse(modified_at))) return { ok: false, error: 'modified_at must be an ISO time' };
+  return {
+    ok: true,
+    row: {
+      ev, at, run: input.run, by, path: input.path, kind: input.kind,
+      remote_id: str(input.remote_id, 200), exists, version, modified_at, same, repo_hash,
+      title: str(input.title, 300), url: str(input.url, 400), error, note: str(input.note, 300),
+      modified_by: str(input.modified_by, 120),
+    },
+  };
+}
+
+/** The readings of every link, oldest first. A line that fails checkRow is skipped, never guessed. */
+function readingsByLink(rows) {
+  const by = new Map();
+  for (const raw of Array.isArray(rows) ? rows : []) {
+    const c = checkRow(raw);
+    if (!c.ok || c.row.ev !== 'reading') continue;
+    const k = keyOf(c.row.path, c.row.kind);
+    if (!by.has(k)) by.set(k, []);
+    by.get(k).push(c.row);
+  }
+  return by;
+}
+
+/** Every check, the one still open (started, not finished), the last one that finished, and every sync. */
+function runsOf(rows) {
+  const runs = new Map();
+  const syncs = new Map();
+  for (const raw of Array.isArray(rows) ? rows : []) {
+    const c = checkRow(raw);
+    if (!c.ok || c.row.ev !== 'run') continue;
+    const r = c.row;
+    if (r.mode === 'sync') {
+      const cur = syncs.get(r.run) || { run: r.run, by: r.by, path: r.path, kind: r.kind, use: r.use, state: 'started', started_at: null, ended_at: null, reason: null };
+      if (r.state === 'started') cur.started_at = cur.started_at || r.at;
+      else if (!cur.ended_at) { cur.state = r.state; cur.ended_at = r.at; cur.reason = r.state === 'failed' ? r.summary : null; }
+      syncs.set(r.run, cur);
+      continue;
+    }
+    const cur = runs.get(r.run) || { run: r.run, by: r.by, started_at: null, finished_at: null, summary: null };
+    if (r.state === 'started') cur.started_at = cur.started_at || r.at;
+    else { cur.finished_at = r.at; cur.summary = r.summary; }
+    runs.set(r.run, cur);
+  }
+  const list = [...runs.values()];
+  return {
+    runs: list,
+    open: list.filter((r) => r.started_at && !r.finished_at).pop() || null,
+    last: list.filter((r) => r.finished_at).pop() || null,
+    syncs: [...syncs.values()].filter((x) => x.started_at),
+  };
+}
+
+/**
+ * The signal for one link. `link` = { artifact_path, kind, target }. `readings` = this link's readings, oldest first.
+ * `repo` = { exists, hash, modified_at } for the repository file now. A reading of a different copy (the PM changed
+ * the link since) does not count: it read something this link no longer names.
+ */
+function signal(link, readings, repo) {
+  const kind = link.kind;
+  const label = KIND_LABEL[kind] || kind;
+  const rid = remoteIdOf(kind, link.target);
+  const mine = (Array.isArray(readings) ? readings : []).filter((r) => !rid || !r.remote_id || r.remote_id === rid);
+  const last = mine[mine.length - 1] || null;
+  const base = [...mine].reverse().find((r) => r.exists === true && r.same === true) || null;
+  const out = (sig, words, extra = {}) => ({
+    signal: sig, words, basis: null, kind, label,
+    checked_at: last ? last.at : null, checked_by: last ? last.by : null,
+    title: last && last.title ? last.title : null,
+    url: (last && last.url) || (/^https?:\/\//i.test(String(link.target || '')) ? link.target : null),
+    note: last && last.note ? last.note : null,
+    remote_modified_at: last && last.modified_at ? last.modified_at : null,
+    remote_modified_by: last && last.modified_by ? last.modified_by : null, ...extra,
+  });
+  const r = repo || { exists: false };
+
+  if (!r.exists) return out('missing-repo', 'Not in the repo');
+  if (!last) return out('unchecked', 'Not checked yet');
+  if (last.error) return out('unreadable', `Could not check — ${last.error}`);
+  if (last.exists === false) return out('missing-remote', `Not found in ${label}`);
+
+  // The latest reading compared the text and found it different, with nothing changed since the baseline it would
+  // otherwise use: that baseline was wrong, so it is not used.
+  const stale = base && last !== base && last.same === false && last.version === base.version && last.repo_hash === base.repo_hash;
+  if (base && !stale) {
+    const repoChanged = base.repo_hash !== r.hash;
+    const remoteChanged = last.version !== base.version;
+    if (!repoChanged && !remoteChanged) return out('same', 'Same', { basis: 'text' });
+    if (repoChanged && !remoteChanged) return out('ahead', 'Ahead — the repo is newer', { basis: 'text' });
+    if (!repoChanged && remoteChanged) return out('behind', `Behind — ${label} is newer`, { basis: 'text' });
+    return out('diverged', 'Edited in both', { basis: 'text' });
+  }
+
+  // Never matched. The text differs (or was not compared): the newer side by modified time, and the row says so.
+  const remoteAt = Date.parse(last.modified_at || '');
+  const repoAt = Date.parse(r.modified_at || '');
+  if (Number.isNaN(remoteAt) || Number.isNaN(repoAt)) {
+    return out('diverged', 'Different, and no date says which is newer', { basis: 'date' });
+  }
+  return remoteAt > repoAt
+    ? out('behind', `Behind — ${label} is newer (by date)`, { basis: 'date' })
+    : out('ahead', 'Ahead — the repo is newer (by date)', { basis: 'date' });
+}
+
+module.exports = {
+  KINDS, KIND_LABEL, EVENTS, SIGNALS, ATTENTION, RUN_ID, USES,
+  checkRow, readingsByLink, runsOf, signal, remoteIdOf, okPath, keyOf,
+};