projectkeeper 0.0.0-stage → 1.0.0

package/src/ledger/docs.ts

@@ -0,0 +1,294 @@
+/**
+ * Document versions (Spec §1.16 row 2; CKC-22 AC-3, AC-15): every version of every document in the history (documents
+ * as `isDocumentPath` of sources/history.ts defines them) with the commit and time it lives at; adds, renames, copies and
+ * deletions; which Markdown sections (by heading path) the version added, removed or changed against the version before
+ * it; the cleanup commits that delete many documents at once, with the document catalogue before and after; and for a
+ * deleted document the commit whose tree still has its full text.
+ *
+ * "The version before it" is the content the commit changed — its first parent's version of the same document (for a
+ * rename, of the old path) — so the section diff is exactly what that commit did, on whichever branch it was made.
+ * Contents are stored once per distinct content (`blob:<repo>:<id>` in the searchable texts).
+ *
+ * Import-style root commit (AC-15), the rule: a commit without parents that adds at least `IMPORT_MIN_DOCS` documents, and
+ * either one of those documents states a full date earlier than the commit's own day (so the content existed before it
+ * entered version control), or its message says it puts existing material under version control. Its content is not dated
+ * by the commit: see `occurredOfLine`.
+ */
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import type { DatabaseSync } from 'node:sqlite';
+import { isDocumentPath } from '../sources/history.ts';
+import { splitMarkdown } from '../sources/files.ts';
+import { blobTextKey, cleanupKey, delKey, docKey, getText, putText, tx } from './schema.ts';
+import { catBlobs, isText, treeFiles } from './git-read.ts';
+import { dateContext, dayOf, fullDatesIn, materialTime, occurred, undated, type DateContext, type Occurred } from './time.ts';
+import type { RepoHandle } from './repo-scan.ts';
+
+/** A cleanup commit deletes at least this many documents in one commit. */
+export const CLEANUP_MIN_DOCS = 5;
+/** An import-style root commit adds at least this many documents. */
+export const IMPORT_MIN_DOCS = 5;
+/** Words of a message that says existing material is being put under version control. */
+export const IMPORT_MESSAGE = /\b(import(?:ed|ing)?|under version control|into (?:git|version control)|initial import|existing (?:files|material|documents))\b|纳入(?:版本管理|git|版本控制)|导入|迁入|入库/i;
+/** Content larger than this is recorded as a version (size, sections unknown) without its text. */
+export const MAX_DOC_BYTES = 4_000_000;
+
+export const IMPORT_RULE = `A root commit (no parents) that adds at least ${IMPORT_MIN_DOCS} documents, where one of them states a full date earlier than the commit's own day, or whose message says it puts existing material under version control. Its content is dated by the date written in the text (the line's own date, else its entry's 日期/date line, else the entry heading's date, else the document's stated date); else by the file's time in the working tree (File time, a weak basis: copying and moving change it); else Undated · first seen at the import commit.`;
+export const CLEANUP_RULE = `One commit that deletes at least ${CLEANUP_MIN_DOCS} documents (a move is not a deletion).`;
+
+export interface DocScanStats {
+  readonly versions: number;
+  readonly versionsAdded: number;
+  readonly withoutText: number;
+  /** The versions this scan recorded without their text (over `MAX_DOC_BYTES`, or not text), so the rebuild says which. */
+  readonly withoutTextPaths?: readonly { readonly path: string; readonly commit: string; readonly bytes: number }[];
+  readonly deleted: number;
+  readonly cleanups: number;
+  readonly importRoots: number;
+}
+
+const CHANGE: Record<string, string> = { A: 'Added', M: 'Modified', R: 'Renamed', C: 'Copied', T: 'Type changed' };
+
+/** The key of a section by its heading path, before a heading path used twice is told apart (`sectionMap`). */
+export const sectionBase = (headingPath: readonly string[]): string => (headingPath.length ? headingPath.join(' › ') : '(before the first heading)');
+
+/** One section of a document with the key `sectionMap` and `diffSections` give it, and where it stands. */
+export interface KeyedSection {
+  readonly key: string;
+  readonly base: string;
+  readonly headingPath: readonly string[];
+  readonly lineStart: number;
+  readonly lineEnd: number;
+  /** The section as written, heading line included. */
+  readonly text: string;
+  /** What `sectionMap` compares: the section without its heading line, trimmed. */
+  readonly body: string;
+}
+
+/** A document's sections in order, keyed as `sectionMap` keys them (a heading path used twice gets ` #2`). */
+export function keyedSections(text: string): KeyedSection[] {
+  const out: KeyedSection[] = [];
+  const used = new Set<string>();
+  for (const s of splitMarkdown(text)) {
+    const base = sectionBase(s.headingPath);
+    let key = base;
+    for (let n = 2; used.has(key); n++) key = `${base} #${n}`;
+    used.add(key);
+    const body = s.text.split(/\r?\n/).slice(s.headingPath.length ? 1 : 0).join('\n').trim();
+    out.push({ key, base, headingPath: s.headingPath, lineStart: s.lineStart, lineEnd: s.lineEnd, text: s.text, body });
+  }
+  return out;
+}
+
+/** Heading path → section text; a heading path used twice in one document is told apart by its position (` #2`). */
+export function sectionMap(text: string): Map<string, string> {
+  return new Map(keyedSections(text).map((s) => [s.key, s.body]));
+}
+
+export function diffSections(before: string | null, after: string): { added: string[]; removed: string[]; changed: string[] } {
+  const a = before === null ? new Map<string, string>() : sectionMap(before);
+  const b = sectionMap(after);
+  const added: string[] = [];
+  const removed: string[] = [];
+  const changed: string[] = [];
+  for (const [k, v] of b) {
+    if (!a.has(k)) added.push(k);
+    else if (a.get(k) !== v) changed.push(k);
+  }
+  for (const k of a.keys()) if (!b.has(k)) removed.push(k);
+  return { added, removed, changed };
+}
+
+const lineCount = (text: string): number => (text.length === 0 ? 0 : text.split(/\r?\n/).length - (text.endsWith('\n') ? 1 : 0));
+
+// ───────────────────────── when a line of a document happened ─────────────────────────
+
+export interface VersionTime {
+  readonly commit: string;
+  readonly commitAt: string;
+  readonly importRoot: boolean;
+  readonly path: string;
+  readonly firstSeen: string;
+  /** The file's time in the working tree, read for import-root content only (`versionTime`). */
+  readonly fileTime: string | null;
+}
+
+/** What dates the lines of one version: its commit, and for import-root content the file's time now. */
+export function versionTime(repoPath: string, path: string, commit: string, commitAt: string, importRoot: boolean, firstSeen: string): VersionTime {
+  return { commit, commitAt, importRoot, path, firstSeen, fileTime: importRoot ? fileTimeOf(repoPath, path) : null };
+}
+
+/**
+ * When a line of a document version happened (§2.11, AC-15). A version made by an ordinary commit: the commit's author
+ * time (`Commit`), with the date written in the text kept as `other` (the table of §2.11: "另记"). With `line` null, the
+ * date the document states for itself (rule 4 of time.ts) is the one written in the text. Content of an import-style
+ * root commit: the written date (`Written in text`) with the import commit as `other`; else the file's time in the working
+ * tree (`File time`); else `Undated · first seen`.
+ */
+export function occurredOfLine(v: VersionTime, dates: DateContext, line: number | null): Occurred {
+  const anchor = `${v.path}@${v.commit.slice(0, 10)}${line ? `:${line}` : ''}`;
+  const written = line === null ? dates.document : dates.at(line);
+  const commitAt = materialTime(v.commitAt) ?? v.commitAt;
+  if (!v.importRoot) {
+    return occurred(commitAt, 'Commit', anchor, written ? { at: written.at, basis: 'Written in text', anchor: `${v.path}:${written.line}` } : null);
+  }
+  const imported = { at: commitAt, basis: 'Commit' as const, anchor: `${v.commit.slice(0, 10)} (import commit)` };
+  if (written) return { at: written.at, basis: 'Written in text', anchor: `${v.path}:${written.line}`, other: imported };
+  if (v.fileTime) return { at: v.fileTime, basis: 'File time', anchor: v.path, other: imported };
+  return { ...undated(v.firstSeen, anchor), other: imported };
+}
+
+function fileTimeOf(root: string, rel: string): string | null {
+  try {
+    const st = statSync(join(root, ...rel.split('/')));
+    return st.isFile() ? st.mtime.toISOString() : null;
+  } catch {
+    return null;
+  }
+}
+
+// ───────────────────────── the scan ─────────────────────────
+
+interface Change {
+  readonly hash: string; readonly status: string; readonly path: string; readonly old_path: string | null;
+  readonly old_blob: string | null; readonly new_blob: string | null;
+  readonly author_at: string; readonly author_ms: number; readonly parents: string; readonly import_root: number; readonly subject: string; readonly body: string;
+}
+
+/** Decide import-style root commits among the repository's root commits not decided yet (the rule above). */
+function decideImportRoots(db: DatabaseSync, repo: RepoHandle, contentOf: (blob: string) => string | null): number {
+  const decided = db.prepare("SELECT value FROM state WHERE key = ?").get(`importRoots:${repo.id}`) as { value: string } | undefined;
+  const done = new Set<string>(decided ? (JSON.parse(decided.value) as string[]) : []);
+  const roots = db.prepare("SELECT hash, author_at, subject, body FROM commits WHERE repo = ? AND parents = ''").all(repo.id) as { hash: string; author_at: string; subject: string; body: string }[];
+  let n = 0;
+  for (const r of roots) {
+    if (done.has(r.hash)) continue;
+    done.add(r.hash);
+    const adds = (db.prepare("SELECT path, new_blob FROM commit_files WHERE repo = ? AND hash = ? AND status = 'A'").all(repo.id, r.hash) as { path: string; new_blob: string | null }[])
+      .filter((f) => isDocumentPath(f.path) && f.new_blob);
+    if (adds.length < IMPORT_MIN_DOCS) continue;
+    // The author's own day (the commit time as git wrote it, with its offset).
+    const day = dayOf(r.author_at) ?? '';
+    const earlier = adds.some((f) => { const t = contentOf(f.new_blob!); return t !== null && fullDatesIn(t).some((d) => d < day); });
+    if (earlier || IMPORT_MESSAGE.test(`${r.subject}\n${r.body}`)) {
+      db.prepare('UPDATE commits SET import_root = 1 WHERE repo = ? AND hash = ?').run(repo.id, r.hash);
+      n += 1;
+    }
+  }
+  db.prepare('INSERT OR REPLACE INTO state (key, value) VALUES (?, ?)').run(`importRoots:${repo.id}`, JSON.stringify([...done]));
+  return n;
+}
+
+export function scanDocs(db: DatabaseSync, repo: RepoHandle, now: string): DocScanStats {
+  const changes = (db.prepare(`
+    SELECT cf.hash, cf.status, cf.path, cf.old_path, cf.old_blob, cf.new_blob, c.author_at, c.author_ms, c.parents, c.import_root, c.subject, c.body
+    FROM commit_files cf JOIN commits c ON c.repo = cf.repo AND c.hash = cf.hash
+    WHERE cf.repo = ? AND (
+      (cf.status <> 'D' AND NOT EXISTS (SELECT 1 FROM docs d WHERE d.repo = cf.repo AND d.path = cf.path AND d.commit_hash = cf.hash))
+      OR (cf.status = 'D' AND NOT EXISTS (SELECT 1 FROM deleted_docs x WHERE x.repo = cf.repo AND x.path = cf.path AND x.deleted_commit = cf.hash)))
+    ORDER BY c.author_ms, cf.hash`).all(repo.id) as unknown as Change[])
+    .filter((ch) => isDocumentPath(ch.path));
+
+  // Contents: what the searchable texts already hold is not read again.
+  const wantedBlobs = new Set<string>();
+  const have = (blob: string) => db.prepare('SELECT 1 FROM texts WHERE key = ?').get(blobTextKey(repo.id, blob)) !== undefined;
+  for (const ch of changes) {
+    if (ch.new_blob && ch.status !== 'D' && !have(ch.new_blob)) wantedBlobs.add(ch.new_blob);
+    if (ch.old_blob && (ch.status === 'M' || ch.status === 'R' || ch.status === 'C' || ch.status === 'T') && !have(ch.old_blob)) wantedBlobs.add(ch.old_blob);
+  }
+  // Root commits' added documents, for the import rule, are among the new blobs already.
+  const fetched = catBlobs(repo.path, [...wantedBlobs]);
+  const texts = new Map<string, string | null>();
+  const contentOf = (blob: string | null): string | null => {
+    if (!blob) return null;
+    if (texts.has(blob)) return texts.get(blob)!;
+    const stored = getText(db, blobTextKey(repo.id, blob));
+    if (stored !== null) { texts.set(blob, stored); return stored; }
+    const buf = fetched.get(blob);
+    const t = buf && buf.length <= MAX_DOC_BYTES && isText(buf) ? buf.toString('utf8') : null;
+    texts.set(blob, t);
+    return t;
+  };
+
+  const importRoots = tx(db, () => decideImportRoots(db, repo, contentOf));
+  const isImport = new Set((db.prepare('SELECT hash FROM commits WHERE repo = ? AND import_root = 1').all(repo.id) as { hash: string }[]).map((r) => r.hash));
+
+  const insDoc = db.prepare(`INSERT OR IGNORE INTO docs (key, repo, path, commit_hash, blob, prev_blob, prev_path, at, at_ms, change, sections, bytes, lines, import_root, added, removed, changed)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+  const insDel = db.prepare(`INSERT OR IGNORE INTO deleted_docs (key, repo, path, deleted_commit, deleted_at, deleted_ms, readable_at, blob, cleanup)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0)`);
+  let versionsAdded = 0;
+  let withoutText = 0;
+  const withoutTextPaths: { path: string; commit: string; bytes: number }[] = [];
+  let deleted = 0;
+  const deletionsByCommit = new Map<string, number>();
+  tx(db, () => {
+    for (const ch of changes) {
+      const at = materialTime(ch.author_at) ?? ch.author_at;
+      if (ch.status === 'D') {
+        const readable = ch.parents.split(' ').filter(Boolean)[0] ?? null;
+        if (insDel.run(delKey(ch.path, ch.hash), repo.id, ch.path, ch.hash, at, ch.author_ms, readable, ch.old_blob).changes > 0) {
+          deleted += 1;
+          deletionsByCommit.set(ch.hash, (deletionsByCommit.get(ch.hash) ?? 0) + 1);
+        }
+        continue;
+      }
+      if (!ch.new_blob) continue;
+      const text = contentOf(ch.new_blob);
+      if (text !== null) putText(db, blobTextKey(repo.id, ch.new_blob), 'doc', repo.id, text);
+      else {
+        withoutText += 1;
+        withoutTextPaths.push({ path: ch.path, commit: ch.hash, bytes: fetched.get(ch.new_blob)?.length ?? 0 });
+      }
+      const prevBlob = ch.status === 'A' ? null : ch.old_blob;
+      const prevPath = ch.status === 'R' || ch.status === 'C' ? ch.old_path : ch.status === 'A' ? null : ch.path;
+      const before = prevBlob ? contentOf(prevBlob) : null;
+      if (prevBlob && before !== null) putText(db, blobTextKey(repo.id, prevBlob), 'doc', repo.id, before);
+      const diff = text === null ? null : diffSections(before, text);
+      const w = insDoc.run(docKey(ch.path, ch.hash), repo.id, ch.path, ch.hash, ch.new_blob, prevBlob, prevPath, at, ch.author_ms,
+        CHANGE[ch.status] ?? 'Modified', text === null ? 0 : splitMarkdown(text).length, fetched.get(ch.new_blob)?.length ?? Buffer.byteLength(text ?? ''),
+        text === null ? 0 : lineCount(text), isImport.has(ch.hash) ? 1 : 0,
+        diff ? JSON.stringify(diff.added) : null, diff ? JSON.stringify(diff.removed) : null, diff ? JSON.stringify(diff.changed) : null);
+      if (w.changes > 0) versionsAdded += 1;
+    }
+  });
+
+  // Cleanup commits: one commit deleting at least CLEANUP_MIN_DOCS documents; the catalogue before and after.
+  let cleanups = 0;
+  const bigDeletions = db.prepare(`SELECT deleted_commit h, count(*) n FROM deleted_docs WHERE repo = ? GROUP BY deleted_commit HAVING n >= ?`).all(repo.id, CLEANUP_MIN_DOCS) as { h: string; n: number }[];
+  for (const { h, n } of bigDeletions) {
+    if (db.prepare('SELECT 1 FROM cleanups WHERE repo = ? AND commit_hash = ?').get(repo.id, h)) continue;
+    const c = db.prepare('SELECT parents, author_at, author_ms FROM commits WHERE repo = ? AND hash = ?').get(repo.id, h) as { parents: string; author_at: string; author_ms: number } | undefined;
+    if (!c) continue;
+    const parent = c.parents.split(' ').filter(Boolean)[0] ?? null;
+    const docsAt = (ref: string) => treeFiles(repo.path, ref).filter((f) => isDocumentPath(f.path)).map((f) => f.path);
+    const total = (db.prepare('SELECT count(*) c FROM commit_files WHERE repo = ? AND hash = ? AND status = ?').get(repo.id, h, 'D') as { c: number }).c;
+    tx(db, () => {
+      db.prepare(`INSERT OR IGNORE INTO cleanups (key, repo, commit_hash, at, at_ms, deleted_docs, deleted_total, catalog_before, catalog_after) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(cleanupKey(h), repo.id, h, materialTime(c.author_at) ?? c.author_at, c.author_ms, n, total, JSON.stringify(parent ? docsAt(parent) : []), JSON.stringify(docsAt(h)));
+      db.prepare('UPDATE deleted_docs SET cleanup = 1 WHERE repo = ? AND deleted_commit = ?').run(repo.id, h);
+    });
+    cleanups += 1;
+  }
+  void now;
+  void deletionsByCommit;
+  const versions = (db.prepare('SELECT count(*) c FROM docs WHERE repo = ?').get(repo.id) as { c: number }).c;
+  return { versions, versionsAdded, withoutText, withoutTextPaths, deleted, cleanups, importRoots };
+}
+
+/** Where a version's text is: the ledger's own copy of its content. */
+export function versionText(db: DatabaseSync, repo: string, blob: string): string | null {
+  return getText(db, blobTextKey(repo, blob));
+}
+
+/** The dates written in a version's text, read once per content. */
+const contexts = new Map<string, DateContext>();
+export function datesOf(key: string, text: string): DateContext {
+  let c = contexts.get(key);
+  if (!c) {
+    if (contexts.size > 2000) contexts.clear();
+    c = dateContext(text);
+    contexts.set(key, c);
+  }
+  return c;
+}

package/src/ledger/git-read.ts

@@ -0,0 +1,321 @@
+/**
+ * The ledger's git reads (CKC-22; Spec §1.16). Everything here only reads, and runs as
+ * `git -C <dir> --no-optional-locks …` with the owner's display settings switched off, so observing a repository never
+ * changes it (Spec §1.1) and a local git setting (colour, no rename detection, a pager) cannot change what is read. No
+ * network: no fetch, pull or remote query — only what the repository already has.
+ */
+import { execFileSync } from 'node:child_process';
+import { canonicalPath } from '../util/paths.ts';
+
+export interface GitOut { readonly ok: boolean; readonly out: string; readonly err: string }
+
+function env(): NodeJS.ProcessEnv {
+  const copy: NodeJS.ProcessEnv = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!['GIT_PAGER', 'PAGER', 'GIT_EXTERNAL_DIFF', 'GIT_OPTIONAL_LOCKS', 'GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE'].includes(key.toUpperCase())) copy[key] = value;
+  }
+  copy.GIT_OPTIONAL_LOCKS = '0';
+  copy.GIT_TERMINAL_PROMPT = '0';
+  return copy;
+}
+
+/** Settings that decide what git prints; fixed so the owner's configuration cannot change what the ledger reads. */
+const FIXED = [
+  '--no-pager', '-c', 'core.fsmonitor=false', '-c', 'core.quotePath=false', '-c', 'color.ui=false', '-c', 'log.showRoot=true',
+  '-c', 'diff.renames=true', '-c', 'diff.noprefix=false', '-c', 'log.decorate=false', '-c', 'log.showSignature=false',
+  // Long ref names (refs/codex/turn-diffs/…) exceed Windows' path limit when stored as loose refs.
+  '-c', 'core.longpaths=true',
+  '--no-optional-locks',
+];
+
+export function ledgerGit(dir: string, args: readonly string[], opts: { timeoutMs?: number; maxBuffer?: number; input?: string } = {}): GitOut {
+  try {
+    const out = execFileSync('git', [...FIXED, '-C', dir, ...args], {
+      encoding: 'utf8', env: env(), timeout: opts.timeoutMs ?? 180_000, maxBuffer: opts.maxBuffer ?? 512_000_000, windowsHide: true,
+      stdio: [opts.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'], ...(opts.input === undefined ? {} : { input: opts.input }),
+    });
+    return { ok: true, out, err: '' };
+  } catch (error) {
+    const e = error as { stdout?: string; stderr?: string; message?: string };
+    return { ok: false, out: typeof e.stdout === 'string' ? e.stdout : '', err: (e.stderr || e.message || String(error)).trim() };
+  }
+}
+
+export const isHash = (h: string): boolean => /^[0-9a-f]{40}$/.test(h);
+
+export type RefNamespace = 'heads' | 'tags' | 'remotes' | 'stash' | 'other';
+export interface RefInfo {
+  readonly refname: string;
+  readonly namespace: RefNamespace;
+  /** The commit the ref ultimately names (an annotated tag peeled); for a ref to a tree or a blob, that object. */
+  readonly tip: string;
+  readonly type: 'commit' | 'tree' | 'blob' | 'tag' | 'unknown';
+}
+
+export function namespaceOf(refname: string): RefNamespace {
+  if (refname.startsWith('refs/heads/')) return 'heads';
+  if (refname.startsWith('refs/tags/')) return 'tags';
+  if (refname.startsWith('refs/remotes/')) return 'remotes';
+  if (refname === 'refs/stash') return 'stash';
+  return 'other';   // e.g. refs/codex/turn-diffs/…
+}
+
+/**
+ * Every ref, tags peeled; a symbolic remote HEAD (`refs/remotes/origin/HEAD`) is left out. A ref that names something
+ * other than a commit (refs/codex/turn-diffs/… name trees) is kept with its object type: it is part of what the
+ * repository records, and has no history to walk.
+ */
+export function listRefs(dir: string): RefInfo[] {
+  const r = ledgerGit(dir, ['for-each-ref', '--format=%(refname)%00%(objecttype)%00%(objectname)%00%(*objecttype)%00%(*objectname)%00%(symref)']);
+  if (!r.ok) return [];
+  const out: RefInfo[] = [];
+  for (const line of r.out.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const [refname, type, object, peeledType, peeled, symref] = line.split('\0');
+    if (!refname || symref) continue;
+    const commit = type === 'commit' ? object : peeledType === 'commit' ? peeled : '';
+    if (commit && isHash(commit)) out.push({ refname, namespace: namespaceOf(refname), tip: commit, type: 'commit' });
+    else if (object && isHash(object)) out.push({ refname, namespace: namespaceOf(refname), tip: object, type: (peeledType || type || 'unknown') as RefInfo['type'] });
+  }
+  return out;
+}
+
+/** The commits reachable from `tips` and from none of `exclude` (full hashes), in one read. */
+export function revList(dir: string, tips: readonly string[], exclude: readonly string[] = []): string[] | null {
+  if (tips.length === 0) return [];
+  const r = ledgerGit(dir, ['rev-list', '--stdin'], { input: [...tips, ...exclude.map((h) => `^${h}`)].join('\n') + '\n' });
+  return r.ok ? r.out.split(/\s+/).filter(isHash) : null;
+}
+
+/** The commits on the first-parent line of a tip. */
+export function firstParentLine(dir: string, tip: string): string[] {
+  const r = ledgerGit(dir, ['rev-list', '--first-parent', tip]);
+  return r.ok ? r.out.split(/\s+/).filter(isHash) : [];
+}
+
+/** Whether `ancestor` is reachable from `descendant`; null when git cannot tell (a missing object). */
+export function isAncestor(dir: string, ancestor: string, descendant: string): boolean | null {
+  if (ancestor === descendant) return true;
+  const r = ledgerGit(dir, ['merge-base', '--is-ancestor', ancestor, descendant], { timeoutMs: 30_000 });
+  if (r.ok) return true;
+  return /^\s*$/.test(r.err) ? false : null;
+}
+
+export interface CommitFileChange {
+  readonly status: 'A' | 'M' | 'D' | 'R' | 'C' | 'T';
+  readonly path: string;
+  /** Rename or copy source. */
+  readonly from: string | null;
+  readonly oldBlob: string | null;
+  readonly newBlob: string | null;
+  /** Null for a binary file. */
+  readonly added: number | null;
+  readonly deleted: number | null;
+}
+export interface CommitDetail {
+  readonly hash: string;
+  readonly parents: readonly string[];
+  readonly authorAt: string;
+  readonly committerAt: string;
+  readonly author: string;
+  readonly subject: string;
+  readonly body: string;
+  readonly files: readonly CommitFileChange[];
+}
+
+const ZERO = /^0{40}$/;
+const DETAIL_FORMAT = '--format=%x1e%H%x1f%P%x1f%aI%x1f%cI%x1f%an%x1f%s%x1f%b%x04';
+
+/**
+ * Parse `git log -z --raw --numstat` output. With -z every field ends in NUL: a raw entry is `:modes blobs STATUS` and
+ * then its path (two paths for a rename or a copy); a numstat entry is `added\tdeleted\tpath`, or `added\tdeleted\t`
+ * followed by the two paths of a rename. A commit's header is the format above, from \x1e to \x04.
+ */
+export function parseLogZ(out: string): CommitDetail[] {
+  const tokens = out.split('\0');
+  const commits: CommitDetail[] = [];
+  let head: { hash: string; parents: string[]; authorAt: string; committerAt: string; author: string; subject: string; body: string } | null = null;
+  let files = new Map<string, { status: CommitFileChange['status']; path: string; from: string | null; oldBlob: string | null; newBlob: string | null; added: number | null; deleted: number | null }>();
+  const flush = () => {
+    if (head) commits.push({ ...head, files: [...files.values()] });
+    head = null;
+    files = new Map();
+  };
+  for (let i = 0; i < tokens.length; i++) {
+    let t = tokens[i]!;
+    const start = t.indexOf('\x1e');
+    if (start >= 0) {
+      flush();
+      t = t.slice(start + 1);
+      const end = t.lastIndexOf('\x04');
+      const fields = (end >= 0 ? t.slice(0, end) : t).split('\x1f');
+      const hash = fields[0] ?? '';
+      if (!isHash(hash)) continue;
+      head = {
+        hash, parents: (fields[1] ?? '').split(' ').filter(isHash), authorAt: fields[2] ?? '', committerAt: fields[3] ?? '',
+        author: fields[4] ?? '', subject: fields[5] ?? '', body: (fields.slice(6).join('\x1f')).replace(/\s+$/, ''),
+      };
+      continue;
+    }
+    if (!head) continue;
+    t = t.replace(/^\n+/, '');
+    if (!t) continue;
+    const raw = /^:(\d+) (\d+) ([0-9a-f]+) ([0-9a-f]+) ([AMDRCTUX])(\d*)$/.exec(t);
+    if (raw) {
+      const status = raw[5] as CommitFileChange['status'];
+      const two = status === 'R' || status === 'C';
+      const first = tokens[i + 1] ?? '';
+      const second = two ? tokens[i + 2] ?? '' : null;
+      i += two ? 2 : 1;
+      if (!'AMDRCT'.includes(status)) continue;
+      const path = two ? second! : first;
+      files.set(path, {
+        status, path, from: two ? first : null,
+        oldBlob: ZERO.test(raw[3]!) ? null : raw[3]!, newBlob: ZERO.test(raw[4]!) ? null : raw[4]!,
+        added: null, deleted: null,
+      });
+      continue;
+    }
+    const num = /^(\d+|-)\t(\d+|-)\t([\s\S]*)$/.exec(t);
+    if (num) {
+      let path = num[3]!;
+      if (path === '') { path = tokens[i + 2] ?? ''; i += 2; }
+      const entry = files.get(path);
+      if (entry) {
+        entry.added = num[1] === '-' ? null : Number(num[1]);
+        entry.deleted = num[2] === '-' ? null : Number(num[2]);
+      }
+    }
+  }
+  flush();
+  return commits;
+}
+
+/**
+ * The details of the given commits in one pass per 2,000: metadata, the whole message, and every file changed against
+ * the first parent — status, rename or copy source, old and new content ids, line counts (rename-aware). A merge's
+ * changes are what it brought into the line it was merged onto; a root commit's are everything it added.
+ */
+export function logDetails(dir: string, hashes: readonly string[]): { details: CommitDetail[]; failed: number } {
+  const out: CommitDetail[] = [];
+  let failed = 0;
+  for (let i = 0; i < hashes.length; i += 2000) {
+    const chunk = hashes.slice(i, i + 2000);
+    const r = ledgerGit(dir, ['log', '--no-walk', '--stdin', '--diff-merges=first-parent', '-M', '--raw', '--no-abbrev', '--numstat', '--no-textconv', '--no-ext-diff', '-z', DETAIL_FORMAT], { input: chunk.join('\n') + '\n' });
+    if (!r.ok) { failed += chunk.length; continue; }
+    out.push(...parseLogZ(r.out));
+  }
+  return { details: out, failed };
+}
+
+/** Contents of blobs by id, one `git cat-file --batch` per 500; a missing object maps to null. */
+export function catBlobs(dir: string, blobs: readonly string[]): Map<string, Buffer | null> {
+  const out = new Map<string, Buffer | null>();
+  const wanted = [...new Set(blobs)];
+  for (let i = 0; i < wanted.length; i += 500) {
+    const chunk = wanted.slice(i, i + 500);
+    let buf: Buffer;
+    try {
+      buf = execFileSync('git', [...FIXED, '-C', dir, 'cat-file', '--batch'], {
+        input: chunk.join('\n') + '\n', env: env(), timeout: 300_000, maxBuffer: 1_500_000_000, windowsHide: true,
+      });
+    } catch {
+      for (const q of chunk) out.set(q, null);
+      continue;
+    }
+    let pos = 0;
+    let q = 0;
+    while (pos < buf.length && q < chunk.length) {
+      const eol = buf.indexOf(10, pos);
+      if (eol < 0) break;
+      const header = buf.subarray(pos, eol).toString('latin1');
+      pos = eol + 1;
+      const query = chunk[q]!;
+      q += 1;
+      const m = /^[0-9a-f]{40} (\S+) (\d+)$/.exec(header);
+      if (!m) { out.set(query, null); continue; }   // "<id> missing"
+      const size = Number(m[2]);
+      out.set(query, m[1] === 'blob' ? buf.subarray(pos, pos + size) : null);
+      pos += size + 1;
+    }
+    while (q < chunk.length) { out.set(chunk[q]!, null); q += 1; }
+  }
+  return out;
+}
+
+/** Whether content looks like text: no NUL in its first 8,000 bytes. */
+export const isText = (buf: Buffer): boolean => !buf.subarray(0, Math.min(buf.length, 8000)).includes(0);
+
+export interface TreeFile { readonly path: string; readonly size: number | null; readonly blob: string; readonly submodule: boolean }
+/** The files of a commit's tree, with content ids and sizes (a submodule has no size). */
+export function treeFiles(dir: string, ref: string): TreeFile[] {
+  const r = ledgerGit(dir, ['ls-tree', '-r', '-l', '-z', ref]);
+  if (!r.ok) return [];
+  const out: TreeFile[] = [];
+  for (const entry of r.out.split('\0')) {
+    if (!entry) continue;
+    const tab = entry.indexOf('\t');
+    if (tab < 0) continue;
+    const [mode, type, blob, size] = entry.slice(0, tab).trim().split(/\s+/);
+    const path = entry.slice(tab + 1);
+    if (mode === '160000' || type === 'commit') { out.push({ path, size: null, blob: blob ?? '', submodule: true }); continue; }
+    if (type !== 'blob') continue;
+    out.push({ path, size: size && /^\d+$/.test(size) ? Number(size) : null, blob: blob ?? '', submodule: false });
+  }
+  return out;
+}
+
+/** The repository's default branch (the trunk): origin's HEAD when set, else main, else master, else the checked-out branch. */
+export function defaultBranch(dir: string, refs: readonly RefInfo[]): string | null {
+  const origin = ledgerGit(dir, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], { timeoutMs: 15_000 });
+  if (origin.ok && origin.out.trim()) {
+    const name = origin.out.trim().replace(/^[^/]+\//, '');
+    if (name && refs.some((r) => r.refname === `refs/heads/${name}`)) return name;
+  }
+  for (const name of ['main', 'master', 'trunk', 'develop']) if (refs.some((r) => r.refname === `refs/heads/${name}`)) return name;
+  const current = ledgerGit(dir, ['symbolic-ref', '--quiet', '--short', 'HEAD'], { timeoutMs: 15_000 });
+  return current.ok && current.out.trim() ? current.out.trim() : null;
+}
+
+export function headOf(dir: string): { hash: string | null; branch: string | null } {
+  const h = ledgerGit(dir, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], { timeoutMs: 15_000 }).out.trim();
+  const b = ledgerGit(dir, ['symbolic-ref', '--quiet', '--short', 'HEAD'], { timeoutMs: 15_000 }).out.trim();
+  return { hash: isHash(h) ? h : null, branch: b || null };
+}
+
+export interface WorktreeEntry {
+  readonly path: string;
+  readonly head: string | null;
+  readonly branch: string | null;
+  readonly detached: boolean;
+  readonly bare: boolean;
+  readonly prunable: boolean;
+}
+/** `git worktree list --porcelain`, the main checkout first. */
+export function worktreeList(dir: string): WorktreeEntry[] {
+  const r = ledgerGit(dir, ['worktree', 'list', '--porcelain', '-z'], { timeoutMs: 30_000 });
+  if (!r.ok) return [];
+  const out: WorktreeEntry[] = [];
+  let cur: { path?: string; head?: string; branch?: string; detached?: boolean; bare?: boolean; prunable?: boolean } = {};
+  const flush = () => {
+    if (cur.path) out.push({ path: canonicalPath(cur.path), head: cur.head ?? null, branch: cur.branch?.replace(/^refs\/heads\//, '') ?? null, detached: cur.detached === true, bare: cur.bare === true, prunable: cur.prunable === true });
+    cur = {};
+  };
+  for (const field of r.out.split('\0')) {
+    if (field.startsWith('worktree ')) { flush(); cur.path = field.slice(9); }
+    else if (field.startsWith('HEAD ')) cur.head = field.slice(5);
+    else if (field.startsWith('branch ')) cur.branch = field.slice(7);
+    else if (field === 'detached') cur.detached = true;
+    else if (field === 'bare') cur.bare = true;
+    else if (field.startsWith('prunable')) cur.prunable = true;
+    else if (field === '') flush();
+  }
+  flush();
+  return out;
+}
+
+/** Uncommitted changes of a checkout (porcelain lines); null when git cannot read it. Takes no lock (GIT_OPTIONAL_LOCKS=0). */
+export function uncommitted(dir: string): string[] | null {
+  const r = ledgerGit(dir, ['status', '--porcelain', '--untracked-files=normal'], { timeoutMs: 60_000 });
+  return r.ok ? r.out.split(/\r?\n/).filter((l) => l.trim()) : null;
+}