paperlint 12.0.0 → 13.0.0

package/src/domain/versions.ts

@@ -0,0 +1,706 @@
+/**
+ * THE FROZEN VERSIONS OF A PAPER, by convention: one folder per attempt at a venue, named by the
+ * attempt's id in `paperlint.json` `cycles`, holding a file per stage and nothing else.
+ *
+ *   versions/
+ *   ├── alpha-2026/            ← a cycle id
+ *   │   ├── submitted.pdf      ← what the venue's reviewers read
+ *   │   └── submitted.tex      ← the source it was built from (a multi-file paper: assembled)
+ *   ├── beta-2027/
+ *   │   ├── submitted.pdf
+ *   │   ├── submitted.tex
+ *   │   └── camera-ready.pdf   ← only after the attempt is accepted
+ *   └── lock.json              ← generated: bytes, sha256 and the time each file was frozen
+ *
+ * ── WHY NAMES, NOT A RECORD ─────────────────────────────────────────────────────────────
+ * The `stages:` list in a paper's scorecard said the same thing as the file names, a second time, by
+ * hand, and a rule kept the two in step. Here the names ARE the record: which attempt a file belongs
+ * to is its folder, which stage is its name, and what state it is in follows from the attempt's
+ * `outcome` — the one value an author changes when a decision arrives. Nothing is typed twice.
+ *
+ * ── WHY A LOCK ──────────────────────────────────────────────────────────────────────────
+ * What a name cannot carry — the bytes a file had when it was frozen, its digest, when it was frozen,
+ * and that a source was lost — goes into `lock.json`, which paperlint writes and nobody edits
+ * (`package-lock.json`, `schema.rb`). A frozen file is never supposed to change, so a file that does
+ * not match its lock entry is the finding.
+ *
+ * ── NO DATES IN NAMES ───────────────────────────────────────────────────────────────────
+ * A second upload to the same attempt replaces the first: the last upload is the one under review.
+ * When it was frozen is a fact paperlint records in the lock, not one a person types into a name.
+ *
+ * Pure: the disk is read by the caller and handed in.
+ */
+import { diffLines } from "diff";
+import * as R from "remeda";
+import {
+  CYCLE_ID_PATTERN,
+  type Current,
+  type Cycle,
+  type CycleId,
+} from "./cycle.ts";
+import { isRecord } from "./record.ts";
+import { err, ok, type Result } from "./result.ts";
+
+export const VERSIONS_DIR = "versions";
+export const LOCK_FILE = "lock.json";
+
+/** The stages a version is frozen at, in the order an attempt reaches them. */
+export const VERSION_STAGES = ["submitted", "camera-ready", "arxiv"] as const;
+export type VersionStage = (typeof VERSION_STAGES)[number];
+export type VersionExt = "pdf" | "tex";
+
+const isStage = (s: unknown): s is VersionStage =>
+  VERSION_STAGES.some((v) => v === s);
+
+/** A frozen file in a cycle's folder: its stage and extension. */
+export interface FrozenName {
+  readonly stage: VersionStage;
+  readonly ext: VersionExt;
+}
+
+/** `submitted.pdf` → its stage and extension; null for a name outside the convention. Pure. */
+export function frozenName(name: string): FrozenName | null {
+  const m = /^([a-z-]+)\.(pdf|tex)$/.exec(name);
+  const stage = m?.[1];
+  const ext = m?.[2];
+  return isStage(stage) && (ext === "pdf" || ext === "tex")
+    ? { stage, ext }
+    : null;
+}
+
+/** `<cycle>/<stage>.<ext>`: a frozen file's path under `versions/`, and its key in the lock. */
+export const frozenKey = (
+  cycle: CycleId,
+  stage: VersionStage,
+  ext: VersionExt,
+): string => `${cycle}/${stage}.${ext}`;
+
+/**
+ * A frozen file in the layout before folders per attempt, `versions/<date>-<stage>.<ext>`: what
+ * `paperlint versions migrate` moves into its attempt's folder.
+ */
+export const DATED_NAME = /^(\d{4}-\d{2}-\d{2})-([a-z-]+)\.(pdf|tex)$/;
+
+// ── the lock ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * One frozen file in the lock: its bytes and digest as frozen, and when (an instant for a file
+ * paperlint froze on send or recorded; the day of the stage for one migrated from `stages:`) — or a
+ * source recorded as LOST, which a frozen PDF of an earlier layout may have.
+ */
+export type LockEntry =
+  | {
+      readonly kind: "file";
+      readonly bytes: number;
+      readonly sha256: string;
+      readonly frozen: string;
+    }
+  | { readonly kind: "lost"; readonly frozen: string | null };
+
+/** The lock: an entry per frozen file, by `<cycle>/<stage>.<ext>`. */
+export type Lock = Readonly<Record<string, LockEntry>>;
+
+export const LOCK_VERSION = 1;
+
+/** What the lock says about itself, so nobody takes it for a file to edit. */
+export const LOCK_NOTE =
+  "generated by paperlint — do not edit: `paperlint submission update --save` and `paperlint versions lock` write it";
+
+const SHA256 = /^[0-9a-f]{64}$/;
+const WHEN = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?Z)?$/;
+/** `<cycle>/<stage>.<ext>`, the cycle part by the same rule `parseCycles` holds an id to. */
+const KEY = new RegExp(`^(${CYCLE_ID_PATTERN})/([a-z-]+\\.(?:pdf|tex))$`);
+
+const isWhen = (v: unknown): v is string =>
+  typeof v === "string" && WHEN.test(v);
+
+/** The cycle and the file name of a lock key; null for a key that is not `<cycle>/<stage>.<ext>`. */
+export function keyParts(
+  key: string,
+): { readonly cycle: string; readonly name: FrozenName } | null {
+  const m = KEY.exec(key);
+  const name = frozenName(m?.[2] ?? "");
+  return m?.[1] === undefined || name === null ? null : { cycle: m[1], name };
+}
+
+const FILE_KEYS: readonly string[] = ["bytes", "sha256", "frozen"];
+const LOST_KEYS: readonly string[] = ["sourceLost", "frozen"];
+
+const whenProblem = (at: string): string =>
+  `${at}: "frozen" must be a date or an instant`;
+
+/** An entry recording a lost source: `{ "sourceLost": true, "frozen"? }`. */
+function parseLost(
+  at: string,
+  ext: VersionExt,
+  frozen: unknown,
+): Result<LockEntry, string> {
+  if (ext !== "tex")
+    return err(`${at}: only a source (.tex) can be recorded as lost`);
+  return frozen === undefined || isWhen(frozen)
+    ? ok({ kind: "lost", frozen: frozen ?? null })
+    : err(whenProblem(at));
+}
+
+/** An entry recording a frozen file: `{ "bytes", "sha256", "frozen" }`. */
+function parseFile(
+  at: string,
+  v: Readonly<Record<string, unknown>>,
+): Result<LockEntry, string> {
+  const { bytes, sha256, frozen } = v;
+  if (typeof bytes !== "number" || !Number.isInteger(bytes) || bytes < 0)
+    return err(`${at}: "bytes" must be a whole number`);
+  if (typeof sha256 !== "string" || !SHA256.test(sha256))
+    return err(`${at}: "sha256" must be 64 lowercase hex digits`);
+  return isWhen(frozen)
+    ? ok({ kind: "file", bytes, sha256, frozen })
+    : err(whenProblem(at));
+}
+
+function parseEntry(key: string, v: unknown): Result<LockEntry, string> {
+  const at = `"files"["${key}"]`;
+  const parts = keyParts(key);
+  if (parts === null) return err(`${at}: a key is <cycle>/<stage>.pdf or .tex`);
+  if (!isRecord(v)) return err(`${at} must be an object`);
+  const lost = v["sourceLost"] === true;
+  const unknown = Object.keys(v).find(
+    (k) => !(lost ? LOST_KEYS : FILE_KEYS).includes(k),
+  );
+  if (unknown !== undefined) return err(`${at}: unknown key "${unknown}"`);
+  return lost ? parseLost(at, parts.name.ext, v["frozen"]) : parseFile(at, v);
+}
+
+/** `lock.json`, parsed → the lock, or one line naming what is wrong. Pure. */
+export function parseLock(json: unknown): Result<Lock, string> {
+  if (!isRecord(json) || json["lockfileVersion"] !== LOCK_VERSION)
+    return err(
+      `not a lock this paperlint writes ("lockfileVersion": ${String(LOCK_VERSION)})`,
+    );
+  const files = json["files"];
+  if (!isRecord(files)) return err(`"files" must be an object`);
+  return Object.entries(files).reduce<Result<Lock, string>>((acc, [key, v]) => {
+    if (!acc.ok) return acc;
+    const e = parseEntry(key, v);
+    return e.ok ? ok({ ...acc.value, [key]: e.value }) : e;
+  }, ok({}));
+}
+
+const entryJson = (e: LockEntry): object =>
+  e.kind === "lost"
+    ? { sourceLost: true, ...(e.frozen === null ? {} : { frozen: e.frozen }) }
+    : { bytes: e.bytes, sha256: e.sha256, frozen: e.frozen };
+
+/** The lock as paperlint writes it: keys sorted, two spaces, a newline at the end. Pure. */
+export const lockText = (lock: Lock): string =>
+  `${JSON.stringify(
+    {
+      lockfileVersion: LOCK_VERSION,
+      note: LOCK_NOTE,
+      files: Object.fromEntries(
+        R.sortBy(Object.entries(lock), ([k]) => k).map(([k, e]) => [
+          k,
+          entryJson(e),
+        ]),
+      ),
+    },
+    null,
+    2,
+  )}\n`;
+
+/** What the disk says about a file: its size and digest. */
+export interface FileFacts {
+  readonly bytes: number;
+  readonly sha256: string;
+}
+
+// ── the layout, judged ──────────────────────────────────────────────────────────────────
+
+/** One entry of a folder: a file or a folder. */
+export interface Entry {
+  readonly name: string;
+  readonly kind: "file" | "dir";
+}
+
+/** A finding, as the rule reports it: a message id and the data its template names. */
+export interface VersionFinding {
+  readonly messageId: string;
+  readonly data: Readonly<Record<string, string>>;
+}
+
+/** What `versions/layout` judges: the paper's cycles, the folder's entries, and the lock. */
+export interface LayoutInput {
+  readonly cycles: readonly Cycle[];
+  /** The entries directly in `versions/`. */
+  readonly root: readonly Entry[];
+  /** The entries of the folder `name` in `versions/`. */
+  readonly inFolder: (name: string) => readonly Entry[];
+  /** `lock.json`: null when there is none; else parsed, or why it does not parse. */
+  readonly lock: Result<Lock, string> | null;
+  /** The size and digest of a frozen file on disk, by its key. */
+  readonly factsOf: (key: string) => FileFacts;
+}
+
+/** A frozen file found on disk: its key, cycle, stage and extension. */
+interface Found extends FrozenName {
+  readonly key: string;
+  readonly cycle: CycleId;
+}
+
+const STAGES_TEXT = VERSION_STAGES.join(", ");
+
+const stray = (path: string, hint: string): VersionFinding => ({
+  messageId: "stray",
+  data: { path, hint },
+});
+
+const MIGRATE_HINT =
+  "a frozen version in the layout before folders per attempt: `npx paperlint versions migrate <paper>` moves it into versions/<cycle>/";
+const LAYOUT_HINT = `versions/ holds lock.json and one folder per cycle, each with <stage>.pdf and <stage>.tex (${STAGES_TEXT}) — anything else goes to extra/`;
+
+/** An entry directly in `versions/`: fine, a cycle's folder, or a finding. */
+function rootFinding(
+  e: Entry,
+  ids: readonly string[],
+): readonly VersionFinding[] {
+  if (e.name.startsWith(".")) return [];
+  if (e.kind === "dir")
+    return ids.includes(e.name)
+      ? []
+      : [
+          {
+            messageId: "unknownCycle",
+            data: { folder: e.name, known: ids.join(" · ") || "(none)" },
+          },
+        ];
+  if (e.name === LOCK_FILE) return [];
+  return [stray(e.name, DATED_NAME.test(e.name) ? MIGRATE_HINT : LAYOUT_HINT)];
+}
+
+/** The frozen files of the cycles' folders, and every entry there outside the convention. */
+function folderContents(input: LayoutInput): {
+  readonly found: readonly Found[];
+  readonly strays: readonly VersionFinding[];
+} {
+  // Each cycle's folder by the cycle's own id, so every key below is built from a parsed one.
+  const folders = input.cycles
+    .map((c) => c.id)
+    .filter((id) => input.root.some((e) => e.kind === "dir" && e.name === id));
+  const listed = folders.flatMap((id) =>
+    input.inFolder(id).map((e) => ({ cycle: id, e })),
+  );
+  const named = listed.map(({ cycle, e }) => ({
+    cycle,
+    e,
+    name: e.kind === "file" ? frozenName(e.name) : null,
+  }));
+  return {
+    found: named.flatMap(({ cycle, name }) =>
+      name === null
+        ? []
+        : [{ ...name, cycle, key: frozenKey(cycle, name.stage, name.ext) }],
+    ),
+    strays: named
+      .filter(({ e, name }) => name === null && !e.name.startsWith("."))
+      .map(({ cycle, e }) => stray(`${cycle}/${e.name}`, LAYOUT_HINT)),
+  };
+}
+
+const isLost = (lock: Lock, key: string): boolean => lock[key]?.kind === "lost";
+
+/** Each frozen PDF without its source beside it, unless the lock records the source as lost. */
+function missingSources(
+  found: readonly Found[],
+  lock: Lock,
+): readonly VersionFinding[] {
+  const keys = found.map((f) => f.key);
+  return found
+    .filter((f) => f.ext === "pdf")
+    .map((f) => ({ f, tex: frozenKey(f.cycle, f.stage, "tex") }))
+    .filter(({ tex }) => !keys.includes(tex) && !isLost(lock, tex))
+    .map(({ f, tex }) => ({
+      messageId: "noSource",
+      data: { pdf: f.key, tex },
+    }));
+}
+
+/** A version sent from a cycle whose source is still declared to be in the previous venue's template. */
+const portingSends = (
+  found: readonly Found[],
+  cycles: readonly Cycle[],
+): readonly VersionFinding[] =>
+  found
+    .filter(
+      (f) =>
+        f.ext === "pdf" &&
+        (f.stage === "submitted" || f.stage === "camera-ready") &&
+        cycles.find((c) => c.id === f.cycle)?.phase === "porting",
+    )
+    .map((f) => ({ messageId: "porting", data: { file: f.key, id: f.cycle } }));
+
+/** Each frozen file against its lock entry, and each lock entry against the disk. */
+function lockFindings(
+  found: readonly Found[],
+  lock: Lock,
+  factsOf: (key: string) => FileFacts,
+): readonly VersionFinding[] {
+  const keys = found.map((f) => f.key);
+  const onDisk = found.flatMap((f): readonly VersionFinding[] => {
+    const e = lock[f.key];
+    if (e === undefined || e.kind === "lost")
+      return [{ messageId: "notLocked", data: { file: f.key } }];
+    const got = factsOf(f.key);
+    return got.bytes === e.bytes && got.sha256 === e.sha256
+      ? []
+      : [
+          {
+            messageId: "changed",
+            data: {
+              file: f.key,
+              want: String(e.bytes),
+              got: String(got.bytes),
+              frozen: e.frozen,
+            },
+          },
+        ];
+  });
+  const gone = Object.entries(lock)
+    .filter(([k, e]) => e.kind === "file" && !keys.includes(k))
+    .map(([k]) => ({ messageId: "lockedGone", data: { file: k } }));
+  return [...onDisk, ...gone];
+}
+
+/** The lock's findings: none needed, none there, unreadable, or each file against it. */
+function lockOf(
+  input: LayoutInput,
+  found: readonly Found[],
+): readonly VersionFinding[] {
+  if (input.lock === null)
+    return found.length === 0 ? [] : [{ messageId: "noLock", data: {} }];
+  if (!input.lock.ok)
+    return [{ messageId: "badLock", data: { why: input.lock.error } }];
+  return lockFindings(found, input.lock.value, input.factsOf);
+}
+
+/**
+ * `versions/layout`: every entry of `versions/` against the convention — a folder per cycle, a file
+ * per stage — the porting declaration, and every frozen file against the lock. Pure.
+ */
+export function judgeVersions(input: LayoutInput): readonly VersionFinding[] {
+  const ids = input.cycles.map((c) => c.id);
+  const { found, strays } = folderContents(input);
+  const lock = input.lock?.ok === true ? input.lock.value : {};
+  return [
+    ...input.root.flatMap((e) => rootFinding(e, ids)),
+    ...strays,
+    ...missingSources(found, lock),
+    ...portingSends(found, input.cycles),
+    ...lockOf(input, found),
+  ];
+}
+
+/**
+ * `cycle/submitted-frozen`: each cycle that has a submission on the portal and no
+ * `versions/<id>/submitted.pdf`. Pure over whether a file exists, by its key.
+ */
+export const unfrozenSubmissions = (
+  cycles: readonly Cycle[],
+  has: (key: string) => boolean,
+): readonly VersionFinding[] =>
+  cycles
+    .filter(
+      (c) => c.submission !== null && !has(frozenKey(c.id, "submitted", "pdf")),
+    )
+    .map((c) => ({
+      messageId: "unfrozen",
+      data: {
+        id: c.id,
+        submission: String(c.submission?.id),
+        pdf: frozenKey(c.id, "submitted", "pdf"),
+      },
+    }));
+
+// ── the draft against a frozen source ─────────────────────────────────────────────────
+
+/** How far one text has moved from another, in lines: added and removed. */
+export interface Drift {
+  readonly added: number;
+  readonly removed: number;
+}
+
+/** The lines `draft` adds to `frozen` and removes from it (a line diff, as `git diff --numstat`). Pure. */
+export function lineDrift(frozen: string, draft: string): Drift {
+  const parts = diffLines(frozen, draft);
+  return {
+    added: R.sumBy(parts, (p) => (p.added ? p.count : 0)),
+    removed: R.sumBy(parts, (p) => (p.removed ? p.count : 0)),
+  };
+}
+
+/** How much of an accepted source a later version keeps: its lines left unchanged, of all it had. */
+export interface Lineage {
+  readonly kept: number;
+  readonly total: number;
+}
+
+/** The lines of `accepted` that `later` keeps unchanged, counted with the same line diff as the drift. Pure. */
+export function lineage(accepted: string, later: string): Lineage {
+  const parts = diffLines(accepted, later);
+  const kept = R.sumBy(parts, (p) => (p.added || p.removed ? 0 : p.count));
+  const removed = R.sumBy(parts, (p) => (p.removed ? p.count : 0));
+  return { kept, total: kept + removed };
+}
+
+/**
+ * Whether a camera-ready started from the accepted source: it keeps at least half of its lines. A
+ * camera-ready is what was accepted plus the changes the reviewers asked for, so it differs — any
+ * difference cannot be the test. One that keeps less than half was built from something else.
+ */
+export const derivesFrom = (l: Lineage): boolean => l.kept * 2 >= l.total;
+
+export const driftText = (d: Drift): string =>
+  `${String(d.added)} line${d.added === 1 ? "" : "s"} added, ${String(d.removed)} removed`;
+
+/** The venue of a cycle, as a person names it: the preset's spec, or the named venue. */
+/** A cycle's venue as a person names it: a named venue's name, a preset's name without its package or path. */
+export const venueName = (c: Cycle): string =>
+  c.venue.kind === "preset"
+    ? c.venue.extends
+        .replace(/^paperlint:/, "")
+        .replace(/^.*\//, "")
+        .replace(/\.jsonc?$/, "")
+    : c.venue.name;
+
+/**
+ * The frozen source the draft is measured against: the open cycle's `submitted.tex`, or — once the
+ * last cycle is accepted — its newest (`camera-ready.tex`, else `submitted.tex`); null between venues
+ * and before the first attempt. Pure over whether a file exists.
+ */
+export function driftBase(
+  current: Current,
+  has: (key: string) => boolean,
+): { readonly cycle: Cycle; readonly key: string } | null {
+  switch (current.kind) {
+    case "cycle":
+      return {
+        cycle: current.cycle,
+        key: frozenKey(current.cycle.id, "submitted", "tex"),
+      };
+    case "accepted": {
+      const camera = frozenKey(current.cycle.id, "camera-ready", "tex");
+      return {
+        cycle: current.cycle,
+        key: has(camera)
+          ? camera
+          : frozenKey(current.cycle.id, "submitted", "tex"),
+      };
+    }
+    case "parked":
+    case "none":
+      return null;
+  }
+}
+
+// ── each version's state ──────────────────────────────────────────────────────────────
+
+/** One row of the version → state table. */
+export interface VersionRow {
+  readonly version: string;
+  readonly stage: string;
+  readonly state: string;
+  readonly detail: string;
+}
+
+/** What a frozen stage of a cycle IS, from the cycle's outcome. Pure. */
+export function stateOf(c: Cycle, stage: VersionStage): string {
+  if (stage === "arxiv") return "arXiv copy";
+  switch (c.outcome.kind) {
+    case "open":
+      return stage === "submitted"
+        ? `CURRENT (under review at ${venueName(c)})`
+        : "camera-ready, cycle still open";
+    case "accepted":
+      return stage === "submitted" ? "camera-ready base" : "final";
+    case "rejected":
+    case "withdrawn":
+      return `historical (${c.outcome.kind})`;
+  }
+}
+
+/** `2026-10-23T16:58:01.000Z` → `2026-10-23 16:58 UTC`; a day stays a day. */
+const whenText = (frozen: string): string =>
+  frozen.length === 10
+    ? frozen
+    : `${frozen.slice(0, 10)} ${frozen.slice(11, 16)} UTC`;
+
+/** A PDF's lock entry as the table shows it (only a source can be recorded lost). */
+const entryDetail = (e: LockEntry | undefined): string =>
+  e === undefined || e.kind === "lost"
+    ? "not locked"
+    : `${String(e.bytes)} B  frozen ${whenText(e.frozen)}`;
+
+/** The stages a cycle has frozen: a PDF, a source, or a source the lock records as lost. */
+const frozenStages = (
+  c: Cycle,
+  has: (key: string) => boolean,
+  lock: Lock,
+): readonly VersionStage[] =>
+  VERSION_STAGES.filter(
+    (s) =>
+      has(frozenKey(c.id, s, "pdf")) ||
+      has(frozenKey(c.id, s, "tex")) ||
+      isLost(lock, frozenKey(c.id, s, "tex")),
+  );
+
+/** The row of a cycle that froze nothing: what it is, from its outcome. */
+const emptyRow = (c: Cycle): VersionRow => ({
+  version: c.id,
+  stage: "—",
+  state:
+    c.outcome.kind === "open"
+      ? "open, nothing sent yet"
+      : `${c.outcome.kind}, nothing frozen`,
+  detail: "",
+});
+
+/** A cycle's rows: one per stage frozen in its folder, or one saying what is missing or that nothing is. */
+function cycleRows(
+  c: Cycle,
+  has: (key: string) => boolean,
+  lock: Lock,
+): readonly VersionRow[] {
+  const stages = frozenStages(c, has, lock);
+  const unfrozen =
+    c.submission !== null && !stages.includes("submitted")
+      ? [
+          {
+            version: c.id,
+            stage: "submitted",
+            state: `NOT FROZEN — submission ${String(c.submission.id)} is on the portal`,
+            detail: "",
+          },
+        ]
+      : [];
+  const frozen = stages.map((s) => ({
+    version: c.id,
+    stage: s,
+    state: stateOf(c, s),
+    detail: [
+      entryDetail(lock[frozenKey(c.id, s, "pdf")]),
+      ...(isLost(lock, frozenKey(c.id, s, "tex")) ? ["source lost"] : []),
+    ].join(", "),
+  }));
+  const rows = [...unfrozen, ...frozen];
+  return rows.length > 0 ? rows : [emptyRow(c)];
+}
+
+/** What the draft row says about its drift from the base. */
+export type DraftDrift =
+  | { readonly kind: "none" }
+  | { readonly kind: "no-base"; readonly key: string }
+  | { readonly kind: "same"; readonly key: string }
+  | { readonly kind: "drift"; readonly key: string; readonly drift: Drift };
+
+const draftDetail = (d: DraftDrift): string => {
+  switch (d.kind) {
+    case "none":
+      return "no attempt to compare with";
+    case "no-base":
+      return `nothing frozen at ${d.key} to compare with`;
+    case "same":
+      return `same as ${d.key}`;
+    case "drift":
+      return `differs from ${d.key}: ${driftText(d.drift)}`;
+  }
+};
+
+/** The table: each cycle, newest first, then the draft. Pure. */
+export function versionRows(input: {
+  readonly cycles: readonly Cycle[];
+  readonly has: (key: string) => boolean;
+  readonly lock: Lock;
+  readonly draft: DraftDrift;
+}): readonly VersionRow[] {
+  return [
+    ...[...input.cycles]
+      .reverse()
+      .flatMap((c) => cycleRows(c, input.has, input.lock)),
+    {
+      version: "paper.tex",
+      stage: "draft",
+      state: "target not chosen",
+      detail: draftDetail(input.draft),
+    },
+  ];
+}
+
+/** The rows as aligned columns, two spaces in front. Pure. */
+export function versionTable(rows: readonly VersionRow[]): readonly string[] {
+  const width = (pick: (r: VersionRow) => string): number =>
+    Math.max(...rows.map((r) => pick(r).length));
+  const w = [
+    width((r) => r.version),
+    width((r) => r.stage),
+    width((r) => r.state),
+  ] as const;
+  return rows.map((r) =>
+    `  ${r.version.padEnd(w[0])}  ${r.stage.padEnd(w[1])}  ${r.state.padEnd(w[2])}  ${r.detail}`.trimEnd(),
+  );
+}
+
+// ── recording what is on disk ─────────────────────────────────────────────────────────
+
+/** A frozen file found on disk: its key and what it holds. */
+export interface OnDisk {
+  readonly key: string;
+  readonly facts: FileFacts;
+}
+
+/** What one found file does to the lock: kept as recorded, recorded anew, or recorded for the first time. */
+function relocked(
+  f: OnDisk,
+  old: LockEntry | undefined,
+  now: string,
+): { readonly entry: LockEntry; readonly line: string | null } {
+  const fresh: LockEntry = { kind: "file", ...f.facts, frozen: now };
+  if (old?.kind !== "file")
+    return {
+      entry: fresh,
+      line: `locked        versions/${f.key} (${String(f.facts.bytes)} bytes)`,
+    };
+  return old.sha256 === f.facts.sha256 && old.bytes === f.facts.bytes
+    ? { entry: old, line: null }
+    : {
+        entry: fresh,
+        line: `re-locked     versions/${f.key}: ${String(old.bytes)} → ${String(f.facts.bytes)} bytes — it changed after ${old.frozen}`,
+      };
+}
+
+/**
+ * `paperlint versions lock`: the lock for the files on disk — each kept as recorded, recorded when it
+ * is new or changed, an entry whose file is gone dropped, a lost source kept while no file replaces
+ * it — and a line per change. Pure.
+ */
+export function relock(
+  found: readonly OnDisk[],
+  old: Lock,
+  now: string,
+): { readonly lock: Lock; readonly lines: readonly string[] } {
+  const keys = found.map((f) => f.key);
+  const each = found.map((f) => ({
+    key: f.key,
+    ...relocked(f, old[f.key], now),
+  }));
+  const gone = Object.entries(old).filter(([k]) => !keys.includes(k));
+  return {
+    lock: {
+      ...Object.fromEntries(gone.filter(([, e]) => e.kind === "lost")),
+      ...Object.fromEntries(each.map((e) => [e.key, e.entry])),
+    },
+    lines: [
+      ...each.flatMap((e) => (e.line === null ? [] : [e.line])),
+      ...gone
+        .filter(([, e]) => e.kind === "file")
+        .map(([k]) => `dropped       versions/${k}: the file is gone`),
+    ],
+  };
+}