@panaversity/ksor 0.0.39 → 0.0.41

package/templates/scaffold/system/site/record/citations.ts

@@ -0,0 +1,312 @@
+/**
+ * What a concept's body says about other things: GFM footnotes (the one
+ * extension to CommonMark, record spec §2.3 — per-claim citation keyed on
+ * `sources[].id`) and links in both OKF §6.1 forms. The code-stripping is
+ * the scaffold checker's, carried because its two review findings (links in
+ * fenced and indented code checked as real; a document-wide span strip
+ * pairing stray backticks pages apart) are ours to keep closed.
+ */
+import type { Refusal } from "./refusal";
+
+const FOOTNOTE_REF = /\[\^([^\]\s]+)\](?!:)/g;
+const FOOTNOTE_DEF = /^[ \t]{0,3}\[\^([^\]\s]+)\]:/gm;
+
+/** Every footnote reference and definition must be keyed on a `sources[].id`. */
+export function checkFootnotes(
+  path: string,
+  body: string,
+  sourceIds: readonly string[],
+): Refusal[] {
+  const prose = stripCode(body);
+  const known = new Set(sourceIds);
+  const seen = new Set<string>();
+  const refusals: Refusal[] = [];
+  const report = (label: string, form: string): void => {
+    if (known.has(label) || seen.has(label)) return;
+    seen.add(label);
+    refusals.push({
+      slug: "ksor-footnote-unkeyed",
+      path,
+      why: `the footnote ${form} \`[^${label}]\` matches no \`sources[].id\` — a citation must trace to a declared source`,
+      fix: `add a source with \`id: ${label}\`, or change the label to one of: ${[...known].join(", ") || "(none declared)"}`,
+    });
+  };
+  for (const m of prose.matchAll(FOOTNOTE_DEF)) report(m[1] ?? "", "definition");
+  for (const m of prose.matchAll(FOOTNOTE_REF)) report(m[1] ?? "", "reference");
+  return refusals;
+}
+
+// The reference definitions that inline `[text][label]` links point at.
+const REFERENCE_DEFINITION =
+  /^[ \t]{0,3}\[[^\]^]+\]:[ \t]*(<[^<>\n]*>|\S+)[ \t]*(?:"[^"]*"|'[^']*'|\([^)]*\))?[ \t]*$/gm;
+
+/**
+ * Every inline destination in a body, scanned rather than matched, because
+ * link TEXT nests and a regex character class cannot.
+ *
+ * The class this replaces was `\[[^\]]*\]\(`, which stops at the FIRST `]`.
+ * On `[![chart](chart.png)](secret/plan.md)` it therefore saw the image and
+ * never the link around it — so a public document could point at a restricted
+ * target and escape `ksor-link-widens`, `ksor-link-dead` and
+ * `ksor-link-escapes` at once, silently, because no rule ever received the
+ * link. A plain `[the [2026] policy](hr/leave.md)` disappeared the same way.
+ * Both found in review, 2026-08-25.
+ *
+ * Every destination is reported, inner and outer: an image inside a link is
+ * one link with two targets, and BOTH are governed — the asset is staged and
+ * the destination decides the audience.
+ */
+function inlineDestinations(prose: string): string[] {
+  const found: string[] = [];
+  const open: number[] = [];
+  let i = 0;
+  while (i < prose.length) {
+    const ch = prose[i];
+    if (ch === "\\") {
+      i += 2;
+      continue;
+    }
+    if (ch === "[") {
+      open.push(i);
+      i += 1;
+      continue;
+    }
+    if (ch !== "]") {
+      i += 1;
+      continue;
+    }
+    // A `]` with no `[` before it is ordinary text, and so is one whose `(`
+    // never closes: neither names a destination, so neither is reported.
+    open.pop();
+    const parsed = prose[i + 1] === "(" ? destinationAt(prose, i + 2) : null;
+    if (parsed === null) {
+      i += 1;
+      continue;
+    }
+    found.push(parsed.target);
+    i = parsed.end;
+  }
+  return found;
+}
+
+/** The destination that starts just after `](`, or null when it does not close. */
+function destinationAt(prose: string, start: number): { target: string; end: number } | null {
+  let i = start;
+  while (i < prose.length && /\s/.test(prose[i] ?? "")) i += 1;
+  let target = "";
+  if (prose[i] === "<") {
+    const close = prose.indexOf(">", i + 1);
+    const newline = prose.indexOf("\n", i + 1);
+    if (close === -1 || (newline !== -1 && newline < close)) return null;
+    target = prose.slice(i, close + 1);
+    i = close + 1;
+  } else {
+    const from = i;
+    while (i < prose.length && !/[\s)]/.test(prose[i] ?? "")) i += 1;
+    target = prose.slice(from, i);
+    if (target === "") return null;
+  }
+  // An optional "double", 'single' or (paren) title, then the closing paren.
+  while (i < prose.length && /\s/.test(prose[i] ?? "")) i += 1;
+  const quote = prose[i];
+  if (quote === '"' || quote === "'" || quote === "(") {
+    const closer = quote === "(" ? ")" : quote;
+    const close = prose.indexOf(closer, i + 1);
+    if (close === -1) return null;
+    i = close + 1;
+    while (i < prose.length && /\s/.test(prose[i] ?? "")) i += 1;
+  }
+  if (prose[i] !== ")") return null;
+  return { target, end: i + 1 };
+}
+
+/** The record's own link destinations in a body: no scheme, no `//host`, no bare fragment. */
+export function linkTargets(body: string): string[] {
+  const prose = stripCode(body);
+  const raw: string[] = [];
+  raw.push(...inlineDestinations(prose));
+  for (const m of prose.matchAll(REFERENCE_DEFINITION)) raw.push(m[1] ?? "");
+  return raw
+    .map((t) => (t.startsWith("<") && t.endsWith(">") ? t.slice(1, -1).trim() : t))
+    .filter(
+      (t) =>
+        t !== "" && !t.startsWith("#") && !t.startsWith("//") && !/^[a-z][a-z0-9+.-]*:/i.test(t),
+    );
+}
+
+/**
+ * The bundle-relative id a link resolves to — bundle-absolute (`/x/y`,
+ * against `knowledge/`) or relative (against the source's directory), `.md`
+ * optional, fragment and trailing slash dropped. Null when it escapes the
+ * bundle.
+ */
+export function resolveLink(sourceId: string, target: string): string | null {
+  const raw = target.split("#")[0] ?? "";
+  let decoded = raw;
+  try {
+    decoded = decodeURIComponent(raw);
+  } catch {
+    // A malformed %-escape names nothing; it resolves to a path that does not exist.
+  }
+  const clean = decoded.replace(/\.md$/, "");
+  const base = clean.startsWith("/") ? [] : sourceId.split("/").slice(0, -1);
+  const segments = [...base];
+  for (const seg of clean.replace(/^\/+/, "").split("/")) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") {
+      if (segments.length === 0) return null;
+      segments.pop();
+      continue;
+    }
+    segments.push(seg);
+  }
+  return segments.join("/");
+}
+
+/**
+ * The column a line's first non-space character sits at, tabs advancing to the
+ * next four-column stop. CommonMark measures block structure in COLUMNS, and a
+ * tab-indented continuation paragraph is the same paragraph as a
+ * four-space-indented one.
+ */
+function indentOf(line: string): number {
+  let col = 0;
+  for (const ch of line) {
+    if (ch === " ") col += 1;
+    else if (ch === "\t") col += 4 - (col % 4);
+    else break;
+  }
+  return col;
+}
+
+const LIST_MARKER = /^[ \t]*([-*+]|\d{1,9}[.)])([ \t]*)(.?)/;
+/** `* * *` and `- - -`: a thematic break, which takes precedence over the item it looks like. */
+const THEMATIC_BREAK = /^[ \t]*([-*_])(?:[ \t]*\1){2,}[ \t]*$/;
+
+/**
+ * The column at which the list item this line opens holds its CONTENT, or null
+ * when the line opens no item. Everything indented to that column belongs to
+ * the item, and code inside the item starts four columns further right — which
+ * is the whole of why the indent below is measured against it.
+ */
+function itemContentColumn(line: string, indent: number): number | null {
+  if (THEMATIC_BREAK.test(line)) return null;
+  const m = LIST_MARKER.exec(line);
+  if (m === null) return null;
+  const marker = m[1] ?? "";
+  const spaces = m[2] ?? "";
+  const rest = m[3] ?? "";
+  // `-x` is a word, not a bullet: a marker is followed by space or line end.
+  if (spaces === "" && rest !== "") return null;
+  const after = indent + marker.length;
+  let padding = 0;
+  for (const ch of spaces) padding += ch === "\t" ? 4 - ((after + padding) % 4) : 1;
+  // One to four spaces of padding set the content column; five or more open an
+  // indented code block INSIDE the item, whose content starts one past the marker.
+  return rest === "" || padding > 4 ? after + 1 : after + padding;
+}
+
+const FENCE_OPEN = /^[ \t]*(`{3,}|~{3,})/;
+const FENCE_CLOSE = /^[ \t]*(`{3,}|~{3,})[ \t]*$/;
+
+/** The line closing a fence opened with `bar` inside a container at `content`, or null. */
+function fenceCloses(
+  lines: readonly string[],
+  from: number,
+  bar: string,
+  content: number,
+): number | null {
+  for (let i = from; i < lines.length; i += 1) {
+    const line = lines[i] ?? "";
+    const run = FENCE_CLOSE.exec(line)?.[1];
+    if (run === undefined) continue;
+    if (run[0] === bar[0] && run.length >= bar.length && indentOf(line) - content <= 3) return i;
+  }
+  return null;
+}
+
+/**
+ * Code is prose about links, never links. Strips fenced blocks (``` and ~~~),
+ * indented code, and code spans per paragraph — and NOTHING else, because a
+ * line this misreads as code is a line no rule judges. `checkFootnotes` and
+ * `checkLinks` both read what comes back, so anything wrongly swallowed here
+ * escapes `ksor-footnote-unkeyed`, `ksor-link-widens`, `ksor-link-dead` and
+ * `ksor-link-escapes` at once, silently — a public document pointing at a
+ * restricted one with nothing red. Two shapes did exactly that (review,
+ * 2026-08-25), and both are answered by reading indentation the way CommonMark
+ * does: from the CONTAINER's content column rather than the line start.
+ *
+ * Where the exact rule is out of reach the line is KEPT. A link checked inside
+ * something that was really code is a false refusal an author can see and fix;
+ * a link never checked is a governance hole nothing reports.
+ */
+export function stripCode(text: string): string {
+  const lines = text.replace(/\r\n?/g, "\n").split("\n");
+  const kept: string[] = [];
+  /** The content columns of the list items currently open, outermost first. */
+  const items: number[] = [];
+  let blank = true;
+  let indented = false;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i] ?? "";
+    if (line.trim() === "") {
+      blank = true;
+      kept.push(line);
+      continue;
+    }
+    const indent = indentOf(line);
+    const opens = itemContentColumn(line, indent);
+    // A block starting left of the open item's content leaves the item, and so
+    // does a new marker. A line that merely continues a paragraph — no blank
+    // before it, no marker of its own — is a lazy continuation and closes nothing.
+    while (items.length > 0 && indent < (items.at(-1) ?? 0) && (blank || opens !== null)) {
+      items.pop();
+    }
+    const content = items.at(-1) ?? 0;
+    const relative = indent - content;
+
+    // A fence opens up to three columns past its container's content, so a
+    // fenced sample inside a list item is still a fence.
+    const open = relative <= 3 ? FENCE_OPEN.exec(line)?.[1] : undefined;
+    if (open !== undefined) {
+      // An unclosed fence is a stray backtick run, not a block. The state used
+      // to survive to end of input, so ONE stray ``` in prose took every link
+      // and footnote after it out of both checks — half a document unjudged,
+      // with no signal at all. Only the line itself is dropped now, and dropped
+      // rather than kept so its backticks cannot pair with a later run in the
+      // code-span pass below.
+      const close = fenceCloses(lines, i + 1, open, content);
+      if (close !== null) {
+        i = close;
+      } else {
+        // That dropped line is still TEXT, so it ends whatever ran before it:
+        // an indented code block cannot interrupt a paragraph, and reading the
+        // next indented line as code would hide it all over again.
+        blank = false;
+        indented = false;
+      }
+      continue;
+    }
+    // Indented code starts four columns past the CONTAINER's content, never
+    // four past the line start: a four-space-indented continuation paragraph is
+    // what CommonMark REQUIRES inside a list item, and reading it as code hid
+    // its links from every rule. A marker line is never read as code, which
+    // only ever checks more.
+    if (relative >= 4 && opens === null) {
+      if (blank || indented) {
+        indented = true;
+        continue;
+      }
+    } else {
+      indented = false;
+    }
+    if (opens !== null) items.push(opens);
+    blank = false;
+    kept.push(line);
+  }
+  return kept
+    .join("\n")
+    .split(/\n{2,}/)
+    .map((paragraph) => paragraph.replace(/(`+)[^`]*?\1/g, " "))
+    .join("\n\n");
+}

package/templates/scaffold/system/site/record/frontmatter.ts

@@ -0,0 +1,134 @@
+/**
+ * Split a document into its YAML frontmatter and its body — with a real YAML
+ * parser. The line scanners it will replace (research/okf-native.md §1) could
+ * not read a nested `ksor:` block and failed silently on it.
+ */
+import { parseAllDocuments, YAMLParseError } from "yaml";
+
+import type { Refusal } from "./refusal";
+import { firstNonPlain, isPlainMapping } from "./yaml-file";
+
+export type Split =
+  | {
+      readonly ok: true;
+      readonly frontmatter: Readonly<Record<string, unknown>> | null;
+      /** The YAML between the fences, byte-exact and comments intact — what `ksor migrate` rewrites. */
+      readonly block: string;
+      readonly body: string;
+    }
+  | { readonly ok: false; readonly refusal: Refusal };
+
+const SLUG = "ksor-frontmatter-invalid";
+/** A fence line: three dashes, trailing blanks tolerated, on the opening and the closing line alike. */
+const FENCE = /^---[ \t]*$/;
+
+/**
+ * An editor's byte-order mark is invisible to the author; CR and CRLF are the
+ * checkout's, not the record's. The BOM is why this runs before the fence is
+ * looked for at all: a BOM-prefixed file whose opening fence is therefore not
+ * at byte 0 reads as having no frontmatter, and serves its YAML as content
+ * (review finding, 2026-08-19).
+ */
+export function normalizeText(text: string): string {
+  return text.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+}
+
+/**
+ * `frontmatter` is null when the text has no fence at all, `{}` for an empty
+ * block. The body is everything after the closing fence's newline, byte-exact.
+ *
+ * The block ends at the first fence LINE after the opening one — found by
+ * walking real `\n` boundaries, never a multiline regex, because JS `^`/`$`
+ * also break on U+2028/U+2029 and YAML 1.2 does not (found in review: a scalar
+ * containing U+2028 was cut mid-line and the real fence published as body).
+ * The consequence is a rule of the profile: a frontmatter may not contain a
+ * bare `---` line, block scalars included (record spec §2).
+ */
+export function splitFrontmatter(text: string, path: string): Split {
+  const normalized = normalizeText(text);
+  const lines = normalized.split("\n");
+  if (!FENCE.test(lines[0] ?? "")) {
+    return { ok: true, frontmatter: null, block: "", body: normalized };
+  }
+  const closeAt = lines.findIndex((line, i) => i > 0 && FENCE.test(line));
+  if (closeAt === -1) {
+    return refuse(
+      path,
+      "the frontmatter opens with `---` but no closing `---` line follows",
+      "add a `---` line after the last frontmatter key",
+    );
+  }
+  const block = lines.slice(1, closeAt).join("\n");
+  const body = lines.slice(closeAt + 1).join("\n");
+
+  let value: unknown;
+  try {
+    const docs = parseAllDocuments(block, {
+      schema: "core",
+      uniqueKeys: true,
+      logLevel: "silent",
+    });
+    if (docs.length > 1) {
+      return refuse(
+        path,
+        "the frontmatter is not valid YAML: a second document marker (`---` or `...`) sits inside the block",
+        "one document per frontmatter — remove the marker",
+      );
+    }
+    const doc = docs[0];
+    const problem = doc?.errors[0] ?? doc?.warnings[0];
+    if (problem !== undefined) throw problem;
+    value = doc?.toJS();
+  } catch (error) {
+    return refuse(
+      path,
+      `the frontmatter is not valid YAML: ${reasonOf(error)}`,
+      "fix the YAML — a stray colon, an unclosed bracket, a duplicated key, tab indentation or an unknown `!!tag` are the usual causes",
+    );
+  }
+  if (value === null || value === undefined) return { ok: true, frontmatter: {}, block, body };
+  if (!isPlainMapping(value)) {
+    return refuse(
+      path,
+      "the frontmatter is not a mapping (a list or a bare scalar was found)",
+      "write `key: value` pairs between the fences",
+    );
+  }
+  const tagged = firstNonPlain(value, "");
+  if (tagged !== null) {
+    return refuse(
+      path,
+      `the frontmatter value at \`${tagged}\` is not plain data — a \`!!tag\` turned it into something no reader expects`,
+      "write strings, numbers, booleans, lists and mappings only; timestamps stay quoted strings",
+    );
+  }
+  return { ok: true, frontmatter: value, block, body };
+}
+
+/** The message as an author reads it: the first line, minus any `SomeError:` class prefix. */
+function reasonOf(error: unknown): string {
+  const first = error instanceof YAMLParseError ? error.message : String(error);
+  return first.split("\n")[0]?.replace(/^\w*Error: /, "") ?? "unreadable";
+}
+
+function refuse(path: string, why: string, fix: string): Split {
+  return { ok: false, refusal: { slug: SLUG, path, why, fix } };
+}
+
+/**
+ * The document's frontmatter as the file holds it — the bytes between the
+ * fences, unparsed — or null when it has none or an unclosed one.
+ *
+ * The markdown twin serves this INTACT rather than a re-serialisation of the
+ * parsed object, and so does the door's `read` tool: the profile preserves
+ * unknown keys (record spec §2.6), and anything this codebase re-emits can
+ * only carry the keys it thought of. It
+ * reads the block `splitFrontmatter` already found, so there is exactly one
+ * walk deciding where a fence ends — a second one that disagreed would
+ * publish a different document from the one the checker read.
+ */
+export function frontmatterText(text: string): string | null {
+  const split = splitFrontmatter(text, "(twin)");
+  if (!split.ok || split.frontmatter === null) return null;
+  return split.block;
+}

package/templates/scaffold/system/site/record/git-ledger.ts

@@ -0,0 +1,171 @@
+/**
+ * The takedown ledger's OTHER baseline: every entry any COMMITTED version of
+ * `.ksor/takedowns.yaml` has ever carried.
+ *
+ * The committed lock is a baseline too, and a good one — it holds each entry's
+ * digest, so an entry retargeted in place is caught. What it cannot do is prove
+ * that an entry was never deleted, because the lock travels in the SAME change
+ * as the ledger: delete the row, recompute `ledger_sha256`, empty
+ * `ledger_entries`, and the two agree with each other about a denial that is
+ * gone. Only history remembers.
+ *
+ * The baseline may be INCOMPLETE only if it SAYS so: every version history
+ * holds is read, or `entries` comes back null and the caller reports that it
+ * could not verify. A version silently skipped would contribute neither
+ * digests nor ids while the answer still read "verified"
+ * (`git-ledger.integration.test.ts`).
+ *
+ * This lives in the record module because THREE surfaces need the same answer —
+ * `ksor build`, the emitted checker, and the site's stage (decision 19: a
+ * surface that refuses must refuse on both surfaces). Plain `git log` / `git
+ * show`, so nothing here needs installing.
+ */
+import { spawnSync } from "node:child_process";
+
+import { entryDigest, parseLedger, type LedgerBaselineEntry } from "./ledger";
+
+const LEDGER = ".ksor/takedowns.yaml";
+
+export interface HistoricLedger {
+  /** False outside any repository, and false without a git binary. */
+  readonly repository: boolean;
+  readonly shallow: boolean;
+  /** Null when history could not be read; empty in a repository with no commit. */
+  readonly entries: readonly LedgerBaselineEntry[] | null;
+  /**
+   * Why `entries` is null, in the caller's words. Two different states reached
+   * one refusal that asserted "this is a shallow clone" as fact — a diagnosis
+   * stated for a state nobody distinguished (27352a4).
+   */
+  readonly unreadable: "shallow" | "unreadable" | null;
+}
+
+/**
+ * `spawnSync` defaults to a 1 MB stdout buffer, and past it the child is KILLED
+ * — `status` comes back null, so the query reads as a failure. A ledger with a
+ * few thousand entries, or one entry carrying a long reason, clears 1 MB
+ * easily, and the version was then dropped from the baseline while the caller
+ * was still told history had been verified. The ceiling stays finite on
+ * purpose: past it this returns null, which is a state the caller SAYS.
+ */
+const MAX_BUFFER = 64 * 1024 * 1024;
+
+/** One git query, read-only. Null on any non-zero exit, including no git at all. */
+export function git(root: string, args: readonly string[]): string | null {
+  const r = spawnSync("git", [...args], { cwd: root, encoding: "utf8", maxBuffer: MAX_BUFFER });
+  return r.status === 0 ? r.stdout : null;
+}
+
+export function historicLedger(root: string): HistoricLedger {
+  const inside = git(root, ["rev-parse", "--is-inside-work-tree"]);
+  if (inside === null || inside.trim() !== "true") {
+    return { repository: false, shallow: false, entries: null, unreadable: null };
+  }
+  const shallow = (git(root, ["rev-parse", "--is-shallow-repository"]) ?? "").trim() === "true";
+  // `ksor init` runs `git init`, so a fresh scaffold IS a repository — with no
+  // commit in it. `git log` exits non-zero there, which read as "history is
+  // unreadable" and refused the first build an adopter ever runs with a message
+  // about a shallow clone (found live). A repository with no commits has no
+  // history for a ledger id to disappear from, so its baseline is empty and
+  // verified, not missing.
+  const born = git(root, ["rev-parse", "--verify", "--quiet", "HEAD"]) !== null;
+  const entries = shallow ? null : born ? historicEntries(root) : [];
+  return {
+    repository: true,
+    shallow,
+    entries,
+    unreadable: entries !== null ? null : shallow ? "shallow" : "unreadable",
+  };
+}
+
+/**
+ * Every id history has ever recorded, each with the text it carried the FIRST
+ * time it was written. A version that parses contributes each entry's digest,
+ * so an entry EDITED in place is caught, not only one deleted; a version that
+ * no longer parses still contributes its ids, read permissively — the point
+ * there is that an id once written never disappears.
+ *
+ * FIRST, not every: keying this by `id\tdigest` kept one baseline entry per
+ * version an id ever had, so a tamper that was COMMITTED and then UNDONE left
+ * two digests for one id, the restored entry matched only one of them, and
+ * `ksor-ledger-amended` fired for good. The record became permanently
+ * unbuildable — by a tamper that had already been put right — and the only
+ * escape was rewriting git history, which is not a remedy a refusal may
+ * demand (found in review, 2026-08-25).
+ *
+ * Taking the OLDEST is what makes the guarantee both enforceable and
+ * escapable. It still refuses a committed tamper (the baseline is what the
+ * entry said when it was written, so committing the edit does not launder
+ * it), and the remedy it names — put the entry back — now actually clears
+ * it. Taking the NEWEST would have done the opposite on both counts.
+ */
+function historicEntries(root: string): readonly LedgerBaselineEntry[] | null {
+  // TWO paths for one file, because git means two different things by "path"
+  // here and each call is right on its own:
+  //
+  //   `git show <rev>:<path>` and `ls-tree --full-tree` read a path relative to
+  //   the REPOSITORY ROOT — hence `atRoot`, built from `--show-prefix`.
+  //
+  //   a `git log -- <pathspec>` is relative to the CWD, and the cwd is already
+  //   the record root — hence `LEDGER`, bare.
+  //
+  // Prefixing both asked `git log` for `docs-sor/docs-sor/.ksor/takedowns.yaml`
+  // whenever a record sat below its repository root, which is an ordinary
+  // shape. A pathspec matching nothing is not an ERROR: `git log` exits 0 and
+  // prints nothing, so the baseline came back EMPTY and non-null — verified,
+  // holding nothing — and a deleted denial republished with the build exiting
+  // 0. Every case in the test file was `mkdtemp` + `git init` in ONE directory,
+  // where the prefix is always empty, so no number of cases in that shape could
+  // have caught it (found in review, 2026-08-25).
+  const prefix = (git(root, ["rev-parse", "--show-prefix"]) ?? "").trim();
+  const atRoot = `${prefix}${LEDGER}`;
+  // `--full-history` because `git log -- <path>` SIMPLIFIES by default: a merge
+  // TREESAME to a parent is followed through that parent alone, so a branch
+  // whose net effect on the ledger was nil is pruned whole — a denial added and
+  // withdrawn inside one pull request never entered the baseline, and
+  // `ksor-ledger-shrank` could not fire for it. That is precisely the deletion
+  // the committed lock cannot catch either, since the lock travels in the same
+  // pull request; if history does not remember it, nothing does.
+  //
+  // `--topo-order` because the walk below lets an OLDER version overwrite a
+  // newer one, and across branches the default ordering is by commit DATE,
+  // which need not follow ancestry. Topological order does, so "oldest" means
+  // the ancestor rather than whichever machine's clock was behind.
+  const commits = git(root, ["log", "--full-history", "--topo-order", "--format=%H", "--", LEDGER]);
+  if (commits === null) return null;
+  const seen = new Map<string, LedgerBaselineEntry>();
+  for (const sha of commits.split("\n").filter((s) => s !== "")) {
+    const text = git(root, ["show", `${sha}:${atRoot}`]);
+    if (text === null) {
+      // `git show` failing means one of two things, and they used to be one
+      // silent `continue`: the commit DELETED the ledger (expected — it has no
+      // version to contribute), or the bytes could not be read (a killed query,
+      // a missing object). `ls-tree` separates them — it exits 0 either way and
+      // prints nothing when the path is absent — so an unreadable version stops
+      // being counted as a verified empty one. Asked only on failure, so the
+      // ordinary walk still costs one git call per commit.
+      const listed = git(root, ["ls-tree", "--full-tree", "--name-only", sha, "--", atRoot]);
+      if (listed !== null && listed.trim() === "") continue;
+      return null;
+    }
+    const where = sha.slice(0, 7);
+    const parsed = parseLedger(text, LEDGER);
+    // The walk is newest-first in topological order, so an OLDER version
+    // overwriting a newer one leaves the oldest — the text the id was written
+    // with.
+    if (parsed.ok) {
+      for (const entry of parsed.ledger.entries) {
+        seen.set(entry.id, { id: entry.id, digest: entryDigest(entry), entry, where });
+      }
+      continue;
+    }
+    for (const m of text.matchAll(/^\s*(?:-\s+)?id:\s*["']?([^\s"']+)/gm)) {
+      const id = m[1] ?? "";
+      // Presence only, and never over a digest: a version that stopped
+      // parsing proves the id existed, and proves nothing about its text, so
+      // it must not erase what an older readable version already said.
+      if (!seen.has(id)) seen.set(id, { id, digest: null, where });
+    }
+  }
+  return [...seen.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}