@supersuit/hyperspec 0.5.0 → 0.7.0

package/src/check.mjs

@@ -0,0 +1,191 @@
+// `hyperspec check`: run every deterministic station against a draft, once the spec that
+// declares them is itself lint-clean. This module is the command's logic, independent of the
+// CLI's argv parsing and printing (bin/hyperspec.mjs owns those), the same split rules.mjs and
+// score.mjs already keep for `lint`.
+//
+// A draft is never checked against a spec that is not ready to check anything against: the spec
+// is linted first, and a spec that fails or is blocked runs no station at all, exiting with lint's
+// own code (1 fail, 3 blocked) rather than a check-specific one. Passing lint's test 9 requires
+// improvement.ledger to be a non-empty path (see
+// src/rules.mjs), so by the time any station runs, the spec is guaranteed to declare one; the
+// presence check and escape check in openLedger (src/ledger.mjs) exist anyway: defense in depth
+// costs one branch and this file should never silently assume another file's invariant holds.
+
+import { appendFileSync, readFileSync } from "node:fs";
+import { basename, isAbsolute, relative, resolve } from "node:path";
+import { loadSpec } from "./load.mjs";
+import { lintSpec } from "./rules.mjs";
+import { score, exitCode } from "./score.mjs";
+import { sha256 } from "./hash.mjs";
+import { readDraft } from "./draft.mjs";
+import { openLedger, priorLines, ledgerDraftKey, ledgerVerdict } from "./ledger.mjs";
+import { STATIONS, STATION_NAMES } from "./stations/index.mjs";
+import { str } from "./placeholder.mjs";
+
+const present = (v) => typeof v === "string" && v.trim().length > 0;
+
+// A crash message with every absolute path in it made relative to the working directory, or cut to
+// "<path>/<file name>" when it lies outside it, so a station that hits a filesystem error never
+// prints this machine's layout.
+export function withoutAbsolutePaths(message) {
+  return message.replace(/(?:[A-Za-z]:\\|\/)[^\s'"`,)]+/g, (p) => {
+    if (!isAbsolute(p)) return p;
+    const rel = relative(process.cwd(), p);
+    return rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : `<path>/${basename(p)}`;
+  });
+}
+
+// runStation(station, spec, draft, ctx): runs one station's run(spec, draft, ctx), converting a
+// throw into a single failing finding rather than letting it crash the whole command. A station
+// is pure and deterministic BY CONTRACT, but that contract is not enforced by the type system,
+// and later stations (terms, claims, quotes, private, dna) read JSONL ledgers, segments files
+// and regexes over untrusted draft text, which is a lot more surface for a bug to throw from
+// than form's own narrow reading. A throw here must never crash the whole command (no raw stack
+// trace, no half-finished --json, no skipped ledger line): every OTHER station and the ledger
+// write still run normally, the same way lintSpec's own crash in bin/hyperspec.mjs's `lint`
+// handler becomes a reported error rather than an uncaught exception. Exported (and taking the
+// station object rather than reading STATIONS itself) so this exact wrapping is testable against
+// a station built to throw, without needing one registered in the shared registry
+// (src/stations/index.mjs), which this file does not own.
+export function runStation(station, spec, draft, ctx) {
+  try {
+    return station.run(spec, draft, ctx);
+  } catch (e) {
+    const raw = e instanceof Error ? e.message : String(e);
+    return {
+      station: station.name,
+      status: "fail",
+      findings: [{
+        station: station.name,
+        id: `station-${station.name}-crashed`,
+        severity: "fail",
+        message: withoutAbsolutePaths(raw),
+        fix: "Fix the station or file an issue; it should never throw.",
+      }],
+    };
+  }
+}
+
+// The spec at specPathArg, loaded and required to carry the writing profile: { spec }, or a usage
+// result naming the command. Every station and every judge reads the writing profile's blocks; a
+// spec without it has nothing for them to read, and a run against it would fail quotations it has
+// no materials for.
+export function loadWritingSpec(specPathArg, command) {
+  const spec = loadSpec(specPathArg);
+  if (spec.error) return { usage: true, error: spec.error };
+  if (str(spec.data?.profile) !== "writing") return { usage: true, error: `${command} needs a writing spec (profile: writing)` };
+  return { spec };
+}
+
+// null when the spec lints clean; otherwise the result a command returns instead of grading
+// anything, carrying lint's own exit code (1 fail, 3 blocked): a draft is never graded against a
+// spec that is not ready.
+export function lintBlock(spec, specPathArg) {
+  const lintFindings = lintSpec(spec);
+  const lintScore = score(lintFindings, spec.data);
+  if (lintScore.status === "pass") return null;
+  return {
+    ok: false,
+    lintBlocked: true,
+    specPath: specPathArg,
+    lintStatus: lintScore.status,
+    lintScore,
+    lintFindings,
+    code: exitCode(lintScore.status),
+  };
+}
+
+// runCheck(specPathArg, draftPathArg, { only }): specPathArg and draftPathArg are exactly what
+// the CLI (or a caller) was given, never resolved, so every path this returns or writes to the
+// ledger is displayed and recorded the way the operator typed it, not as an absolute path on this
+// machine. only, when given, is an array of station names to run instead of every registered one.
+export function runCheck(specPathArg, draftPathArg, { only } = {}) {
+  if (!present(specPathArg)) return { usage: true, error: "check needs a spec path" };
+  if (!present(draftPathArg)) return { usage: true, error: "check needs --draft <file>" };
+
+  const loaded = loadWritingSpec(specPathArg, "check");
+  if (loaded.usage) return loaded;
+  const { spec } = loaded;
+
+  // --only: every name must be one this build's registry knows; unknown names are a usage error
+  // (exit 2) rather than a silent no-op, and the run order always follows the registry, never the
+  // order --only happened to name them in, so two operators running the same --only string in a
+  // different order still see stations printed and ledgered identically.
+  let stationsToRun = STATIONS;
+  if (only && only.length) {
+    const unknown = only.filter((n) => !STATION_NAMES.includes(n));
+    if (unknown.length) {
+      return { usage: true, error: `unknown station${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}; known stations: ${STATION_NAMES.join(", ") || "(none)"}` };
+    }
+    stationsToRun = STATIONS.filter((s) => only.includes(s.name));
+  }
+
+  const blocked = lintBlock(spec, specPathArg);
+  if (blocked) return blocked;
+
+  // BOM stripped, CRLF-clean lines, sha256 over the raw bytes: see src/draft.mjs.
+  const draft = readDraft(draftPathArg);
+  if (!draft) return { usage: true, error: `cannot read draft: ${draftPathArg}` };
+
+  const ctx = {};
+  const results = stationsToRun.map((s) => runStation(s, spec, draft, ctx));
+  const failing = results.filter((r) => r.status === "fail").map((r) => r.station);
+  const code = failing.length ? 1 : 0;
+
+  // ---- ledger: one line of evidence per check, only when the spec declares one -----------------
+  // A run with --only is partial: verdict not-improved, reason "partial run: <stations>",
+  // partial: true. Later verdicts ignore partial lines, so a subset never claims (or uses up) the
+  // verdict for the whole draft. A full run is compared with the most recent earlier FULL line for
+  // the same draft path; which verdict that earns, and why each reason is true, is
+  // ledgerVerdict's (src/ledger.mjs), shared with `judge record` so both follow one set of rules.
+  let ledgerPath = null;
+  let ledgerWarning = null;
+  let verdict = null;
+  let verdictDetail = {};
+  const partial = Boolean(only && only.length);
+  const ledger = openLedger(spec);
+  if (ledger?.warning) ledgerWarning = ledger.warning;
+  else if (ledger) {
+    const draftKey = ledgerDraftKey(spec.dir, draftPathArg);
+    const specSha = sha256(readFileSync(resolve(specPathArg)));
+    const statusNow = Object.fromEntries(results.map((r) => [r.station, r.status]));
+
+    if (partial) {
+      verdict = "not-improved";
+      verdictDetail.reason = `partial run: ${results.map((r) => r.station).join(", ")}`;
+    } else {
+      const last = priorLines(ledger.priorText, "check").filter((l) => l.draft === draftKey && l.partial !== true).at(-1);
+      ({ verdict, detail: verdictDetail } = ledgerVerdict({ last, statusNow, draftSha: draft.sha256, specSha }));
+    }
+
+    const line = {
+      at: new Date().toISOString(),
+      kind: "check",
+      draft: draftKey,
+      draft_sha256: draft.sha256,
+      spec_sha256: specSha,
+      stations: statusNow,
+      ...(partial ? { partial: true } : {}),
+      verdict,
+      ...verdictDetail,
+    };
+    appendFileSync(ledger.abs, `${JSON.stringify(line)}\n`);
+    // Reported exactly as the spec wrote it (improvement.ledger's own string), never resolved.
+    ledgerPath = ledger.decl;
+  }
+
+  return {
+    ok: true,
+    specPath: specPathArg,
+    draftPath: draftPathArg,
+    draftSha256: draft.sha256,
+    stations: results,
+    failing,
+    partial,
+    verdict,
+    verdictDetail,
+    ledgerPath,
+    ledgerWarning,
+    code,
+  };
+}

package/src/dna.mjs

@@ -251,7 +251,10 @@ function percentileNearestRank(sortedArr, p) {
 // the token by this same rule; it is simply never "between letters", so it never makes the word
 // count as a contraction below.
 const WORD_RE = /[\p{L}\p{N}'\u2019]+/gu;
-function wordsOf(text) {
+// Exported so a later reader of a whole document (the check command's "form" station counting a
+// draft's words against writing.form.length) reuses this exact word definition rather than
+// keeping a second one that could quietly disagree with it.
+export function wordsOf(text) {
   const m = text.match(WORD_RE);
   return m ? m.map((w) => w.toLowerCase()) : [];
 }

package/src/draft.mjs

@@ -0,0 +1,26 @@
+// Reading a draft the way every command that grades one reads it (`hyperspec check`, `hyperspec
+// judge prepare` and `judge record`), so a station and a judge see the same text for the same file.
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { sha256 } from "./hash.mjs";
+
+// 1-based line array: text.split("\n"), so array index i holds line i + 1. A trailing "\r" (a
+// CRLF file) is stripped from every entry here, at the source, so every station that reads
+// draft.lines sees a clean line ("# Claim", never "# Claim\r") without needing to know CRLF
+// exists; the line COUNT and every 1-based line number are unaffected, since stripping a
+// trailing byte from an entry never changes how many entries there are.
+export function splitLines(text) {
+  return text.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+}
+
+// { path, text, lines, sha256 } for the draft at draftPathArg (resolved against the working
+// directory, recorded as given), or null when it cannot be read. One leading UTF-8 BOM is not part
+// of the draft's text: stripped here, so a heading on line 1 is found and every offset and line
+// number counts from the first real character. sha256 stays over the raw bytes.
+export function readDraft(draftPathArg) {
+  let buf;
+  try { buf = readFileSync(resolve(draftPathArg)); } catch { return null; }
+  const text = buf.toString("utf8").replace(/^/, "");
+  return { path: draftPathArg, text, lines: splitLines(text), sha256: sha256(buf) };
+}

package/src/judge.mjs

@@ -0,0 +1,386 @@
+// `hyperspec judge prepare` and `hyperspec judge record`: judgment stations as packets. hyperspec
+// never calls a model. For each judgment station, `prepare` writes a PACKET: everything a judge
+// needs (the rubric from the spec, fixed instructions, the inputs, the exact verdict shape). An
+// outside judge, a person or a model, fills a VERDICT file. `record` validates the verdict,
+// including that every evidence span it cites really appears in the draft, derives the station's
+// status deterministically, and appends one line to the spec's runs ledger, under the same truth
+// rules `check` follows (src/ledger.mjs).
+//
+// This module is the commands' logic; bin/hyperspec.mjs owns argv parsing and printing, the split
+// src/check.mjs keeps too. Each station lives in src/judges/ and is registered in its index.
+
+import { appendFileSync, existsSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { sha256 } from "./hash.mjs";
+import { writeFileAtomic } from "./fsutil.mjs";
+import { readDraft } from "./draft.mjs";
+import { loadWritingSpec, lintBlock, withoutAbsolutePaths } from "./check.mjs";
+import { openLedger, priorLines, ledgerDraftKey, ledgerVerdict } from "./ledger.mjs";
+import { lineAt, truncate } from "./stations/util.mjs";
+import { JUDGES, JUDGE_NAMES } from "./judges/index.mjs";
+
+export const PACKET_VERSION = "0.1";
+
+const present = (v) => typeof v === "string" && v.trim().length > 0;
+
+// ---- the evidence rule -------------------------------------------------------------------------
+// A span of evidence counts as quoted from the draft when, after both are normalized, the draft
+// contains it. Normalization collapses every run of whitespace (spaces, tabs, line breaks, CRLF) to
+// one space and turns curly, low and angle quotation marks and apostrophes into their straight
+// forms (primes are not quotation marks and are left alone), so a judge that reflows a quotation or
+// types typographic quotes is still quoting; changing a single word is not.
+//
+// A span must also carry at least MIN_EVIDENCE_WORDS word tokens (runs of letters and digits), and
+// match on word boundaries: a match may not start or end in the middle of a word. A one-letter or
+// one-word "quotation" is found almost anywhere and so checks nothing.
+
+export const MIN_EVIDENCE_WORDS = 3;
+const WORD_CHAR = /[\p{L}\p{N}]/u;
+const WORD_TOKENS = /[\p{L}\p{N}]+/gu;
+
+const QUOTE_CHARS = new Map([
+  ["\u2018", "'"], ["\u2019", "'"], ["\u201A", "'"], ["\u201B", "'"], ["\u2039", "'"], ["\u203A", "'"],
+  ["\u201C", '"'], ["\u201D", '"'], ["\u201E", '"'], ["\u201F", '"'], ["\u00AB", '"'], ["\u00BB", '"'],
+]);
+
+// { norm, map }: the normalized text, and for each of its characters the offset in `text` it came
+// from, so a match in the normalized text can be traced back to a line of the original.
+export function normalizeForEvidence(text) {
+  let norm = "";
+  const map = [];
+  let pendingSpace = -1;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (/\s/.test(ch)) { if (norm && pendingSpace < 0) pendingSpace = i; continue; }
+    if (pendingSpace >= 0) { norm += " "; map.push(pendingSpace); pendingSpace = -1; }
+    norm += QUOTE_CHARS.get(ch) ?? ch;
+    map.push(i);
+  }
+  return { norm, map };
+}
+
+// The helpers a station's validate() and derive() receive, bound to one packet and one draft: every
+// finding they build has the same shape as a `check` finding ({ station, id, severity, message,
+// fix, line? }).
+function toolsFor(stationName, draft) {
+  const { norm, map } = normalizeForEvidence(draft.text);
+  // The 1-based line of the first whole-word match of `span`, or -1.
+  const locate = (span) => {
+    const needle = normalizeForEvidence(span).norm;
+    if (!needle) return -1;
+    const startsWord = WORD_CHAR.test(needle[0]);
+    const endsWord = WORD_CHAR.test(needle[needle.length - 1]);
+    for (let at = norm.indexOf(needle); at >= 0; at = norm.indexOf(needle, at + 1)) {
+      const before = at > 0 ? norm[at - 1] : "";
+      const after = norm[at + needle.length] ?? "";
+      if (startsWord && before && WORD_CHAR.test(before)) continue;
+      if (endsWord && after && WORD_CHAR.test(after)) continue;
+      return lineAt(draft.text, map[at]);
+    }
+    return -1;
+  };
+  const finding = (id, message, fix, line) => ({ station: stationName, id, severity: "fail", message, fix, ...(typeof line === "number" && line > 0 ? { line } : {}) });
+  return {
+    finding,
+    shape: (message, fix) => finding("judge-verdict-shape", message, fix),
+    // [] when `value` is a non-empty span found in the draft, else the one finding saying why.
+    evidence(value, where) {
+      if (typeof value !== "string" || !value.trim()) {
+        return [finding("judge-evidence-missing", `${where} is empty or not a string`, "Quote the span of the draft this judgment rests on, verbatim.")];
+      }
+      const words = (normalizeForEvidence(value).norm.match(WORD_TOKENS) ?? []).length;
+      if (words < MIN_EVIDENCE_WORDS) {
+        return [finding("judge-evidence-too-short", `${where} has ${words} word${words === 1 ? "" : "s"}, fewer than ${MIN_EVIDENCE_WORDS}: "${truncate(value, 80)}"`, `Quote the sentence or clause the judgment rests on, at least ${MIN_EVIDENCE_WORDS} words, verbatim.`)];
+      }
+      if (locate(value) < 0) {
+        return [finding("judge-evidence-not-found", `${where} is not in the draft: "${truncate(value, 80)}"`, "Copy the evidence verbatim from the draft, whole words only; only whitespace and quote characters may differ.")];
+      }
+      return [];
+    },
+    // The 1-based draft line where a (valid) evidence span starts, or undefined.
+    lineOf(span) {
+      const line = typeof span === "string" ? locate(span) : -1;
+      return line > 0 ? line : undefined;
+    },
+  };
+}
+
+// The message for files whose bytes no longer match the hashes a packet recorded. Nothing on disk
+// can tell a file changed since prepare from a packet whose hash (or path) was edited, so it claims
+// neither. `names` lists the files, e.g. ["the spec", "the draft"]. Shared with
+// `learn record`.
+export function hashMismatchMessage(names) {
+  const one = names.length === 1;
+  const what = one ? names[0] : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+  return `${what} ${one ? "does" : "do"} not match the ${one ? "hash" : "hashes"} the packet recorded: ${one ? "it" : "they"} changed since prepare, or the packet was edited`;
+}
+
+const packetJson = (packet) => `${JSON.stringify(packet, null, 2)}\n`;
+
+// The packet one judge gets for this spec and draft, built the one way both commands build it:
+// prepare writes it, and record rebuilds it to check the file it was handed. { packet, packetBytes,
+// key }: key is the station's hidden answer key (null for a station with none), written by prepare
+// to <station>.key.json for a person to read, and never read back as truth: record rebuilds it.
+// specPathArg and the draft's path are the strings as given, so the bytes are deterministic.
+export function buildPacket(judge, specPathArg, spec, draft, specSha) {
+  const parts = judge.packet(spec, draft);
+  const packet = {
+    hyperspec_judge: PACKET_VERSION,
+    station: judge.name,
+    spec: specPathArg,
+    spec_sha256: specSha,
+    draft: draft.path,
+    draft_sha256: draft.sha256,
+    rubric: parts.rubric,
+    instructions: judge.instructions,
+    inputs: parts.inputs,
+    verdict_schema: parts.verdict_schema,
+  };
+  return { packet, packetBytes: packetJson(packet), key: parts.key ?? null };
+}
+
+// ---- prepare -----------------------------------------------------------------------------------
+
+// prepareJudges(specPathArg, draftPathArg, outDirArg, { only, force }): writes one
+// <station>.packet.json (plus <station>.key.json where a station has a hidden answer key) per
+// applicable station into outDirArg. Paths are kept as given, so the same spec and draft produce
+// byte-identical packets. Refuses (usage) to overwrite an existing file without force, naming every
+// one, and writes nothing in that case.
+export function prepareJudges(specPathArg, draftPathArg, outDirArg, { only, force = false } = {}) {
+  if (!present(specPathArg)) return { usage: true, error: "judge prepare needs a spec path" };
+  if (!present(draftPathArg)) return { usage: true, error: "judge prepare needs --draft <file>" };
+  if (!present(outDirArg)) return { usage: true, error: "judge prepare needs --out <dir>" };
+
+  const loaded = loadWritingSpec(specPathArg, "judge prepare");
+  if (loaded.usage) return loaded;
+  const { spec } = loaded;
+
+  let judges = JUDGES;
+  if (only && only.length) {
+    const unknown = only.filter((n) => !JUDGE_NAMES.includes(n));
+    if (unknown.length) {
+      return { usage: true, error: `unknown judge${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}; known judges: ${JUDGE_NAMES.join(", ")}` };
+    }
+    judges = JUDGES.filter((j) => only.includes(j.name));
+  }
+
+  let outStat = null;
+  try { outStat = statSync(resolve(outDirArg)); } catch { /* reported below */ }
+  if (!outStat) return { usage: true, error: `--out folder does not exist: ${outDirArg}; create it first` };
+  if (!outStat.isDirectory()) return { usage: true, error: `--out is not a folder: ${outDirArg}` };
+
+  const blocked = lintBlock(spec, specPathArg);
+  if (blocked) return blocked;
+
+  const draft = readDraft(draftPathArg);
+  if (!draft) return { usage: true, error: `cannot read draft: ${draftPathArg}` };
+  const specSha = sha256(readFileSync(resolve(specPathArg)));
+
+  const files = [];
+  const skipped = [];
+  const crashed = [];
+  for (const judge of judges) {
+    const reason = judge.skipReason(spec, draft);
+    if (reason) { skipped.push({ station: judge.name, reason }); continue; }
+    let built;
+    try { built = buildPacket(judge, specPathArg, spec, draft, specSha); }
+    catch (e) {
+      crashed.push({ station: judge.name, id: `judge-${judge.name}-crashed`, severity: "fail", message: withoutAbsolutePaths(e instanceof Error ? e.message : String(e)), fix: "Fix the station or file an issue; it should never throw." });
+      continue;
+    }
+    files.push({ station: judge.name, path: join(outDirArg, `${judge.name}.packet.json`), bytes: built.packetBytes });
+    if (built.key) files.push({ station: judge.name, path: join(outDirArg, `${judge.name}.key.json`), bytes: packetJson(built.key) });
+  }
+
+  const existing = files.filter((f) => existsSync(resolve(f.path))).map((f) => f.path);
+  if (existing.length && !force) {
+    return { usage: true, error: `refusing to overwrite ${existing.join(", ")}; pass --force to replace ${existing.length > 1 ? "them" : "it"}` };
+  }
+  for (const f of files) writeFileAtomic(resolve(f.path), f.bytes);
+
+  return {
+    ok: true,
+    specPath: specPathArg,
+    draftPath: draftPathArg,
+    draftSha256: draft.sha256,
+    written: files.map((f) => ({ station: f.station, path: f.path })),
+    skipped,
+    crashed,
+    code: crashed.length ? 1 : 0,
+  };
+}
+
+// ---- record ------------------------------------------------------------------------------------
+
+// recordJudgment(packetPathArg, verdictPathArg): validates the verdict against its packet and, when
+// it is valid, derives the station's status and appends one ledger line. Returns a usage result
+// (exit 2), { invalid } (exit 1, nothing appended; a stale packet is { invalid, stale }, the shape
+// `learn record` returns too), or the recorded result (exit 0 when the station passes, 1 when it
+// fails).
+export function recordJudgment(packetPathArg, verdictPathArg) {
+  if (!present(packetPathArg)) return { usage: true, error: "judge record needs a packet path" };
+  if (!present(verdictPathArg)) return { usage: true, error: "judge record needs --verdict <file>" };
+
+  let packetText;
+  try { packetText = readFileSync(resolve(packetPathArg), "utf8"); }
+  catch { return { usage: true, error: `cannot read packet: ${packetPathArg}` }; }
+  let packet;
+  try { packet = JSON.parse(packetText); } catch { packet = null; }
+  if (!packet || typeof packet !== "object" || packet.hyperspec_judge !== PACKET_VERSION || !present(packet.station) || !present(packet.spec) || !present(packet.draft)) {
+    return { usage: true, error: `not a hyperspec judge packet: ${packetPathArg}` };
+  }
+  const judge = JUDGES.find((j) => j.name === packet.station);
+  if (!judge) return { usage: true, error: `the packet names an unknown judge: ${packet.station}; known judges: ${JUDGE_NAMES.join(", ")}` };
+
+  let verdictBuf;
+  try { verdictBuf = readFileSync(resolve(verdictPathArg)); }
+  catch { return { usage: true, error: `cannot read verdict: ${verdictPathArg}` }; }
+
+  const loaded = loadWritingSpec(packet.spec, "judge record");
+  if (loaded.usage) return { usage: true, error: `the packet's spec: ${loaded.error}` };
+  const { spec } = loaded;
+  const draft = readDraft(packet.draft);
+  if (!draft) return { usage: true, error: `cannot read the packet's draft: ${packet.draft}` };
+
+  const base = { packetPath: packetPathArg, verdictPath: verdictPathArg, station: judge.name };
+  const t = toolsFor(judge.name, draft);
+
+  // A verdict on bytes other than the ones the packet was prepared from judges nothing that exists.
+  const specSha = sha256(readFileSync(resolve(packet.spec)));
+  const draftChanged = draft.sha256 !== packet.draft_sha256;
+  const specChanged = specSha !== packet.spec_sha256;
+  if (draftChanged || specChanged) {
+    const names = [specChanged && "the spec", draftChanged && "the draft"].filter(Boolean);
+    return { ...base, ok: false, invalid: true, stale: true, findings: [t.finding("judge-stale", hashMismatchMessage(names), "Run judge prepare again (with --force) and judge the new packet.")], code: 1 };
+  }
+
+  // record never trusts the packet file: it rebuilds the packet (and any answer key) from the spec
+  // and draft on disk, requires the file to be those exact bytes, and validates the verdict against
+  // the rebuilt copy only. A packet edited after prepare (its conditions, its inputs, a hash made to
+  // match a changed draft) is refused here.
+  const skip = judge.skipReason(spec, draft);
+  let rebuilt = null;
+  if (!skip) {
+    try { rebuilt = buildPacket(judge, packet.spec, spec, draft, specSha); }
+    catch (e) {
+      return { ...base, ok: false, invalid: true, findings: [t.finding(`judge-${judge.name}-crashed`, withoutAbsolutePaths(e instanceof Error ? e.message : String(e)), "Fix the station or file an issue; it should never throw.")], code: 1 };
+    }
+  }
+  // A station that reads files besides the spec and the draft (lineup reads the DNA
+  // goldens) can go out of date with both hashes unchanged. When the file is a well-formed packet
+  // that differs from the rebuilt one only in its inputs, that is reported as stale, naming those
+  // files; the packet could also have been hand-edited there (its inputs, or a hash forged to match
+  // an edited draft), and the message says so without claiming either hash is honest,
+  // since nothing on disk can tell these apart. Anything else is an altered packet.
+  //
+  // A station can also stop applying because of those files (persona's claims ledger deleted,
+  // lineup's goldens removed): its sourceSkip names that reason, and with the spec and draft hashes
+  // matching the packet is stale for the same reason, the message saying the station no longer
+  // applies and why. Any other skip (the spec changed under a forged hash, say) is an altered
+  // packet. Neither message tells the user to judge a packet prepare will no longer write.
+  const sources = judge.inputSources?.(spec) ?? null;
+  const staleSources = (message, fix) => ({ ...base, ok: false, invalid: true, stale: true, findings: [t.finding("judge-stale", `${message}: ${sources} changed since the packet was prepared, or the packet was edited`, fix)], code: 1 });
+  const sourceSkip = !rebuilt && sources ? judge.sourceSkip?.(spec, draft) ?? null : null;
+  if (sourceSkip) {
+    return staleSources(`${judge.name} no longer applies (${sourceSkip})`, `Restore ${sources} and record this verdict again; as they are now, judge prepare skips ${judge.name} for this spec and draft.`);
+  }
+  if (rebuilt && rebuilt.packetBytes !== packetText && sources && packetJson(packet) === packetText
+      && JSON.stringify({ ...packet, inputs: null }) === JSON.stringify({ ...rebuilt.packet, inputs: null })) {
+    return staleSources(`the packet's inputs no longer match what the spec, the draft and ${sources} produce now`, `Run judge prepare again (with --force) so the packet is built from the spec, the draft and ${sources} as they are now, and judge the new packet.`);
+  }
+  if (!rebuilt) {
+    return { ...base, ok: false, invalid: true, findings: [t.finding("judge-packet-altered", `${packetPathArg} is for a station that does not apply to this spec and draft (${skip})`, `judge prepare writes no ${judge.name} packet for this spec and draft; record verdicts only on packets prepare writes, and never edit one.`)], code: 1 };
+  }
+  if (rebuilt.packetBytes !== packetText) {
+    return { ...base, ok: false, invalid: true, findings: [t.finding("judge-packet-altered", `${packetPathArg} is not the packet judge prepare builds from the spec and draft on disk`, "Run judge prepare again (with --force) and judge the new packet; never edit a packet.")], code: 1 };
+  }
+
+  let verdictJson;
+  try { verdictJson = JSON.parse(verdictBuf.toString("utf8").replace(/^/, "")); }
+  catch (e) {
+    return { ...base, ok: false, invalid: true, findings: [t.finding("judge-verdict-not-json", `the verdict is not valid JSON (${e instanceof Error ? e.message : String(e)})`, "Write the verdict as one JSON object in the packet's verdict_schema shape.")], code: 1 };
+  }
+
+  let problems;
+  let derived;
+  try {
+    problems = judge.validate(verdictJson, rebuilt.packet, t, rebuilt.key);
+    if (!problems.length) derived = judge.derive(verdictJson, rebuilt.packet, t, rebuilt.key);
+  } catch (e) {
+    const crash = t.finding(`judge-${judge.name}-crashed`, withoutAbsolutePaths(e instanceof Error ? e.message : String(e)), "Fix the station or file an issue; it should never throw.");
+    return { ...base, ok: false, invalid: true, findings: [crash], code: 1 };
+  }
+  if (problems.length) return { ...base, ok: false, invalid: true, findings: problems, code: 1 };
+
+  // summary: an optional one-line result a station reports beside its status (attribution's
+  // accuracy); printed after the status and carried in --json, never in the ledger line.
+  const { status, findings, summary } = derived;
+
+  // ---- ledger: the same truth rules as check: compared with the most recent earlier
+  // judge line for the same station and draft path, through ledgerVerdict; two judge-only rules on
+  // top are marked below.
+  let ledgerPath = null;
+  let ledgerWarning = null;
+  let verdict = null;
+  let verdictDetail = {};
+  const ledger = openLedger(spec);
+  if (ledger?.warning) ledgerWarning = ledger.warning;
+  else if (ledger) {
+    const draftKey = ledgerDraftKey(spec.dir, packet.draft);
+    // packet_sha256: the hash of what the judge was shown, taken over the packet with its two paths
+    // written as the ledger writes them (relative to the spec's folder), so the same packet
+    // prepared from another folder, or as ./draft.md, hashes the same and a path's spelling can
+    // never pass for a change.
+    const packetSha = sha256(packetJson({ ...rebuilt.packet, spec: ledgerDraftKey(spec.dir, packet.spec), draft: draftKey }));
+    // inputs_sha256: the hash of the packet's inputs alone, so a packet that changed can be told
+    // apart as changed inputs (the files the station reads) or changed fixed text (a release that
+    // rewords the instructions or the schema).
+    const inputsSha = sha256(JSON.stringify(rebuilt.packet.inputs));
+    const judgeLines = priorLines(ledger.priorText, "judge");
+    const prior = judgeLines.filter((l) => l.station === judge.name && l.draft === draftKey).at(-1);
+    const last = prior ? { stations: { [prior.station]: prior.status }, draft_sha256: prior.draft_sha256, spec_sha256: prior.spec_sha256 } : undefined;
+    // What changed since that line is judged by what the judge was shown: the packet. The draft
+    // and the spec are named when their bytes changed. A packet that changed with both unchanged
+    // was changed either in its inputs, by the files the station reads besides them (the DNA
+    // scope, the claims ledger), which are named, or in its fixed text (hyperspec's instructions
+    // or format), which is said. A line with no packet_sha256 (none is written without one) is
+    // compared by the two hashes alone.
+    let what = null;
+    if (prior) {
+      const draftChanged = prior.draft_sha256 !== draft.sha256;
+      const specChanged = prior.spec_sha256 !== specSha;
+      if (draftChanged || specChanged) what = draftChanged && specChanged ? "spec and draft" : specChanged ? "spec" : "draft";
+      else if (typeof prior.packet_sha256 === "string" && prior.packet_sha256 !== packetSha) {
+        what = prior.inputs_sha256 === inputsSha ? "the packet's fixed text (hyperspec's instructions or format)" : sources ?? "the packet's inputs";
+      }
+    }
+    ({ verdict, detail: verdictDetail } = ledgerVerdict({
+      last, statusNow: { [judge.name]: status }, draftSha: draft.sha256, specSha, noun: "judgment", what,
+      // A judge can answer differently about an identical packet; that is not the work improving.
+      unchangedImprovedReason: "the verdict changed; nothing the judge was shown changed",
+    }));
+    // one-shot means these bytes passed the first time they were judged, whatever the file was
+    // called: bytes already judged under another path (a copy, a rename) never earn it.
+    if (verdict === "one-shot") {
+      const sameBytes = judgeLines.filter((l) => l.station === judge.name && l.draft_sha256 === draft.sha256).at(-1);
+      if (sameBytes) { verdict = "not-improved"; verdictDetail = { reason: `these draft bytes were judged before as ${sameBytes.draft}: ${sameBytes.status}` }; }
+    }
+    const line = {
+      at: new Date().toISOString(),
+      kind: "judge",
+      station: judge.name,
+      draft: draftKey,
+      draft_sha256: draft.sha256,
+      spec_sha256: specSha,
+      packet_sha256: packetSha,
+      inputs_sha256: inputsSha,
+      status,
+      verdict,
+      ...verdictDetail,
+    };
+    appendFileSync(ledger.abs, `${JSON.stringify(line)}\n`);
+    ledgerPath = ledger.decl;
+  }
+
+  return { ...base, ok: true, status, ...(summary ? { summary } : {}), findings, verdict, verdictDetail, ledgerPath, ledgerWarning, code: status === "pass" ? 0 : 1 };
+}