@augurworks/augur 0.15.1

package/scripts/lib/publish-compose.mjs

@@ -0,0 +1,12 @@
+// Moved to src/publish-compose.mjs, re-exported here so no CLI import had to change.
+//
+// ⚠️ IT MOVED BECAUSE THE WORKER RUNS IT. `C-fork-on-conflict` resolves a stale base inside
+// the commit handler using the SAME composition the CLI uses — two implementations of "who
+// keeps the URL" would disagree on exactly the publishes a conflict is about. `src/` is what
+// the deploy copies beside `_worker.js`; a module the worker imports from `scripts/` resolves
+// nowhere at the edge, and the build's derived copy list would have to reach outside `src/`
+// to fix it. See the header of src/publish-compose.mjs for the composition rules themselves.
+export { composePublish, filterLitter, forkLanded, LITTER_RE } from "../../src/publish-compose.mjs";
+// The unit vocabulary rode along here before the move (compose re-exported what it imported),
+// and CLI modules import it from this path. Kept, pointing at its one definition.
+export { authoredUnits, unitOfPath, unitPaths } from "../../src/publish-units.mjs";

package/scripts/lib/publish-conflict.mjs

@@ -0,0 +1,78 @@
+// Build-decoration tolerance + the repo-dir mapping — pure, shared by the publish stack.
+//
+// ⚠️ THE UNIT VOCABULARY MOVED TO src/publish-units.mjs and is re-exported below, so no CLI
+// import had to change. It moved because the SERVER needs it: `C-fork-on-conflict` resolves
+// a stale base inside the commit handler, and two definitions of "which folder does this
+// path belong to" would disagree on exactly the paths a conflict is about.
+//
+// A unit is a prototype/playground folder — the thing a URL names and a person edits, never
+// a lone file — and units are exactly the routing fragment's publicPrefixes (galleries get
+// versionMap entries but no prefix, which is what keeps them out). Since protocol 5 the
+// per-unit decisions live in publish-compose.mjs; what remains here is the repo-dir mapping
+// and the two views of what the build decorates authored HTML with:
+// stripVolatileHead (a COMPARATOR: does this content really differ?) and
+// stripBuildDecorations (a TRANSFORMER: undo the decoration exactly — kept for
+// repo-debake tooling, e.g. peeling dist-flavored bytes out of a space repo).
+
+export { authoredUnits, unitOfPath, unitPaths } from "../../src/publish-units.mjs";
+const dec = (s) => { try { return decodeURIComponent(String(s)); } catch (e) { return String(s); } };
+
+// A unit URL back to the repo folder(s) it could live in, best guess first:
+// prototypes elide the /prototypes/ segment on the URL side, playground does not,
+// and a non-default space carries its base as the first segment.
+export function repoDirCandidates(unit, { spaceBase = "" } = {}) {
+  let u = dec(unit);
+  const base = dec(spaceBase || "");
+  if (base && (u === base + "/" || u.startsWith(base + "/"))) u = u.slice(base.length);
+  const segs = u.replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
+  if (!segs.length) return [];
+  if (segs[0] === "playground" || segs.length !== 2) return [segs.join("/")];
+  return [`${segs[0]}/prototypes/${segs[1]}`, segs.join("/")];
+}
+
+// The build decorates authored HTML on its way to dist: marker-delimited chrome
+// (the review overlay, the pet layer, offline reload) plus og/twitter meta.
+// stripInjectedChrome removes exactly the marker blocks — used when writing live
+// bytes back into a tree, so adopted sources stay close to what their author
+// wrote (og meta stays: the injector skips pages that already carry it, so it is
+// stable across rebuilds).
+export function stripInjectedChrome(html) {
+  return String(html).replace(/<!--gv-([a-z0-9-]+)-start-->[\s\S]*?<!--gv-\1-end-->/g, "");
+}
+
+// Tolerant equality for "did the content really change": a live blob and a git
+// source must compare equal when they differ only by injected chrome, social
+// meta (og:url legitimately varies with the configured origin), the linked-assets
+// stamp, the skills-path depth rewrite (dist mounts prototypes one level shallower
+// than the repo), and the whitespace those injections leave behind. Every one of
+// these leaked through this comparator on 2026-08-19 and a reconcile then adopted
+// 169 chrome-baked pages into a space repo as one collaborator's authorship.
+// A comparator, not a transformer.
+export function stripVolatileHead(html) {
+  return stripInjectedChrome(html)
+    .replace(/[ \t]*<meta\s+(?:property|name)="(?:og|twitter):[^"]*"\s+content="[^"]*"\s*\/?>[ \t]*/g, "")
+    .replace(/<script>window\.__GV_LINKED=\[[^\n]*?\];<\/script>/g, "")
+    // The build stamps the card emoji onto <title> (idempotently) — not an edit.
+    .replace(/(<title>)\s*(?:[\p{Extended_Pictographic}‍️]+\s*)+/gu, "$1")
+    // Depth is layout, not content: collapse any ../-run before skills/ so the
+    // repo form (../../../skills/…) and the dist form (../../skills/…) compare equal.
+    .replace(/(?:\.\.\/)+skills\//g, "skills/")
+    .replace(/\s+/g, " ").replace(/>\s+</g, "><").trim();
+}
+
+// The WRITER'S peel — everything the build decorates authored HTML with on its way
+// to dist, undone, so an adopted source is byte-shaped like what its author wrote:
+// marker chrome out, og/twitter meta out (the build re-derives it), the linked-assets
+// stamp out, the title emoji off, and the skills-path depth rewrite reversed for the
+// file's REPO location (`relDir`, the file's directory relative to the space root).
+// Without the full peel, an adopt writes dist bytes into git — pages whose relative
+// asset paths no longer resolve in the repo layout, plus baked meta that reads as an
+// edit forever after. A transformer, not a comparator: depth must come out exact.
+export function stripBuildDecorations(html, relDir) {
+  const up = "../".repeat(String(relDir || "").split("/").filter(Boolean).length);
+  return stripInjectedChrome(String(html))
+    .replace(/[ \t]*<meta\s+(?:property|name)="(?:og|twitter):[^"]*"\s+content="[^"]*"\s*\/?>\s*\n?/g, "")
+    .replace(/[ \t]*<script>window\.__GV_LINKED=\[[^\n]*?\];<\/script>\s*\n?/g, "")
+    .replace(/(<title>)\s*(?:[\p{Extended_Pictographic}‍️]+\s*)+/gu, "$1")
+    .replace(/(?:\.\.\/)+skills\//g, up + "skills/");
+}

package/scripts/lib/publish-evidence.mjs

@@ -0,0 +1,144 @@
+// Git evidence for composed publish (protocol 5) — the impure half.
+//
+// composePublish (publish-compose.mjs) is pure; this module answers its three
+// questions from the one source of truth we trust: git.
+//
+//   ffUnits       which units are a FAST-FORWARD of live — live's recorded unit
+//                 source is a clean commit in this tree's history, so shipping my
+//                 build cannot revert anyone (their content is already mine).
+//   editedUnits   which units I have local evidence of editing: uncommitted paths
+//                 (porcelain, untracked included) plus — when live's base is a
+//                 provable ancestor — commits since that base. When the base is
+//                 unknowable the answer degrades to porcelain only: fail CLOSED
+//                 (my committed edit stays local with a note) rather than sprawl.
+//   deletedUnits  live units provably deleted here: the folder existed at live's
+//                 base, the base is my ancestor, and the folder is gone from the
+//                 tree. Anything less keeps live's URLs up.
+//
+// Per-unit live provenance comes from routing.unitSources (written by every
+// protocol-5 publish), falling back to the space-level manifest source for
+// manifests that predate the field.
+//
+//   seed units    a live unit the PLATFORM wrote (provenance `isSeedSource`: the
+//                 seed pack a fresh workspace arrives with) is nobody's work. Its
+//                 recorded sha is an ENGINE commit no space repo has in its history,
+//                 so to git it looks exactly like an unpushed stranger's commit — and
+//                 a person's first edit to a start-here page was filed "unprovable"
+//                 and quietly stayed local. It is NOT unprovable: the platform's
+//                 provenance is a provenance. This module only declines to call it
+//                 one; WHETHER IT YIELDS IS THE COMPOSER'S RULE (publish-compose.mjs),
+//                 so the store, which runs the same composer with its own evidence,
+//                 reaches the same verdict for a repo-less publisher.
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { authoredUnits, unitPaths } from "./publish-compose.mjs";
+import { repoDirCandidates } from "./publish-conflict.mjs";
+import { isSeedSource } from "../../src/provenance.mjs";
+
+const dec = (s) => { try { return decodeURIComponent(String(s)); } catch (e) { return String(s); } };
+
+const gitq = (dir, ...a) => {
+  try {
+    return execFileSync("git", ["-C", dir, ...a], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch (e) { return null; }
+};
+
+export const isAncestor = (dir, sha) =>
+  !!sha && gitq(dir, "merge-base", "--is-ancestor", sha, "HEAD") !== null;
+const haveCommit = (dir, sha) => !!sha && gitq(dir, "cat-file", "-e", `${sha}^{commit}`) !== null;
+
+// Repo path → the unit URL it belongs to (the inverse of the build's URL scheme:
+// prototypes elide /prototypes/ on the URL side, playground does not).
+export function unitOfRepoPath(repoPath, spaceBase = "") {
+  const m = /^([^/]+)\/prototypes\/([^/]+)\//.exec(repoPath)
+    || /^(playground)\/([^/]+)\//.exec(repoPath);
+  if (!m) return null;
+  const enc = encodeURIComponent;
+  return m[1] === "playground"
+    ? `${spaceBase}/playground/${enc(m[2])}/`
+    : `${spaceBase}/${enc(m[1])}/${enc(m[2])}/`;
+}
+
+export function unitRepoDir(unit, spaceBase, sourceDir) {
+  const candidates = repoDirCandidates(unit, { spaceBase });
+  for (const c of candidates) if (existsSync(path.join(sourceDir, c))) return c;
+  return candidates[0];
+}
+
+const porcelainPaths = (dir) => (gitq(dir, "status", "--porcelain") || "").split("\n")
+  .filter(Boolean)
+  .map((l) => l.slice(3).replace(/^"|"$/g, ""))
+  .flatMap((p) => p.split(" -> ")); // renames evidence both sides
+
+export function collectEvidence({ sourceDir, spaceBase, mine, live }) {
+  const liveUnits = authoredUnits(live);
+  const mineUnits = authoredUnits(mine);
+  const unitSources = ((live || {}).routing || {}).unitSources || {};
+  const spaceSrc = (live || {}).source || {};
+  const srcOf = (u) => unitSources[u]
+    || { sha: spaceSrc.sha || null, dirty: !!spaceSrc.dirty, actor: spaceSrc.actor, seed: spaceSrc.seed };
+
+  const editedUnits = new Set();
+  const dirtyUnits = new Set();
+  const editedPaths = new Set();
+  const unprovable = []; // committed-looking divergence we refused to ship — for one honest log line
+
+  for (const rel of porcelainPaths(sourceDir)) {
+    const u = unitOfRepoPath(rel, spaceBase);
+    if (u) { editedUnits.add(u); dirtyUnits.add(u); }
+    if (!spaceBase && rel.startsWith("skills/")) editedPaths.add("/" + rel);
+  }
+
+  const ffUnits = new Set();
+  const ancestorCache = new Map();
+  const provenAncestor = (sha) => {
+    if (!sha) return false;
+    if (!ancestorCache.has(sha)) ancestorCache.set(sha, haveCommit(sourceDir, sha) && isAncestor(sourceDir, sha));
+    return ancestorCache.get(sha);
+  };
+
+  for (const u of new Set([...liveUnits, ...mineUnits])) {
+    const src = srcOf(u);
+    if (!src.dirty && provenAncestor(src.sha)) {
+      ffUnits.add(u);
+      continue; // FF ships regardless; no need to weigh evidence
+    }
+    if (editedUnits.has(u)) continue; // porcelain already says edited
+    // Dirty-or-unknown live base: committed evidence only counts against a
+    // provable ancestor (diffing against an unrelated commit would count THEIR
+    // work as mine). Without one, a committed local edit stays local — noted.
+    if (src.sha && provenAncestor(src.sha)) {
+      const dirRel = unitRepoDir(u, spaceBase, sourceDir);
+      const names = (gitq(sourceDir, "diff", "--name-only", src.sha, "HEAD", "--", dirRel) || "").trim();
+      if (names) editedUnits.add(u);
+    } else if (mineUnits.has(u) && liveUnits.has(u) && !isSeedSource(src)) {
+      // The seed is excluded because its provenance is KNOWN — it is the platform's —
+      // and the composer decides what that means. Everything else here is a stranger's.
+      unprovable.push(u);
+    }
+  }
+
+  // Skill files: committed evidence against the space-level base when provable.
+  if (!spaceBase && spaceSrc.sha && !spaceSrc.dirty && provenAncestor(spaceSrc.sha)) {
+    for (const rel of (gitq(sourceDir, "diff", "--name-only", spaceSrc.sha, "HEAD", "--", "skills") || "").split("\n")) {
+      if (rel.trim()) editedPaths.add("/" + rel.trim());
+    }
+  }
+
+  // Deletions: only what git can prove — existed at a provable ancestor base,
+  // gone from the tree now.
+  const deletedUnits = new Set();
+  for (const u of liveUnits) {
+    if (mineUnits.has(u)) continue;
+    const src = srcOf(u);
+    if (!provenAncestor(src.sha)) continue;
+    const dirRel = unitRepoDir(u, spaceBase, sourceDir);
+    if (existsSync(path.join(sourceDir, dirRel))) continue;
+    const then = (gitq(sourceDir, "ls-tree", "-r", "--name-only", src.sha, "--", dirRel) || "").trim();
+    if (then) deletedUnits.add(u);
+  }
+
+  return { editedUnits, dirtyUnits, deletedUnits, editedPaths, ffUnits, unprovable };
+}

package/scripts/lib/refine-compare.mjs

@@ -0,0 +1,140 @@
+// refine-compare — the measurement the refine harness reports, and the only thing that
+// decides a component's verdict.
+//
+// THE RULE THIS FILE ENFORCES: no self-assessment. A verdict is `diffRatio <= threshold`
+// computed from two images, and nothing else. There is no argument, no field and no file
+// through which an agent's opinion of its own work reaches the answer — `verdict()` takes
+// pixels and a number. Anything that reads a stored verdict must re-derive it here (see
+// `refine-ledger.mjs`, which stores measurements and never a pass).
+//
+// THE METRIC. Per pixel, the YIQ-weighted colour distance — the same perceptual delta the
+// well-known browser-screenshot comparators use — against `pixelTolerance`; then the
+// fraction of pixels that exceed it, against `threshold`. Two numbers rather than one
+// because they catch different lies: a shifted padding moves a large NUMBER of pixels a
+// long way, and a wrong hue moves a large number of pixels a SHORT way. A single mean
+// delta hides both under a big flat background.
+//
+// IT IS DELIBERATELY NAIVE ABOUT ANTIALIASING, and that is a posture, not an oversight.
+// Antialiasing-aware comparators exist so that a golden PNG captured on one machine can
+// be compared against a render on another. This harness would rather not be in that
+// business at all: in `source`/`url` reference mode both sides are rendered by the same
+// browser in the same run, so text antialiasing is byte-identical and there is nothing to
+// forgive — and a comparator that forgives nothing is the sensitive one. The cost is
+// stated where it is paid: an `image` reference captured on another machine WILL produce
+// font-edge noise here, and `docs/canon-refine.md` says to keep the threshold for that
+// mode empirical rather than hopeful.
+
+import { decodePng, encodePng } from "./refine-png.mjs";
+
+// Largest possible squared YIQ distance between two 8-bit colours, used to normalise.
+const MAX_YIQ_DELTA = 35215;
+
+// THE TWO NUMBERS, AND WHY THESE ONES.
+//
+// `pixelTolerance` 0.02 puts the per-pixel cutoff at 35215 · 0.02² ≈ 14.1 squared YIQ
+// units. In plain terms that forgives a uniform grey shift of about five levels out of
+// 255 and catches six — tight, because in same-run mode two renders of the same thing are
+// bit-identical and there is nothing legitimate to forgive. The widely-used default of 0.1
+// was measured against this fixture and was too loose to be worth running: it puts the
+// cutoff at 352, which lets a twenty-level channel error through unremarked, and a wrong
+// hue is exactly a twenty-level channel error.
+//
+// `threshold` 0.02 lets 2% of a frame differ before the component fails. It is a fraction
+// of the FRAME, so it only means anything if the component fills the frame — a small
+// component photographed on a large empty page can be badly wrong in 1% of the pixels and
+// pass. Size each component's viewport to the component. `docs/canon-refine.md` repeats
+// this because it is the one way to get a green run that means nothing.
+export const DEFAULT_THRESHOLD = 0.02;       // ≤2% of the frame may differ
+export const DEFAULT_PIXEL_TOLERANCE = 0.02; // how far one pixel may move before it counts
+
+const y = (r, g, b) => r * 0.29889531 + g * 0.58662247 + b * 0.11448223;
+const i = (r, g, b) => r * 0.59597799 - g * 0.2741761 - b * 0.32180189;
+const q = (r, g, b) => r * 0.21147017 - g * 0.52261711 + b * 0.31114694;
+
+/** Composite an RGBA sample over white, because a screenshot's transparent pixels are what the page shows through. */
+function flatten(data, p) {
+  const a = data[p + 3] / 255;
+  return [
+    data[p] * a + 255 * (1 - a),
+    data[p + 1] * a + 255 * (1 - a),
+    data[p + 2] * a + 255 * (1 - a),
+  ];
+}
+
+/**
+ * Compare two decoded images.
+ *
+ * Returns `{width, height, pixels, diffPixels, diffRatio, maxDelta, meanDelta, diff}`
+ * where the deltas are normalised 0..1 and `diff` is an RGBA buffer marking every
+ * counted pixel — for a human to look at AFTER the fact, never for the verdict.
+ */
+export function compareImages(a, b, { pixelTolerance = DEFAULT_PIXEL_TOLERANCE, withDiff = false } = {}) {
+  if (a.width !== b.width || a.height !== b.height) {
+    return {
+      sizeMismatch: true,
+      width: a.width, height: a.height,
+      referenceSize: `${b.width}x${b.height}`, candidateSize: `${a.width}x${a.height}`,
+      pixels: 0, diffPixels: 0, diffRatio: 1, maxDelta: 1, meanDelta: 1, diff: null,
+    };
+  }
+  const pixels = a.width * a.height;
+  const cutoff = MAX_YIQ_DELTA * pixelTolerance * pixelTolerance;
+  const diff = withDiff ? Buffer.alloc(pixels * 4) : null;
+  let diffPixels = 0, maxDelta = 0, sumDelta = 0;
+
+  for (let p = 0; p < pixels; p++) {
+    const o = p * 4;
+    const [ar, ag, ab] = flatten(a.data, o);
+    const [br, bg, bb] = flatten(b.data, o);
+    const dy = y(ar, ag, ab) - y(br, bg, bb);
+    const di = i(ar, ag, ab) - i(br, bg, bb);
+    const dq = q(ar, ag, ab) - q(br, bg, bb);
+    const delta = 0.5053 * dy * dy + 0.299 * di * di + 0.1957 * dq * dq;
+    if (delta > maxDelta) maxDelta = delta;
+    sumDelta += delta;
+    const counted = delta > cutoff;
+    if (counted) diffPixels++;
+    if (diff) {
+      if (counted) { diff[o] = 255; diff[o + 1] = 0; diff[o + 2] = 200; diff[o + 3] = 255; }
+      else {
+        // Ghost the reference so the marks have somewhere to sit.
+        const grey = Math.round(255 - (255 - y(br, bg, bb)) * 0.15);
+        diff[o] = diff[o + 1] = diff[o + 2] = grey; diff[o + 3] = 255;
+      }
+    }
+  }
+  return {
+    sizeMismatch: false,
+    width: a.width, height: a.height, pixels, diffPixels,
+    diffRatio: diffPixels / pixels,
+    maxDelta: maxDelta / MAX_YIQ_DELTA,
+    meanDelta: sumDelta / pixels / MAX_YIQ_DELTA,
+    diff: diff ? { width: a.width, height: a.height, data: diff } : null,
+  };
+}
+
+/** Same, from PNG bytes. */
+export function comparePngs(candidateBuf, referenceBuf, opts) {
+  return compareImages(decodePng(candidateBuf), decodePng(referenceBuf), opts);
+}
+
+/**
+ * The verdict. Derived, never stored, never supplied.
+ *
+ * A measurement with no `diffRatio` is not a pass and not a fail — it is `incomplete`,
+ * so a ledger line that carries an opinion but no number can never be mistaken for work
+ * that was done.
+ */
+export function verdict(measurement, threshold = DEFAULT_THRESHOLD) {
+  if (!measurement || typeof measurement.diffRatio !== "number" || !Number.isFinite(measurement.diffRatio)) {
+    return { state: "incomplete", pass: false, reason: "no measurement" };
+  }
+  if (measurement.error) return { state: "error", pass: false, reason: measurement.error };
+  if (measurement.sizeMismatch) {
+    return { state: "fail", pass: false, reason: `size mismatch — reference ${measurement.referenceSize}, candidate ${measurement.candidateSize}` };
+  }
+  const pass = measurement.diffRatio <= threshold;
+  return { state: pass ? "pass" : "fail", pass, reason: pass ? "" : `${(measurement.diffRatio * 100).toFixed(2)}% of pixels differ (threshold ${(threshold * 100).toFixed(2)}%)` };
+}
+
+export { encodePng, decodePng };

package/scripts/lib/refine-ledger.mjs

@@ -0,0 +1,150 @@
+// refine-ledger — the record that makes a refine run resumable, and auditable.
+//
+// WHY APPEND-ONLY JSONL AND NOT A JSON FILE. A run over five hundred components is an
+// overnight run, and an overnight run gets killed: the laptop sleeps, the socket drops,
+// the agent's own process is stopped. Rewriting one JSON document after each component
+// means five hundred chances to be interrupted mid-write and lose the whole record; one
+// appended line per component means the worst a kill can cost is the line being written.
+// A torn final line is DISCARDED on read rather than crashing the next run, which is the
+// only sane reading of a file that a `kill -9` was allowed to end.
+//
+// WHAT A LINE HOLDS: a measurement and the digests of the two images it was measured
+// from. WHAT IT NEVER HOLDS: a verdict. Pass and fail are derived by
+// `refine-compare.mjs#verdict` every time the report is drawn, so a line edited to say
+// `"pass": true` changes nothing at all — the field is not read. That is the mechanical
+// form of "no self-assessment": there is no key an agent can write to make its own work
+// count as done, and `--audit` re-measures from the saved PNGs to catch a line whose
+// NUMBER was edited instead.
+//
+// RESUME IS BY CONTENT, NOT BY POSITION. A component is skipped only when the ledger
+// already holds a completed measurement for it whose candidate digest, reference digest
+// and settings fingerprint all still match. So a re-run after editing one component
+// re-verifies that one and skips the other four hundred and ninety-nine, and a re-run
+// after changing the threshold re-verifies everything, because the settings changed.
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { verdict } from "./refine-compare.mjs";
+
+export const LEDGER_NAME = "ledger.jsonl";
+
+export const sha256 = (buf) => crypto.createHash("sha256").update(buf).digest("hex");
+
+/** A stable digest of a settings object — what invalidates every entry when it changes. */
+export function settingsFingerprint(settings) {
+  const ordered = Object.keys(settings).sort().reduce((o, k) => (o[k] = settings[k], o), {});
+  return sha256(JSON.stringify(ordered)).slice(0, 16);
+}
+
+/**
+ * Content digest of a folder or file. Names AND bytes, so a renamed file counts as a
+ * change; mtime is deliberately not read, because a fresh clone rewrites every mtime and
+ * would invalidate a whole ledger for no reason.
+ */
+export async function contentDigest(target) {
+  const h = crypto.createHash("sha256");
+  const walk = async (p, rel) => {
+    const st = await fs.stat(p);
+    if (st.isDirectory()) {
+      for (const name of (await fs.readdir(p)).sort()) {
+        if (name.startsWith(".")) continue;
+        await walk(path.join(p, name), rel ? `${rel}/${name}` : name);
+      }
+    } else {
+      h.update(rel + "\0");
+      h.update(await fs.readFile(p));
+    }
+  };
+  await walk(target, "");
+  return h.digest("hex").slice(0, 16);
+}
+
+/** Read a ledger, tolerating a torn final line. Later lines win over earlier ones for the same id. */
+export async function readLedger(file) {
+  let text = "";
+  try { text = await fs.readFile(file, "utf8"); } catch { return { entries: new Map(), lines: 0, torn: 0 }; }
+  const entries = new Map();
+  let lines = 0, torn = 0;
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    lines++;
+    let rec;
+    try { rec = JSON.parse(line); } catch { torn++; continue; }
+    if (rec && typeof rec.id === "string") entries.set(rec.id, rec);
+  }
+  return { entries, lines, torn };
+}
+
+/**
+ * Append one measurement. Opened, written and closed per call with an fsync, so the line
+ * is on disk before the next component starts rendering — the property the whole resume
+ * story rests on.
+ */
+export async function appendLedger(file, record) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const fh = await fs.open(file, "a");
+  try {
+    await fh.write(JSON.stringify(record) + "\n");
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+}
+
+/** Is this ledger entry still a usable answer for this component, under these settings? */
+export function isFresh(entry, { candidateDigest, referenceDigest, fingerprint }) {
+  if (!entry || typeof entry.diffRatio !== "number") return false;
+  // ⚠️ AN ERRORED LINE IS NEVER FRESH, and this is not a nicety. A failed render records
+  // `diffRatio: 1` so the component counts as failed rather than as missing — which means
+  // it carries a number, and a number is what "already measured" is made of. Without this
+  // line, the browser dying at component 200 of 500 writes a permanent FAIL for the other
+  // 300, and every resume afterwards skips them because the ledger looks complete. The
+  // overnight run then reports 40% forever and nothing re-renders. A transient failure has
+  // to be retried by the next run; a real one costs a re-render and says the same thing.
+  if (entry.error) return false;
+  if (entry.fingerprint !== fingerprint) return false;
+  // No digest means the caller could not tell what this side is made of — a URL with
+  // nothing on disk behind it. Two nulls must never compare equal and count as unchanged:
+  // that is how a component fixed at 2am keeps its 11pm verdict all night.
+  if (!candidateDigest || !referenceDigest) return false;
+  if (entry.candidateDigest !== candidateDigest) return false;
+  if (entry.referenceDigest !== referenceDigest) return false;
+  return true;
+}
+
+/**
+ * Turn a ledger into the per-component report. Verdicts are computed HERE, from the
+ * numbers, every time — a stored `pass` field is not consulted and never will be.
+ */
+export function report(components, entries, threshold) {
+  const rows = components.map((c) => {
+    const e = entries.get(c.id);
+    const v = verdict(e, c.threshold ?? threshold);
+    return {
+      id: c.id,
+      state: v.state,
+      pass: v.pass,
+      reason: v.reason,
+      diffRatio: e && typeof e.diffRatio === "number" ? e.diffRatio : null,
+      diffPixels: e?.diffPixels ?? null,
+      pixels: e?.pixels ?? null,
+      maxDelta: e?.maxDelta ?? null,
+      threshold: c.threshold ?? threshold,
+      measuredAt: e?.measuredAt ?? null,
+    };
+  });
+  const measured = rows.filter((r) => r.state !== "incomplete");
+  const passed = rows.filter((r) => r.pass);
+  return {
+    total: rows.length,
+    measured: measured.length,
+    passed: passed.length,
+    failed: measured.length - passed.length,
+    incomplete: rows.length - measured.length,
+    // The pass-rate is over EVERY component in the manifest, not over the ones that got
+    // measured. A run that fell over after ten of five hundred otherwise reports 100%.
+    passRate: rows.length ? passed.length / rows.length : 0,
+    rows,
+  };
+}