@spexcode/spec-core 0.6.2 → 0.6.3

package/dist/git.js

@@ -0,0 +1,2736 @@
+import { execFileSync, execFile, spawn } from 'node:child_process';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { readFileSync, readdirSync, statSync, existsSync, writeFileSync, mkdirSync, rmSync, renameSync, openSync, closeSync, accessSync, constants } from 'node:fs';
+import { join, isAbsolute, resolve, delimiter } from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+import { projectRuntimeRoot } from './project-store.js';
+import { rootSlots, touchRoot as touchRootLru } from './root-lru.js';
+import { processStartToken } from './process-identity.js';
+const US = '\x1f', RS = '\x1e';
+// @@@ bounded graph git children - a git child that never exits (wedged fs, a hijacked PATH git, a dead
+// network mount) must not pin its awaiter forever: [[graph-cache]]'s settle guarantee starts at this seam.
+// Every shared helper passes a generous timeout with SIGKILL. A graph build additionally carries one fixed
+// permit pool through AsyncLocalStorage, so corpus-wide Promise.all fanout queues here before spawn rather
+// than materializing one process per worktree/eval. Calls outside that build context remain unconstrained.
+const GIT_TIMEOUT_MS = Number(process.env.SPEXCODE_GIT_TIMEOUT_MS || 120000);
+const GIT_SYNC_MAX_BUFFER = 1 << 27;
+export const BOARD_GIT_CONCURRENCY = 4;
+const gitByPath = new Map();
+export function gitBinary(env = process.env) {
+    const path = env.PATH || '';
+    const known = gitByPath.get(path);
+    if (known) {
+        try {
+            accessSync(known, constants.X_OK);
+            return known;
+        }
+        catch { }
+    }
+    for (const dir of path.split(delimiter)) {
+        const candidate = resolve(dir || '.', 'git');
+        try {
+            accessSync(candidate, constants.X_OK);
+            gitByPath.set(path, candidate);
+            return candidate;
+        }
+        catch { }
+    }
+    throw new Error('git executable not found on PATH');
+}
+const gitBuild = new AsyncLocalStorage();
+// @@@ a build's git children run on a bounded pack footprint - git sizes its mmap window, its mmap ceiling
+// and its delta-base cache for a process that owns the machine. A graph build's heaviest walks each mapped
+// well over a hundred megabytes of pack for output measured in kilobytes, and those children land inside the
+// build's own memory platform. Capping the three makes the same walks run in a fraction of the resident set
+// for a fraction of a second more. This is a RESOURCE boundary, never a semantic one — output, exit status
+// and stderr are byte-identical under every setting — and it is scoped to the build context, so ordinary
+// CLI/API git keeps git's defaults. It is also content-blind: the transport knows pack sizing, never which
+// walk a caller is doing.
+const BUILD_GIT_LIMITS = [
+    '-c', 'core.packedGitWindowSize=1m',
+    '-c', 'core.packedGitLimit=32m',
+    '-c', 'core.deltaBaseCacheLimit=1m',
+];
+const withBuildLimits = (args) => (gitBuild.getStore() ? [...BUILD_GIT_LIMITS, ...args] : args);
+export function gitAbortError() {
+    return Object.assign(new Error('The operation was aborted'), { name: 'AbortError', code: 'ABORT_ERR' });
+}
+function gitPermitPool(limit) {
+    let active = 0;
+    const waiting = [];
+    const releasePermit = () => {
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            active--;
+            drain();
+        };
+    };
+    const drain = () => {
+        while (active < limit && waiting.length) {
+            const waiter = waiting.shift();
+            waiter.signal.removeEventListener('abort', waiter.onAbort);
+            if (waiter.signal.aborted) {
+                waiter.reject(gitAbortError());
+                continue;
+            }
+            active++;
+            waiter.resolve(releasePermit());
+        }
+    };
+    return {
+        acquire(signal) {
+            if (signal.aborted)
+                return Promise.reject(gitAbortError());
+            if (active < limit) {
+                active++;
+                return Promise.resolve(releasePermit());
+            }
+            return new Promise((resolve, reject) => {
+                const waiter = {
+                    signal,
+                    resolve,
+                    reject,
+                    onAbort: () => {
+                        const index = waiting.indexOf(waiter);
+                        if (index >= 0)
+                            waiting.splice(index, 1);
+                        reject(gitAbortError());
+                    },
+                };
+                waiting.push(waiter);
+                signal.addEventListener('abort', waiter.onAbort, { once: true });
+            });
+        },
+    };
+}
+// A board build owns one abort signal. Async git calls inherit it without every graph layer growing a
+// cancellation parameter; aborting the build therefore reaches every active child and queued permit below
+// the graph seam. The pool is created here, so ordinary CLI/API git calls never share or wait on it.
+export function withGitAbortSignal(signal, run) {
+    return gitBuild.run({ signal, permits: gitPermitPool(BOARD_GIT_CONCURRENCY) }, run);
+}
+const inheritedContext = () => gitBuild.getStore();
+export function currentGitBuildAbortSignal() {
+    return inheritedContext()?.signal;
+}
+function warnIfTimedOut(e, args) {
+    if (e?.code === 'ETIMEDOUT' || e?.spexcodeGitTimeout === true)
+        console.warn(`spec-cli: git ${args.slice(0, 6).join(' ')}… killed after ${GIT_TIMEOUT_MS}ms — child never exited`);
+}
+// strip git's hook-exported env (GIT_DIR etc.) so every call discovers the repo from the filesystem.
+export function git(args) {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    delete env.GIT_OBJECT_DIRECTORY;
+    try {
+        return execFileSync(gitBinary(env), withBuildLimits(args), {
+            encoding: 'utf8',
+            env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: GIT_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
+            maxBuffer: GIT_SYNC_MAX_BUFFER,
+        });
+    }
+    catch (e) {
+        warnIfTimedOut(e, args);
+        throw e;
+    }
+}
+function gitBuffer(args, input) {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    delete env.GIT_OBJECT_DIRECTORY;
+    try {
+        return execFileSync(gitBinary(env), withBuildLimits(args), {
+            input,
+            env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: GIT_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
+            maxBuffer: GIT_SYNC_MAX_BUFFER,
+        });
+    }
+    catch (e) {
+        warnIfTimedOut(e, args);
+        throw e;
+    }
+}
+const gitObjectFormatMemo = new Map();
+export function gitObjectFormat(root) {
+    const key = rootKey(root);
+    const hit = gitObjectFormatMemo.get(key);
+    if (hit)
+        return hit;
+    const format = git(['-C', root, 'rev-parse', '--show-object-format=storage']).trim();
+    if (format !== 'sha1' && format !== 'sha256')
+        throw new Error(`unsupported Git object format '${format || 'empty'}' at ${root}`);
+    gitObjectFormatMemo.set(key, format);
+    return format;
+}
+export function isGitObjectId(root, value) {
+    const length = gitObjectFormat(root) === 'sha256' ? 64 : 40;
+    return value.length === length && /^[0-9a-f]+$/.test(value);
+}
+// Batch immutable object lookups used by the shared anchor/index path. Git accepts revision:path queries on
+// batch-check, so dozens of rev-parse + cat-file children collapse into two bounded processes without
+// changing the returned bytes or object ids.
+//
+// These are async for two reasons a synchronous execFileSync cannot serve once the caller batches its WHOLE
+// invocation rather than one reading at a time. A sync child is invisible to the build's permit pool and its
+// abort signal, so a watchdog abort could not kill it; and one build-wide `cat-file --batch` reading tens of
+// megabytes would be a single uninterruptible stretch — exactly the /health-blocking shape [[graph-cache]]
+// closed for the fs walks.
+//
+// Chunking is a real output bound, not ceremony: the async transport caps a child's stdout at GIT_MAX_BUFFER
+// and overflow is a loud error. Revision rows are 41 bytes each, so only the blob read (payload-sized) needs
+// a chunk; the cap is on COUNT because sizes are unknown until git answers, and it is set so an ordinary
+// source corpus never approaches the byte ceiling.
+const BATCH_BLOB_CHUNK = 256;
+const BATCH_BLOB_MAX_BUFFER = 1 << 26;
+async function batchBuffer(args, input, maxBuffer, extraEnv = {}) {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    delete env.GIT_OBJECT_DIRECTORY;
+    Object.assign(env, extraEnv);
+    try {
+        return (await execGitForCaller(args, env, maxBuffer, input)).stdout;
+    }
+    catch (error) {
+        if (error?.name === 'AbortError')
+            throw error;
+        warnIfTimedOut(error, args);
+        throw new Error(`git ${args.slice(2, 5).join(' ')} failed: ${String(error?.stderr || error?.message || 'unknown git error').trim()}`);
+    }
+}
+export async function batchRevisionOids(root, revisions, options = {}) {
+    if (!revisions.length)
+        return [];
+    const extraEnv = options.replaceObjects === false ? { GIT_NO_REPLACE_OBJECTS: '1' } : {};
+    const out = (await batchBuffer(['-C', root, 'cat-file', '--batch-check=%(objectname)'], revisions.join('\n') + '\n', undefined, extraEnv)).toString('utf8');
+    const lines = out.split('\n');
+    if (lines.length - 1 !== revisions.length)
+        throw new Error(`git cat-file --batch-check returned ${lines.length - 1} rows for ${revisions.length} revisions`);
+    return revisions.map((revision, index) => {
+        const value = lines[index].trim();
+        if (isGitObjectId(root, value))
+            return value;
+        if (value === `${revision} missing`)
+            return null;
+        throw new Error(`git cat-file --batch-check returned '${value}' for ${revision}`);
+    });
+}
+export async function batchBlobTexts(root, oids) {
+    const unique = [...new Set(oids.filter(Boolean))];
+    const files = new Map();
+    if (!unique.length)
+        return files;
+    for (const oid of unique)
+        if (!isGitObjectId(root, oid))
+            throw new Error(`invalid object id '${oid}'`);
+    for (let cursor = 0; cursor < unique.length; cursor += BATCH_BLOB_CHUNK) {
+        const chunk = unique.slice(cursor, cursor + BATCH_BLOB_CHUNK);
+        const out = await batchBuffer(['-C', root, 'cat-file', '--batch'], chunk.join('\n') + '\n', BATCH_BLOB_MAX_BUFFER);
+        let offset = 0;
+        for (const oid of chunk) {
+            const newline = out.indexOf(10, offset);
+            if (newline < 0)
+                throw new Error(`git cat-file --batch ended before ${oid}`);
+            const header = out.subarray(offset, newline).toString('utf8');
+            const size = Number(header.match(/ blob (\d+)$/)?.[1]);
+            if (!header.startsWith(`${oid} blob `) || !Number.isFinite(size))
+                throw new Error(`git cat-file --batch returned '${header}' for ${oid}`); // dead-words-ok: Git object protocol type
+            const start = newline + 1, end = start + size;
+            if (end >= out.length || out[end] !== 0x0a)
+                throw new Error(`git cat-file --batch truncated object ${oid}`);
+            files.set(oid, out.subarray(start, end).toString('utf8'));
+            offset = end + 1;
+        }
+        if (offset !== out.length)
+            throw new Error(`git cat-file --batch returned ${out.length - offset} unexpected trailing bytes`);
+    }
+    return files;
+}
+function treeBlobs(root, tip, pathspec = '.') {
+    const out = git(['-C', root, '-c', 'core.quotePath=false', 'ls-tree', '-r', '-z', tip, '--', pathspec]);
+    const blobs = [];
+    for (const record of out.split('\0')) {
+        if (!record)
+            continue;
+        const m = record.match(/^\d+ blob ([0-9a-f]+)\t([\s\S]+)$/);
+        if (m)
+            blobs.push({ oid: m[1], path: m[2] });
+    }
+    return blobs;
+}
+// Read a tree slice in two Git calls regardless of file count: ls-tree names immutable blob oids, then
+// cat-file --batch returns their exact bytes. Pending lint uses this for .spec so commit --only/partial
+// staging can never be judged through unrelated working-tree prose.
+export function treeTextFiles(root, tip, pathspec = '.') {
+    const blobs = treeBlobs(root, tip, pathspec);
+    const files = new Map();
+    if (!blobs.length)
+        return files;
+    const out = gitBuffer(['-C', root, 'cat-file', '--batch'], blobs.map((b) => b.oid).join('\n') + '\n');
+    let offset = 0;
+    for (const blob of blobs) {
+        const newline = out.indexOf(10, offset);
+        if (newline < 0)
+            throw new Error(`git cat-file --batch ended before ${blob.path}`);
+        const header = out.subarray(offset, newline).toString('utf8');
+        const size = Number(header.match(/ blob (\d+)$/)?.[1]);
+        if (!Number.isFinite(size))
+            throw new Error(`git cat-file --batch returned '${header}' for ${blob.path}`);
+        const start = newline + 1, end = start + size;
+        files.set(blob.path, out.subarray(start, end).toString('utf8'));
+        offset = end + 1; // one LF follows each payload
+    }
+    return files;
+}
+export function treeFilePaths(root, tip) {
+    return new Set(treeBlobs(root, tip).map((b) => b.path));
+}
+export function treeFileText(root, tip, path) {
+    try {
+        return gitBuffer(['-C', root, 'cat-file', 'blob', `${tip}:${path}`]).toString('utf8');
+    } // dead-words-ok: git plumbing
+    catch {
+        return null;
+    }
+}
+// execFile's AbortSignal kills only its direct child. A wedged adapter may have descendants (the
+// deterministic tests use a shell + sleep), so async git runs in their own process group and abort/timeout
+// kills the whole group. The callback still carries the same stdout/stderr/error shape to gitA/gitTry.
+const GIT_MAX_BUFFER = 1 << 24;
+function execGit(args, env, signal, maxBuffer = GIT_MAX_BUFFER, input) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(gitAbortError());
+            return;
+        }
+        const child = spawn(gitBinary(env), args, { env, detached: true, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] });
+        const stdout = [], stderr = [];
+        let stdoutBytes = 0, stderrBytes = 0, aborted = false, timedOut = false, overflow = false;
+        let spawnError = null;
+        const killTree = () => {
+            if (!child.pid)
+                return;
+            try {
+                process.kill(-child.pid, 'SIGKILL');
+            }
+            catch { /* group may already be gone */ }
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* already exited */ }
+        };
+        const onAbort = () => { aborted = true; killTree(); };
+        const append = (chunks, chunk, stream) => {
+            const total = stream === 'stdout' ? (stdoutBytes += chunk.length) : (stderrBytes += chunk.length);
+            if (total > maxBuffer) {
+                overflow = true;
+                killTree();
+                return;
+            }
+            chunks.push(chunk);
+        };
+        child.stdout.on('data', (chunk) => append(stdout, chunk, 'stdout'));
+        child.stderr.on('data', (chunk) => append(stderr, chunk, 'stderr'));
+        child.once('error', (error) => { spawnError = error; });
+        if (input !== undefined) {
+            // A command can reject its input before the pipe drains. Keep that write failure on the same
+            // close/reject path as spawn and exit failures instead of letting Node raise an unhandled EPIPE.
+            child.stdin.once('error', (error) => { if (!spawnError)
+                spawnError = error; });
+            child.stdin.end(input);
+        }
+        child.once('close', (code, childSignal) => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            const result = { stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr).toString('utf8') };
+            if (code === 0 && !aborted && !timedOut && !overflow && !spawnError) {
+                resolve(result);
+                return;
+            }
+            const error = spawnError ?? new Error(overflow
+                ? `git output exceeded ${maxBuffer} bytes`
+                : `git exited with ${code ?? childSignal ?? 'unknown status'}`);
+            // @@@ a spawn failure keeps its OWN cause - a child that never started still emits `close`, with the
+            // negated errno as its code (EACCES arrives as -13). Overwriting the spawn error's `'EACCES'`/`'ENOENT'`
+            // with that number turns "git could not RUN" into "git ran and exited", and every caller that separates
+            // the two reads the second as a real git answer: the freshness batch concluded "the anchor object is
+            // unreadable", session create concluded "the branch does not exist". A machine where git is missing or
+            // unexecutable would have been told, silently, that the thing it asked about is absent.
+            if (overflow)
+                error.code = 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER';
+            else if (!spawnError)
+                error.code = code;
+            error.signal = childSignal;
+            error.stdout = result.stdout.toString('utf8');
+            error.stderr = result.stderr;
+            if (aborted)
+                error.name = 'AbortError';
+            if (timedOut)
+                error.spexcodeGitTimeout = true;
+            reject(error);
+        });
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
+        const timer = setTimeout(() => { timedOut = true; killTree(); }, GIT_TIMEOUT_MS);
+        timer.unref?.();
+    });
+}
+async function execGitForCaller(args, env, maxBuffer, input) {
+    const context = inheritedContext();
+    if (!context)
+        return execGit(args, env, undefined, maxBuffer, input);
+    const release = await context.permits.acquire(context.signal);
+    try {
+        return await execGit(withBuildLimits(args), env, context.signal, maxBuffer, input);
+    }
+    finally {
+        release();
+    }
+}
+// Event streams are the index input itself and may legitimately exceed execFile's fixed maxBuffer. Read
+// them through spawn so the only bound is the index the caller is intentionally constructing; timeout,
+// cancellation, process-group cleanup and build permits remain identical to the ordinary async transport.
+function execGitStream(args, env, signal, input) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(gitAbortError());
+            return;
+        }
+        const child = spawn(gitBinary(env), args, { env, detached: true, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] });
+        const stdout = [], stderr = [];
+        let settled = false, aborted = false, timedOut = false;
+        let stdinError = null;
+        const killTree = () => {
+            if (!child.pid)
+                return;
+            try {
+                process.kill(-child.pid, 'SIGKILL');
+            }
+            catch { /* group may already be gone */ }
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* already exited */ }
+        };
+        const onAbort = () => { aborted = true; killTree(); };
+        const timer = setTimeout(() => { timedOut = true; killTree(); }, GIT_TIMEOUT_MS);
+        timer.unref?.();
+        signal?.addEventListener('abort', onAbort, { once: true });
+        child.stdout.on('data', (chunk) => stdout.push(chunk));
+        child.stderr.on('data', (chunk) => stderr.push(chunk));
+        if (input !== undefined) {
+            // A command can reject its input before the pipe drains. Keep that write failure on the same close
+            // path as exit and abort failures instead of letting Node raise an unhandled EPIPE.
+            child.stdin.once('error', (error) => { stdinError ??= error; });
+            child.stdin.end(input);
+        }
+        child.on('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            if (aborted)
+                error.name = 'AbortError';
+            if (timedOut)
+                error.spexcodeGitTimeout = true;
+            reject(error);
+        });
+        child.on('close', (code, childSignal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            const result = { stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr).toString('utf8') };
+            if (code === 0 && !aborted && !timedOut && !stdinError) {
+                resolve(result);
+                return;
+            }
+            const error = stdinError ?? new Error(`git exited with ${code ?? childSignal ?? 'unknown status'}`);
+            error.code = stdinError ? error.code : code;
+            error.signal = childSignal;
+            error.stdout = result.stdout.toString('utf8');
+            error.stderr = result.stderr;
+            if (aborted)
+                error.name = 'AbortError';
+            if (timedOut)
+                error.spexcodeGitTimeout = true;
+            reject(error);
+        });
+    });
+}
+async function execGitStreamForCaller(args, env, input) {
+    const context = inheritedContext();
+    if (!context)
+        return execGitStream(args, env, undefined, input);
+    const release = await context.permits.acquire(context.signal);
+    try {
+        return await execGitStream(withBuildLimits(args), env, context.signal, input);
+    }
+    finally {
+        release();
+    }
+}
+export async function gitA(args, input) {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    delete env.GIT_OBJECT_DIRECTORY;
+    const context = inheritedContext();
+    try {
+        const { stdout } = await execGitForCaller(args, env, undefined, input);
+        return stdout.toString('utf8');
+    }
+    catch (e) {
+        if (context?.signal.aborted || e?.name === 'AbortError')
+            throw e;
+        warnIfTimedOut(e, args);
+        return '';
+    }
+}
+async function gitARequired(args, input) {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    delete env.GIT_OBJECT_DIRECTORY;
+    try {
+        return (await execGitForCaller(args, env, undefined, input)).stdout.toString('utf8');
+    }
+    catch (error) {
+        if (error?.name === 'AbortError')
+            throw error;
+        warnIfTimedOut(error, args);
+        throw new Error(`git ${args.slice(2, 6).join(' ')} failed: ${String(error?.stderr || error?.message || 'unknown git error').trim()}`);
+    }
+}
+// The schema names both the ledger grammar and its on-disk namespace. A reader that predates a row type
+// must never share a ledger with its writer: it seeds the next namespace from Git instead.
+const EVENT_CACHE_SCHEMA = 'history-events-v16';
+const IMMUTABLE_HUNK_FACT = 'immutable-hunk-v1';
+const EVENT_STREAM_KINDS = ['merge', 'identity-raw'];
+const eventLedgerBuild = new AsyncLocalStorage();
+const eventLedgerDemandPolicy = new AsyncLocalStorage();
+const eventLedgerDiagnostics = { reads: 0, locks: 0, replaces: 0 };
+const eventPathMemo = new Map();
+function replacementStorageIdentity(common) {
+    const hash = createHash('sha256');
+    const addTree = (root, rel) => {
+        if (!existsSync(root))
+            return;
+        const stack = [{ dir: root, rel }];
+        while (stack.length) {
+            const current = stack.pop();
+            const entries = readdirSync(current.dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+            for (const entry of entries) {
+                const path = join(current.dir, entry.name);
+                const name = `${current.rel}/${entry.name}`;
+                if (entry.isDirectory())
+                    stack.push({ dir: path, rel: name });
+                else
+                    hash.update(`\0${name}\0`).update(readFileSync(path));
+            }
+        }
+    };
+    addTree(join(common, 'refs', 'replace'), 'refs/replace');
+    for (const name of ['packed-refs']) {
+        const path = join(common, name);
+        if (existsSync(path))
+            hash.update(`\0${name}\0`).update(readFileSync(path));
+    }
+    // Reftable is opaque here by design: its bytes are only an invalidation signal. Git remains the one
+    // parser and supplies the canonical refs/replace targets when those bytes change.
+    addTree(join(common, 'reftable'), 'reftable');
+    return hash.digest('hex');
+}
+function eventCacheLocation(root) {
+    const rootId = rootKey(root), old = eventPathMemo.get(rootId);
+    const common = old?.common ?? git(['-C', root, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim();
+    const shallowPath = old?.shallowPath ?? git(['-C', root, 'rev-parse', '--path-format=absolute', '--git-path', 'shallow']).trim();
+    const shallow = existsSync(shallowPath) ? readFileSync(shallowPath, 'utf8') : 'unshallow';
+    const graftsPath = join(common, 'info', 'grafts');
+    const grafts = existsSync(graftsPath) ? readFileSync(graftsPath, 'utf8') : '';
+    const replacementStorage = replacementStorageIdentity(common);
+    const replacements = old?.replacementStorage === replacementStorage
+        ? old.replacements
+        : git(['-C', root, 'for-each-ref', 'refs/replace', '--format=%(refname) %(objectname)']);
+    const objectFormat = gitObjectFormat(root);
+    if (old && old.shallow === shallow && old.grafts === grafts && old.replacements === replacements && old.objectFormat === objectFormat)
+        return { path: old.path, identity: old.identity, interpretation: old.interpretation, objectFormat };
+    const interpretation = createHash('sha256')
+        .update(`${EVENT_CACHE_SCHEMA}\0${objectFormat}\0${shallow}\0${grafts}\0${replacements}`)
+        .digest('hex');
+    const identity = interpretation.slice(0, 16);
+    // projectRuntimeRoot derives checkout identity from dirname(common). A bare repository is its own common
+    // dir, so a synthetic `.git` suffix preserves the repository path instead of collapsing sibling bares.
+    const gitDir = gitDirOf(root);
+    const storeIdentity = gitDir === root && common === root ? join(common, '.git') : common;
+    const path = join(projectRuntimeRoot(storeIdentity), `${EVENT_CACHE_SCHEMA}-${identity}.ndjson`);
+    eventPathMemo.set(rootId, { common, shallowPath, grafts, shallow, replacementStorage, replacements, path, identity, interpretation, objectFormat });
+    return { path, identity, interpretation, objectFormat };
+}
+// One existing source-of-truth identity governs every Git reader that interprets commit images. Consumers
+// may retain the full digest in memory while the ledger keeps its established short directory name.
+export function gitObjectInterpretation(root) {
+    const location = eventCacheLocation(root);
+    const raw = eventPathMemo.get(rootKey(root))?.replacements ?? '';
+    const replacements = new Map();
+    for (const line of raw.split('\n').filter(Boolean)) {
+        const match = line.match(/^refs\/replace\/([0-9a-f]+) ([0-9a-f]+)$/);
+        if (!match || !isGitObjectIdForFormat(location.objectFormat, match[1]) || !isGitObjectIdForFormat(location.objectFormat, match[2]))
+            throw new Error(`malformed refs/replace projection '${line}' at ${root}`);
+        replacements.set(match[1], match[2]);
+    }
+    return { identity: location.interpretation, objectFormat: location.objectFormat, replacements };
+}
+export function gitInterpretationIdentity(root) { return eventCacheLocation(root).identity; }
+function emptyEventCache() {
+    return { streams: new Map(), streamTips: new Map(), hunks: new Map() };
+}
+function exactKeys(value, expected) {
+    const actual = Object.keys(value).sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+function isGitObjectIdForFormat(format, value) {
+    return value.length === (format === 'sha256' ? 64 : 40) && /^[0-9a-f]+$/.test(value);
+}
+function eventPayloadDigest(payload) {
+    return createHash('sha256').update(payload).digest('hex');
+}
+function eventIntegrityFooter(payload, addition) {
+    const footer = {
+        k: 'integrity',
+        bytes: payload.length + addition.length,
+        sha256: createHash('sha256').update(payload).update(addition).digest('hex'),
+    };
+    return Buffer.from(`${JSON.stringify(footer)}\n`);
+}
+function eventStreamKind(value) {
+    return typeof value === 'string' && EVENT_STREAM_KINDS.includes(value)
+        ? value
+        : null;
+}
+function decodeHunkRanges(value) {
+    if (!Array.isArray(value))
+        return null;
+    const ranges = [];
+    for (const row of value) {
+        if (!Array.isArray(row) || row.length !== 2 || !Number.isSafeInteger(row[0]) || !Number.isSafeInteger(row[1])
+            || row[0] <= 0 || row[1] < row[0])
+            return null;
+        ranges.push([row[0], row[1]]);
+    }
+    return ranges;
+}
+function decodeImmutableHunkFact(row) {
+    if (!exactKeys(row, ['a', 'b', 'i', 'k']) || row.k !== IMMUTABLE_HUNK_FACT || typeof row.i !== 'string' || !row.i)
+        return null;
+    const after = decodeHunkRanges(row.a);
+    if (!after || !Array.isArray(row.b))
+        return null;
+    const before = [];
+    for (const parent of row.b) {
+        const ranges = decodeHunkRanges(parent);
+        if (!ranges)
+            return null;
+        before.push(ranges);
+    }
+    return { key: row.i, ranges: { after, before } };
+}
+function decodeEventPayload(payload, location) {
+    const state = emptyEventCache();
+    const text = payload.toString('utf8');
+    for (let start = 0; start < text.length;) {
+        const newline = text.indexOf('\n', start);
+        const end = newline < 0 ? text.length : newline;
+        const line = text.slice(start, end);
+        start = end + 1;
+        if (!line)
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            return null;
+        }
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return null;
+        const row = value;
+        if (row.k === IMMUTABLE_HUNK_FACT) {
+            const fact = decodeImmutableHunkFact(row);
+            if (!fact || state.hunks.has(fact.key))
+                return null;
+            state.hunks.set(fact.key, fact.ranges);
+            continue;
+        }
+        if (exactKeys(row, ['k', 'tip'])) {
+            const kind = typeof row.k === 'string' && row.k.startsWith('tip:') ? eventStreamKind(row.k.slice(4)) : null;
+            if (!kind || typeof row.tip !== 'string' || !isGitObjectIdForFormat(location.objectFormat, row.tip))
+                return null;
+            const tips = state.streamTips.get(kind) ?? [];
+            if (tips.includes(row.tip))
+                return null;
+            tips.push(row.tip);
+            state.streamTips.set(kind, tips);
+            continue;
+        }
+        const kind = eventStreamKind(row.k);
+        if (!kind || typeof row.h !== 'string' || !isGitObjectIdForFormat(location.objectFormat, row.h))
+            return null;
+        const record = kind === 'identity-raw'
+            ? (() => {
+                const payload = exactKeys(row, ['a', 'c', 'd', 'h', 'k', 'r', 's'])
+                    ? { a: row.a, c: row.c, d: row.d, r: row.r, s: row.s }
+                    : null;
+                const identity = payload ? decodeIdentityRawRecord(payload, row.h, location) : null;
+                return identity ? { hash: row.h, identity } : null;
+            })()
+            : (!exactKeys(row, ['h', 'k', 'r']) || typeof row.r !== 'string' || !row.r
+                ? null
+                : (() => {
+                    const rawHash = row.r.split(US, 1)[0].split('\n', 1)[0].trim();
+                    return rawHash === row.h ? { hash: row.h, raw: row.r } : null;
+                })());
+        if (!record)
+            return null;
+        let stream = state.streams.get(kind);
+        if (!stream) {
+            stream = new Map();
+            state.streams.set(kind, stream);
+        }
+        if (stream.has(row.h))
+            return null;
+        stream.set(row.h, record);
+    }
+    return state;
+}
+function loadEventLedger(location) {
+    eventLedgerDiagnostics.reads++;
+    let file;
+    try {
+        file = readFileSync(location.path);
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT')
+            throw error;
+        return { payload: Buffer.alloc(0), state: emptyEventCache() };
+    }
+    if (!file.length || file[file.length - 1] !== 0x0a)
+        return { payload: Buffer.alloc(0), state: emptyEventCache() };
+    const body = file.subarray(0, file.length - 1);
+    const footerBreak = body.lastIndexOf(0x0a);
+    const footerStart = footerBreak + 1;
+    const payload = file.subarray(0, footerStart);
+    try {
+        const value = JSON.parse(body.subarray(footerStart).toString('utf8'));
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error('invalid integrity row');
+        const row = value;
+        if (!exactKeys(row, ['bytes', 'k', 'sha256']) || row.k !== 'integrity' || row.bytes !== payload.length
+            || typeof row.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(row.sha256)
+            || row.sha256 !== eventPayloadDigest(payload))
+            throw new Error('invalid integrity row');
+        const state = decodeEventPayload(payload, location);
+        if (!state)
+            throw new Error('invalid event row');
+        return { payload, state };
+    }
+    catch {
+        return { payload: Buffer.alloc(0), state: emptyEventCache() };
+    }
+}
+function readEventLockOwner(lock) {
+    try {
+        const value = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'));
+        return Number.isInteger(value.pid) && value.pid > 0
+            && typeof value.startToken === 'string' && !!value.startToken
+            && typeof value.nonce === 'string' && !!value.nonce
+            ? { pid: value.pid, startToken: value.startToken, nonce: value.nonce }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+const sameEventLockOwner = (left, right) => !!left && !!right && left.pid === right.pid && left.startToken === right.startToken && left.nonce === right.nonce;
+function eventLockOwnerState(owner) {
+    try {
+        process.kill(owner.pid, 0);
+    }
+    catch (error) {
+        if (error?.code === 'ESRCH')
+            return 'dead';
+        if (error?.code !== 'EPERM')
+            return 'unknown';
+    }
+    const observed = processStartToken(owner.pid);
+    if (!observed)
+        return 'unknown';
+    return observed === owner.startToken ? 'live' : 'dead';
+}
+function retireLockPath(active) {
+    const inert = `${active}.inert.${process.pid}.${randomBytes(8).toString('hex')}`;
+    try {
+        renameSync(active, inert);
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    try {
+        rmSync(inert, { recursive: true, force: true });
+    }
+    catch { /* no longer arbitrates ownership */ }
+    return true;
+}
+function reclaimDeadEventLock(lock, held, claimant) {
+    if (eventLockOwnerState(held) !== 'dead')
+        return false;
+    const reclaim = join(lock, 'reclaim');
+    if (existsSync(reclaim)) {
+        const reclaimer = readEventLockOwner(reclaim);
+        if (!reclaimer)
+            throw new Error(`history event cache lock has an unprovable reclaimer: ${lock}`);
+        const state = eventLockOwnerState(reclaimer);
+        if (state === 'unknown')
+            throw new Error(`history event cache lock reclaimer identity is unreadable: ${lock}`);
+        if (state === 'live')
+            return false;
+        retireLockPath(reclaim);
+    }
+    const prepared = join(lock, `reclaim-${claimant.pid}-${claimant.nonce}`);
+    try {
+        mkdirSync(prepared);
+        writeFileSync(join(prepared, 'owner.json'), JSON.stringify(claimant));
+        renameSync(prepared, reclaim);
+    }
+    catch (error) {
+        rmSync(prepared, { recursive: true, force: true });
+        if (error?.code === 'EEXIST' || error?.code === 'ENOTEMPTY' || error?.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    const current = readEventLockOwner(lock);
+    if (!sameEventLockOwner(current, held) || (current && eventLockOwnerState(current) !== 'dead')) {
+        retireLockPath(reclaim);
+        return false;
+    }
+    return retireLockPath(lock);
+}
+const EVENT_LEDGER_BUSY = Symbol('event ledger held by a live writer');
+async function withEventCacheLock(path, run, waitForWriter = true) {
+    const lock = `${path}.lock`;
+    mkdirSync(join(path, '..'), { recursive: true });
+    const startToken = processStartToken(process.pid);
+    if (!startToken)
+        throw new Error(`cannot prove history event cache lock claimant identity: ${path}`);
+    const owner = { pid: process.pid, startToken, nonce: randomBytes(16).toString('hex') };
+    const attempts = Math.max(1, Math.ceil(GIT_TIMEOUT_MS / 5));
+    const signal = inheritedContext()?.signal;
+    for (let attempt = 0;; attempt++) {
+        if (signal?.aborted)
+            throw gitAbortError();
+        const claimant = `${lock}.claim.${owner.pid}.${owner.nonce}`;
+        try {
+            mkdirSync(claimant);
+            writeFileSync(join(claimant, 'owner.json'), JSON.stringify(owner));
+            renameSync(claimant, lock);
+            break;
+        }
+        catch (error) {
+            rmSync(claimant, { recursive: true, force: true });
+            if (error?.code !== 'EEXIST' && error?.code !== 'ENOTEMPTY')
+                throw error;
+            const held = readEventLockOwner(lock);
+            if (!held) {
+                if (!existsSync(lock))
+                    continue;
+                throw new Error(`history event cache lock has no provable exact owner: ${path}`);
+            }
+            const heldState = eventLockOwnerState(held);
+            if (heldState === 'unknown')
+                throw new Error(`history event cache lock owner identity is unreadable: ${path}`);
+            if (heldState === 'dead') {
+                if (reclaimDeadEventLock(lock, held, owner))
+                    continue;
+                if (!existsSync(lock))
+                    continue;
+            }
+            if (!waitForWriter) {
+                const current = readEventLockOwner(lock);
+                if (!current) {
+                    if (!existsSync(lock))
+                        continue;
+                    throw new Error(`history event cache lock has no provable exact owner: ${path}`);
+                }
+                const state = eventLockOwnerState(current);
+                if (state === 'live')
+                    return EVENT_LEDGER_BUSY;
+                // A live reclaimer may be arbitrating this exact dead owner. Foreground demand can safely derive
+                // from the atomic snapshot, but must not spin synchronously until that separate lease finishes.
+                if (state === 'dead')
+                    return EVENT_LEDGER_BUSY;
+                throw new Error(`history event cache lock owner identity is unreadable: ${path}`);
+            }
+            if (attempt >= attempts) {
+                const heldBy = readEventLockOwner(lock)?.pid;
+                throw new Error(`timed out waiting for history event cache lock held by ${heldBy ? `pid ${heldBy}` : 'unknown owner'}: ${path}`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, 5));
+        }
+    }
+    eventLedgerDiagnostics.locks++;
+    try {
+        return await run();
+    }
+    finally {
+        if (sameEventLockOwner(readEventLockOwner(lock), owner))
+            retireLockPath(lock);
+    }
+}
+function removeEventTemps(path) {
+    const dir = join(path, '..'), base = path.split('/').pop() ?? '';
+    try {
+        for (const name of readdirSync(dir))
+            if (name.startsWith(`${base}.`) && name.endsWith('.tmp'))
+                rmSync(join(dir, name), { force: true });
+    }
+    catch { /* the writer creates the directory immediately below */ }
+}
+function replaceEventLedger(path, payload, additions) {
+    const addition = Buffer.from(additions.join(''));
+    const tmp = `${path}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+    let fd = null;
+    try {
+        fd = openSync(tmp, 'wx', 0o600);
+        writeFileSync(fd, payload);
+        writeFileSync(fd, addition);
+        writeFileSync(fd, eventIntegrityFooter(payload, addition));
+        const written = fd;
+        fd = null;
+        closeSync(written);
+        renameSync(tmp, path);
+        eventLedgerDiagnostics.replaces++;
+    }
+    catch (error) {
+        if (fd !== null)
+            closeSync(fd);
+        rmSync(tmp, { force: true });
+        throw error;
+    }
+}
+const EVENT_LEDGER_RETRY = Symbol('event ledger identity moved');
+function activeEventLedger(root) {
+    const build = eventLedgerBuild.getStore();
+    if (!build)
+        return null;
+    return eventCacheLocation(root).path === build.location.path ? build : null;
+}
+async function runEventLedgerAttempt(root, location, run, persist) {
+    const build = { location, snapshot: loadEventLedger(location), additions: [] };
+    const result = await eventLedgerBuild.run(build, run);
+    if (eventCacheLocation(root).identity !== location.identity)
+        return EVENT_LEDGER_RETRY;
+    if (persist && build.additions.length) {
+        removeEventTemps(location.path);
+        mkdirSync(join(location.path, '..'), { recursive: true });
+        replaceEventLedger(location.path, build.snapshot.payload, build.additions);
+    }
+    return result;
+}
+async function eventLedgerTransaction(root, run, demand) {
+    if (activeEventLedger(root))
+        return run();
+    for (let attempt = 0; attempt < 8; attempt++) {
+        const location = eventCacheLocation(root);
+        const locked = await withEventCacheLock(location.path, () => runEventLedgerAttempt(root, location, run, true), !demand);
+        const value = locked === EVENT_LEDGER_BUSY
+            ? await runEventLedgerAttempt(root, location, run, false)
+            : locked;
+        if (value !== EVENT_LEDGER_RETRY)
+            return value;
+    }
+    throw new Error('history event cache identity changed repeatedly during one ledger build');
+}
+// The event ledger is one build transaction, not one transaction per consumer: stream extraction and
+// immutable hunk derivation share the snapshot, integrity verdict, lock, and final replacement.
+export function withEventLedgerBuild(root, run) {
+    const demand = eventLedgerDemandPolicy.getStore();
+    return eventLedgerTransaction(root, run, !!demand && demand.path === eventCacheLocation(root).path);
+}
+// Demand is an ambient acquisition POLICY, not an eager lock. Nested ledger consumers therefore use the
+// read-only path under a live writer, while observer waits, revision reads, and stable-cut replay take no lock.
+export function withEventLedgerDemand(root, run) {
+    const path = eventCacheLocation(root).path;
+    if (eventLedgerDemandPolicy.getStore()?.path === path)
+        return run();
+    return eventLedgerDemandPolicy.run({ path }, run);
+}
+export function eventLedgerDiagnosticsForTests() { return { ...eventLedgerDiagnostics }; }
+export function resetEventLedgerDiagnosticsForTests() {
+    eventLedgerDiagnostics.reads = 0;
+    eventLedgerDiagnostics.locks = 0;
+    eventLedgerDiagnostics.replaces = 0;
+}
+function sortedEventRecords(records, request) {
+    return [...records].filter((record) => request.reachable.has(record.hash))
+        .sort((a, b) => (request.order.get(a.hash) ?? Number.MAX_SAFE_INTEGER) - (request.order.get(b.hash) ?? Number.MAX_SAFE_INTEGER));
+}
+function identityRecords(records, request) {
+    return sortedEventRecords(records, request).map((record) => {
+        if (!('identity' in record))
+            throw new Error('identity-raw ledger contained a text event');
+        return record.identity;
+    });
+}
+function renderEventStream(state, request) {
+    const records = sortedEventRecords(state.streams.get(request.kind)?.values() ?? [], request);
+    if (request.kind === 'identity-raw')
+        return records.map((record) => {
+            if (!('identity' in record))
+                throw new Error('identity-raw ledger contained a text event');
+            return record.identity;
+        });
+    return records.map((record) => {
+        if (!('raw' in record))
+            throw new Error(`history event stream '${request.kind}' contained a structured event`);
+        return RS + record.raw;
+    }).join('');
+}
+function appendEventRecord(state, kind, record, additions) {
+    let stream = state.streams.get(kind);
+    if (!stream) {
+        stream = new Map();
+        state.streams.set(kind, stream);
+    }
+    if (stream.has(record.hash))
+        return;
+    stream.set(record.hash, record);
+    additions.push('identity' in record
+        ? JSON.stringify({ k: kind, h: record.hash, d: record.identity.d, r: record.identity.r, s: record.identity.s, a: record.identity.a, c: record.identity.c.flat() }) + '\n'
+        : JSON.stringify({ k: kind, h: record.hash, r: record.raw }) + '\n');
+}
+function appendEventTip(state, kind, tip, additions) {
+    const tips = state.streamTips.get(kind) ?? [];
+    if (tips.includes(tip))
+        return;
+    tips.push(tip);
+    state.streamTips.set(kind, tips);
+    additions.push(JSON.stringify({ k: `tip:${kind}`, tip }) + '\n');
+}
+function appendImmutableHunkFact(state, key, ranges, additions) {
+    const existing = state.hunks.get(key);
+    if (existing) {
+        if (JSON.stringify(existing) !== JSON.stringify(ranges))
+            throw new Error(`immutable hunk ledger fact disagrees for image identity ${JSON.stringify(key)}`);
+        return;
+    }
+    state.hunks.set(key, ranges);
+    additions.push(JSON.stringify({ k: IMMUTABLE_HUNK_FACT, i: key, a: ranges.after, b: ranges.before }) + '\n');
+}
+function parseEventRecords(out, kind, location) {
+    if (kind === 'identity-raw')
+        return parseIdentityRawEventRecords(out, location);
+    const records = [];
+    for (const rec of out.split(RS)) {
+        const raw = rec.replace(/^\n/, '');
+        if (!raw)
+            continue;
+        const hash = raw.split(US, 1)[0].split('\n', 1)[0].trim();
+        if (!isGitObjectIdForFormat(location.objectFormat, hash))
+            throw new Error(`history event stream '${kind}' returned malformed object id '${hash || 'empty'}'`);
+        records.push({ hash, raw });
+    }
+    return records;
+}
+function indexEventRequests(root, tip, order, reachable) {
+    return {
+        'identity-raw': {
+            kind: 'identity-raw', order, reachable,
+            argsFor: (base) => ['-C', root, '-c', 'core.quotePath=false',
+                'log', '--root', '--full-history', '--date-order', '--no-diff-merges', '-M', '-l0', '--raw', '-z', '--no-abbrev', '--no-ext-diff', '--no-textconv',
+                `--format=${RS}%H%x00%aI%x00%s%x00%b%x00%(trailers:key=Spec-OK,valueonly,separator=%x2C)%x00`,
+                ...(base ? [`^${base}`] : []), tip],
+        },
+        merge: {
+            kind: 'merge', order, reachable,
+            argsFor: (base) => ['-C', root, '-c', 'core.quotePath=false',
+                'log', '--merges', '--raw', '--patch', '--cc', '--combined-all-paths', '--unified=0', '--no-color', '--no-ext-diff', '-M',
+                `--format=${RS}%H`, ...(base ? [`^${base}`] : []), tip],
+        },
+    };
+}
+async function strictEventGit(args) {
+    return gitRequiredA(args, 'cannot derive history events');
+}
+async function deriveEventStreams(root, tip, requests, persist = true, cache = true) {
+    if (!cache) {
+        const location = eventCacheLocation(root);
+        const outputs = await Promise.all(requests.map((request) => strictEventGit(request.argsFor(''))));
+        const rendered = new Map();
+        for (let index = 0; index < requests.length; index++) {
+            const request = requests[index];
+            rendered.set(request.kind, request.kind === 'identity-raw'
+                ? identityRecords(parseIdentityRawEventRecords(outputs[index], location), request)
+                : outputs[index]);
+        }
+        return rendered;
+    }
+    if (new Set(requests.map((request) => request.kind)).size !== requests.length)
+        throw new Error('one event-ledger transaction cannot request the same stream twice');
+    const build = activeEventLedger(root);
+    if (!build)
+        return withEventLedgerBuild(root, () => deriveEventStreams(root, tip, requests, persist, cache));
+    const { location, snapshot, additions } = build;
+    const missing = requests.filter((request) => !(snapshot.state.streamTips.get(request.kind) ?? []).includes(tip));
+    const outputs = await Promise.all(missing.map((request) => {
+        const base = [...(snapshot.state.streamTips.get(request.kind) ?? [])].reverse()
+            .find((candidate) => request.reachable.has(candidate)) ?? '';
+        return strictEventGit(request.argsFor(base));
+    }));
+    for (let index = 0; index < missing.length; index++) {
+        const request = missing[index];
+        for (const record of parseEventRecords(outputs[index], request.kind, location))
+            appendEventRecord(snapshot.state, request.kind, record, additions);
+        if (persist)
+            appendEventTip(snapshot.state, request.kind, tip, additions);
+    }
+    return new Map(requests.map((request) => [request.kind, renderEventStream(snapshot.state, request)]));
+}
+// Immutable hunk ranges are a ledger fact, not a second anchor cache: callers name their whole image-key
+// demand, receive only facts the shared ledger already certified, and derive/persist misses in their own read.
+export function readImmutableHunkFacts(root, keys) {
+    const wanted = new Set(keys);
+    if (!wanted.size)
+        return new Map();
+    const build = activeEventLedger(root);
+    if (!build)
+        return new Map();
+    const found = new Map();
+    for (const key of wanted) {
+        const ranges = build.snapshot.state.hunks.get(key);
+        if (ranges)
+            found.set(key, ranges);
+    }
+    return found;
+}
+export async function persistImmutableHunkFacts(root, facts) {
+    if (!facts.size)
+        return;
+    const build = activeEventLedger(root);
+    if (!build)
+        return withEventLedgerBuild(root, () => persistImmutableHunkFacts(root, facts));
+    for (const [key, ranges] of facts)
+        appendImmutableHunkFact(build.snapshot.state, key, ranges, build.additions);
+}
+async function eventStream(root, tip, request, persist = true, cache = true) {
+    const value = (await deriveEventStreams(root, tip, [request], persist, cache)).get(request.kind);
+    if (value === undefined)
+        throw new Error(`history event stream '${request.kind}' was not rendered`);
+    return value;
+}
+async function textEventStream(root, tip, request, persist = true, cache = true) {
+    const value = await eventStream(root, tip, request, persist, cache);
+    if (typeof value !== 'string')
+        throw new Error(`history event stream '${request.kind}' rendered structured data`);
+    return value;
+}
+async function identityRawEventStream(root, tip, request, persist = true, cache = true) {
+    const value = await eventStream(root, tip, request, persist, cache);
+    if (!Array.isArray(value) || value.some((record) => !('a' in record)))
+        throw new Error(`history event stream '${request.kind}' rendered text`);
+    return value;
+}
+export async function gitTry(args, options = {}) {
+    const env = { ...process.env };
+    for (const [key, value] of Object.entries(options.extraEnv ?? {})) {
+        if (value === undefined)
+            delete env[key];
+        else
+            env[key] = value;
+    }
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    delete env.GIT_OBJECT_DIRECTORY;
+    if (options.indexFile)
+        env.GIT_INDEX_FILE = options.indexFile;
+    const context = inheritedContext();
+    try {
+        const { stdout, stderr } = await execGitForCaller(args, env, undefined, options.input);
+        return { ok: true, stdout: stdout.toString('utf8'), stderr };
+    }
+    catch (e) {
+        if (context?.signal.aborted || e?.name === 'AbortError')
+            throw e;
+        warnIfTimedOut(e, args);
+        const failure = e?.spexcodeGitTimeout ? 'timeout' : typeof e?.code === 'number' ? 'exit' : 'spawn';
+        return { ok: false, stdout: e?.stdout ?? '', stderr: e?.stderr ?? String(e?.message ?? e), failure };
+    }
+}
+// A walk whose OUTPUT is a projection the caller is intentionally building reads through the streamed
+// transport (no fixed stdout bound); `input` lets its revision roster ride stdin, so argv cannot grow with
+// the roster and needs no chunking.
+export async function gitRequiredA(args, purpose, options = {}) {
+    const env = { ...process.env };
+    for (const [key, value] of Object.entries(options.extraEnv ?? {})) {
+        if (value === undefined)
+            delete env[key];
+        else
+            env[key] = value;
+    }
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    delete env.GIT_OBJECT_DIRECTORY;
+    try {
+        return (await execGitStreamForCaller(args, env, options.input)).stdout.toString('utf8');
+    }
+    catch (error) {
+        if (error?.name === 'AbortError')
+            throw error;
+        warnIfTimedOut(error, args);
+        throw new Error(`${purpose}: git ${args.slice(2).join(' ')} failed: ${String(error?.stderr || error?.message || 'unknown git error').trim()}`);
+    }
+}
+// memoized: repoRoot is constant per process, but resolveLayout() calls it per request — avoid a git fork each time.
+let repoRootCache = null;
+export function repoRoot() {
+    if (repoRootCache !== null)
+        return repoRootCache;
+    try {
+        repoRootCache = git(['rev-parse', '--show-toplevel']).trim();
+    }
+    catch {
+        repoRootCache = process.cwd();
+    }
+    return repoRootCache;
+}
+function gitDirOf(root) {
+    // a normal checkout has a `.git` DIRECTORY; a linked worktree has a `.git` FILE: `gitdir: <path>`.
+    const dotgit = join(root, '.git');
+    if (!existsSync(dotgit)) {
+        try {
+            if (git(['-C', root, 'rev-parse', '--is-bare-repository']).trim() === 'true')
+                return root;
+        }
+        catch { /* the caller will receive the same loud path error as a malformed checkout */ }
+        throw new Error(`headSha: no .git directory at ${dotgit}`);
+    }
+    if (statSync(dotgit).isDirectory())
+        return dotgit;
+    const m = readFileSync(dotgit, 'utf8').match(/^gitdir:\s*(.+)$/m);
+    if (!m)
+        throw new Error(`headSha: unparseable .git file at ${dotgit}`);
+    const dir = m[1].trim();
+    return isAbsolute(dir) ? dir : resolve(root, dir);
+}
+function commonDirOf(gitDir) {
+    // a worktree's gitdir holds per-worktree state (HEAD); SHARED refs (refs/heads/*, packed-refs) live
+    // in the common dir, named by the `commondir` pointer. A plain checkout IS its own common dir.
+    const p = join(gitDir, 'commondir');
+    if (!existsSync(p))
+        return gitDir;
+    const c = readFileSync(p, 'utf8').trim();
+    return isAbsolute(c) ? c : resolve(gitDir, c);
+}
+export function headSha(root) {
+    const gitDir = gitDirOf(root);
+    const head = readFileSync(join(gitDir, 'HEAD'), 'utf8').trim();
+    const ref = head.match(/^ref:\s*(.+)$/);
+    if (!ref)
+        return head; // detached HEAD: the file already holds the sha
+    const name = ref[1].trim();
+    // a loose ref wins over packed; per-worktree HEAD points at a branch whose ref lives in the common dir.
+    const looseWt = join(gitDir, name);
+    if (existsSync(looseWt))
+        return readFileSync(looseWt, 'utf8').trim();
+    const common = commonDirOf(gitDir);
+    const loose = join(common, name);
+    if (existsSync(loose))
+        return readFileSync(loose, 'utf8').trim();
+    const packed = join(common, 'packed-refs');
+    if (existsSync(packed)) {
+        for (const line of readFileSync(packed, 'utf8').split('\n')) {
+            if (!line || line[0] === '#' || line[0] === '^')
+                continue;
+            const sp = line.indexOf(' ');
+            if (sp > 0 && line.slice(sp + 1).trim() === name)
+                return line.slice(0, sp).trim();
+        }
+    }
+    // an UNBORN HEAD — a fresh `git init` with no commits — points at a branch ref that doesn't exist yet.
+    // That is a valid EMPTY-HISTORY state, not a failure: the board renders fine from the working tree. Return
+    // a stable, truthy sentinel so historyIndex/driftIndex/safeHead MEMOIZE it (the head value is only ever a
+    // cache key, never a git ref) instead of re-forking git on every read; headOrEmpty's warning is then
+    // reserved for a genuinely unreadable HEAD and never fires for this routine first-run state.
+    return `unborn:${name}`;
+}
+function isUnbornHistoryTip(tip) { return tip.startsWith('unborn:'); }
+// fingerprint of a worktree's `.spec` working tree by path + mtimeMs + size (no git); the overlay-cache
+// key for its working-tree state. '' when `.spec` is absent.
+export function worktreeSpecSig(wtPath) {
+    const root = join(wtPath, '.spec');
+    if (!existsSync(root))
+        return '';
+    const parts = [];
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let ents;
+        try {
+            ents = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of ents) {
+            const p = join(dir, e.name);
+            if (e.isDirectory()) {
+                stack.push(p);
+                continue;
+            }
+            try {
+                const st = statSync(p);
+                parts.push(`${p}:${st.mtimeMs}:${st.size}`);
+            }
+            catch { /* vanished mid-walk */ }
+        }
+    }
+    return parts.sort().join('\n');
+}
+function emptyHistoryIndex() {
+    return { versions: new Map(), contentVersions: new Set(), versionPaths: new Map(), mergeVersions: new Set() };
+}
+function isRawObjectId(value, format) {
+    const length = format === 'sha256' ? 64 : 40;
+    return isGitObjectIdForFormat(format, value) || (value.length === length && /^0+$/.test(value));
+}
+function parseIdentityRawEventRecords(out, location) {
+    const parsed = [];
+    let current = null;
+    const tokens = out.split('\0');
+    let index = 0;
+    const metadata = (field) => {
+        const token = tokens[index++];
+        if (token === undefined)
+            throw new Error(`raw identity stream ended before commit ${field}`);
+        return token;
+    };
+    const begin = (token) => {
+        const header = token.startsWith('\n') ? token.slice(1) : token;
+        if (!header.startsWith(RS))
+            throw new Error(`raw identity stream expected a commit header, got '${header}'`);
+        const hash = header.slice(RS.length);
+        if (!isGitObjectIdForFormat(location.objectFormat, hash))
+            throw new Error(`history event stream 'identity-raw' returned malformed object id '${hash || 'empty'}'`);
+        if (current)
+            parsed.push(current);
+        const date = metadata('date'), reason = metadata('subject'), body = metadata('body'), ack = metadata('trailers');
+        const session = body.match(/Session:\s*(\S+)/);
+        return { h: hash, d: date, r: reason, s: session ? session[1] : null, a: ack, c: [] };
+    };
+    while (index < tokens.length) {
+        const token = tokens[index++];
+        if (!current) {
+            if (!token)
+                continue;
+            current = begin(token);
+            continue;
+        }
+        const value = token.startsWith('\n') ? token.slice(1) : token;
+        if (!value)
+            continue;
+        if (value.startsWith(RS)) {
+            current = begin(value);
+            continue;
+        }
+        const raw = value.match(/^:([0-7]{6}) ([0-7]{6}) ([0-9a-f]+) ([0-9a-f]+) ([A-Z])(?:\d+)?$/);
+        if (!raw || !isRawObjectId(raw[3], location.objectFormat) || !isRawObjectId(raw[4], location.objectFormat))
+            throw new Error(`raw identity event ${current.h} has malformed raw record '${value}'`);
+        const from = tokens[index++];
+        if (from === undefined)
+            throw new Error(`raw identity event ${current.h} ended before its path`);
+        const to = raw[5] === 'R' ? tokens[index++] : from;
+        if (to === undefined)
+            throw new Error(`raw identity event ${current.h} ended before its rename destination`);
+        current.c.push([raw[5], from, to, raw[3], raw[4]]);
+    }
+    if (current)
+        parsed.push(current);
+    return parsed.map((identity) => ({ hash: identity.h, identity }));
+}
+function decodeIdentityRawRecord(value, hash, location) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    if (!exactKeys(record, ['a', 'c', 'd', 'r', 's']) || typeof record.a !== 'string' || typeof record.d !== 'string'
+        || typeof record.r !== 'string' || (typeof record.s !== 'string' && record.s !== null) || !Array.isArray(record.c) || record.c.length % 5)
+        return null;
+    const changes = [];
+    for (let index = 0; index < record.c.length; index += 5) {
+        if (typeof record.c[index] !== 'string' || typeof record.c[index + 1] !== 'string' || typeof record.c[index + 2] !== 'string'
+            || typeof record.c[index + 3] !== 'string' || typeof record.c[index + 4] !== 'string'
+            || !/^[A-Z](?:\d+)?$/.test(record.c[index]) || !isRawObjectId(record.c[index + 3], location.objectFormat)
+            || !isRawObjectId(record.c[index + 4], location.objectFormat))
+            return null;
+        changes.push([record.c[index], record.c[index + 1], record.c[index + 2], record.c[index + 3], record.c[index + 4]]);
+    }
+    return { h: hash, d: record.d, r: record.r, s: record.s, a: record.a, c: changes };
+}
+// Both bulk indices are pure functions of a checkout's HEAD, and they are read for SEVERAL roots at
+// once — the backend checkout (board, loadSpecs) plus every session worktree ([[session-eval]]'s eval
+// tab roots its readings at the session's branch). A single-slot cache thrashes between those roots:
+// each eval-tab request evicts the board's entry and vice versa, so every request re-runs a full-history
+// `git log` and re-parses it on the event loop — which is what starves every other request (the board,
+// remark posts) under load. So the cache is a small LRU keyed by interpretation identity + HEAD, holding
+// the in-flight PROMISE so concurrent requests for one immutable view share a single build.
+const indexCache = new Map();
+const indexRoots = new Map();
+const driftRoots = new Map();
+const driftIdxCache = new Map();
+const INDEX_ROOT_SLOTS = rootSlots(process.env.SPEXCODE_INDEX_CACHE_ROOTS, 32);
+function rootKey(root) { return resolve(root); }
+function indexCacheKey(root, head) { return `${eventCacheLocation(root).path}\0${head}`; }
+// A project-namespaced ledger path plus HEAD identifies immutable index contents. Its path is scoped to the
+// common Git store and interpretation state, so linked worktrees share while independent same-HEAD clones do not.
+// The checkout root owns which live view is useful; the root bound keeps closed worktrees from leaking.
+// The bookkeeping itself is [[root-lru]]'s — this only names the store and the bound.
+function touchRoot(roots, cache, root, cacheKey) {
+    touchRootLru(roots, cache, rootKey(root), cacheKey, INDEX_ROOT_SLOTS);
+}
+function dropFailed(cache, head, promise) {
+    if (cache.get(head) !== promise)
+        return;
+    // A rejected index is never reusable, even when its root still points at that HEAD. The next read must
+    // start a fresh walk after a watchdog abort or transient git failure.
+    cache.delete(head);
+}
+function pendingOnlyIssues(root, tip) {
+    try {
+        const parents = git(['-C', root, 'rev-list', '--parents', '-n1', tip]).trim().split(/\s+/).filter(Boolean);
+        // A first-parent issue diff can hide side-branch code debt in an ours merge. Only a single-parent
+        // candidate may reuse its parent's indexes; every merge must build the candidate's full reachable view.
+        if (parents.length !== 2)
+            return false;
+        const parent = git(['-C', root, 'rev-parse', `${tip}^`]).trim();
+        const paths = git(['-C', root, 'diff-tree', '--no-commit-id', '--name-only', '-r', parent, tip])
+            .split('\n').map((p) => p.trim()).filter(Boolean);
+        return paths.length > 0 && paths.every((p) => p.startsWith('.spec/.issues/'));
+    }
+    catch {
+        return false;
+    }
+}
+function pendingParent(root, tip) {
+    try {
+        const parent = git(['-C', root, 'rev-parse', `${tip}^`]).trim();
+        return isGitObjectId(root, parent) ? parent : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function historyIndex(root, tip = 'HEAD') {
+    if (tip !== 'HEAD') {
+        const resolved = git(['-C', root, 'rev-parse', `${tip}^{commit}`]).trim();
+        // An issue-only candidate changes no governed content, but its lint result still includes the
+        // parent's existing drift/related-drift warnings. Reuse that immutable parent index instead of
+        // manufacturing an empty one (which silently dropped warnings at golden depths).
+        if (pendingOnlyIssues(root, resolved)) {
+            const parent = pendingParent(root, resolved);
+            if (parent) {
+                const head = headOrEmpty(root);
+                if (head === parent)
+                    return historyIndex(root);
+                return buildIndex(root, parent, true, true);
+            }
+        }
+        return buildIndex(root, resolved, true, true);
+    }
+    const head = headOrEmpty(root);
+    if (!head)
+        return buildIndex(root, 'HEAD', false, true);
+    const cacheKey = indexCacheKey(root, head);
+    touchRoot(indexRoots, indexCache, root, cacheKey);
+    const hit = indexCache.get(cacheKey);
+    if (hit)
+        return hit;
+    const p = buildIndex(root, head, false, true);
+    p.catch(() => { dropFailed(indexCache, cacheKey, p); }); // don't pin a failed build
+    indexCache.set(cacheKey, p);
+    return p;
+}
+// resolve HEAD for cache-keying, '' if unreadable (fails the cache test → recompute); warns once.
+let headWarned = false;
+function headOrEmpty(root) {
+    try {
+        return headSha(root);
+    }
+    catch (e) {
+        if (!headWarned) {
+            headWarned = true;
+            console.warn(`spec-cli: headSha failed, recomputing every read: ${e.message}`);
+        }
+        return '';
+    }
+}
+// @@@ reachability memoized on the rename side, never the event side - every comparison the projector makes
+// has a RENAME commit on one end, and a history holds far fewer renames than file events. Keying the memo on
+// the OTHER end rebuilds a history-wide ancestor set per distinct event commit: 2.3M parent-edge visits and
+// 1,219 retained bitsets served 9k one-bit questions on this repository. That end builds one closure per
+// distinct event commit actually compared against a rename — C of them, O(C(H+G)) construction and Θ(CH) bits
+// — which a linear history whose events all sit on one renamed path drives to Θ(H²). Asking the rename end
+// instead — its descendants when it is the older commit, its ancestors when it is the newer one — moves ONLY
+// the closure term onto the rename count K: at most 2K full-size closures, O(K(H+G)) construction over H
+// reachable commits and G parent edges, O(KH) bits. That 2K ceiling bounds closure buffers, count and bytes,
+// against C; it does NOT bound runtime or edge visits, since a rename with many unrelated descendants
+// traverses ground the event-side ancestor walk never touched. The projector's own work is unchanged and is
+// NOT covered by that term: one scan of the N events, plus a lineage walk whose frontier compares each step's
+// applicable renames pairwise — Σ d(candidate)² O(1) queries, worst case Θ(NK²) when one path carries K
+// mutually incomparable renames. So: no linear-in-history promise — at K≈H the closure term is O(H(H+G)),
+// quadratic only where the DAG is sparse enough that G=O(H), and the untouched frontier term is cubic when
+// N, K and H grow together. It is also why a
+// reachability matrix over the rename commits is not worth it: same O(KH) bits, but eagerly.
+function renameSideReachability(renameCommits, topology) {
+    const { order, parents } = topology;
+    const size = (order.size + 7) >> 3;
+    let childEdges = null;
+    const children = () => {
+        if (childEdges)
+            return childEdges;
+        childEdges = new Map();
+        for (const [hash] of order)
+            for (const parent of parents.get(hash) ?? []) {
+                if (!order.has(parent))
+                    continue; // shallow boundary: an unwalked parent ends the chain
+                const kids = childEdges.get(parent);
+                if (kids)
+                    kids.push(hash);
+                else
+                    childEdges.set(parent, [hash]);
+            }
+        return childEdges;
+    };
+    const closure = (start, edges, memo) => {
+        const hit = memo.get(start);
+        if (hit)
+            return hit;
+        const bits = new Uint8Array(size);
+        const at = order.get(start);
+        bits[at >> 3] |= 1 << (at & 7);
+        const stack = [start];
+        while (stack.length)
+            for (const next of edges.get(stack.pop()) ?? []) {
+                const position = order.get(next);
+                if (position === undefined)
+                    continue;
+                const mask = 1 << (position & 7);
+                if (bits[position >> 3] & mask)
+                    continue;
+                bits[position >> 3] |= mask;
+                stack.push(next);
+            }
+        memo.set(start, bits);
+        return bits;
+    };
+    const ancestors = new Map(), descendants = new Map();
+    return (older, newer) => {
+        const from = order.get(older), to = order.get(newer);
+        if (from === undefined || to === undefined)
+            throw new Error(`rename projection cannot place ${older} against ${newer} in the current topology`);
+        // Whichever end is the rename owns the closure; the projector always puts one there.
+        return renameCommits.has(older)
+            ? (closure(older, children(), descendants)[to >> 3] & (1 << (to & 7))) !== 0
+            : (closure(newer, parents, ancestors)[from >> 3] & (1 << (from & 7))) !== 0;
+    };
+}
+function canonicalPathProjector(renamesByFrom, topology) {
+    const renameCommits = new Set();
+    for (const renames of renamesByFrom.values())
+        for (const rename of renames)
+            renameCommits.add(rename.hash);
+    const precedes = renameSideReachability(renameCommits, topology);
+    return (path, event) => {
+        // A path no rename ever left keeps its own identity at every event; there is no lineage to walk.
+        if (!renamesByFrom.has(path))
+            return [path];
+        const pending = [path], resolved = new Set(), seen = new Set();
+        while (pending.length) {
+            const candidate = pending.pop();
+            if (seen.has(candidate)) {
+                resolved.add(candidate);
+                continue;
+            }
+            seen.add(candidate);
+            const unique = new Map();
+            for (const rename of renamesByFrom.get(candidate) ?? []) {
+                if (!precedes(rename.hash, event))
+                    unique.set(`${rename.hash}\0${rename.to}`, rename);
+            }
+            const applicable = [...unique.values()];
+            if (!applicable.length) {
+                resolved.add(candidate);
+                continue;
+            }
+            // The earliest applicable rename starts this path's next lineage epoch. Later renames from the same
+            // path belong to a recreated path, not to an event that predates the first boundary. Incomparable
+            // rename branches are both frontier members, so their identities still fork at the merge. A merge can
+            // expose the same rename once per parent; equal-commit rows are peers, never ancestors of one another.
+            const frontier = applicable.filter((rename, index) => !applicable.some((other, otherIndex) => otherIndex !== index
+                && other.hash !== rename.hash && precedes(other.hash, rename.hash)));
+            if (frontier.some((rename) => !precedes(event, rename.hash)))
+                resolved.add(candidate);
+            for (const rename of frontier)
+                pending.push(rename.to);
+        }
+        return [...resolved];
+    };
+}
+async function buildIndex(root, tip, transient, useCache = true, shared) {
+    if (isUnbornHistoryTip(tip))
+        return emptyHistoryIndex();
+    const versions = new Map();
+    const contentVersions = new Set();
+    const versionPaths = new Map();
+    const mergeVersions = new Set();
+    const commitVersions = new Map();
+    const commitOrder = new Map();
+    const rawVersions = new Map();
+    let currentPaths;
+    let topology;
+    if (shared) {
+        currentPaths = shared.specPaths;
+        topology = shared.topology;
+    }
+    else {
+        const [tipPathsOut, topologyOut] = await Promise.all([
+            strictEventGit(['-C', root, '-c', 'core.quotePath=false', 'ls-tree', '-r', '-z', '--name-only', tip, '--', '.spec']),
+            strictEventGit(['-C', root, 'rev-list', '--parents', tip]),
+        ]);
+        currentPaths = new Set(tipPathsOut.split('\0').filter((path) => path.startsWith('.spec/')));
+        topology = topologyProjection(topologyOut);
+    }
+    const renamesByFrom = new Map();
+    const topologyOrd = topology.order;
+    const topologyParents = topology.parents;
+    const topologyReachable = topology.reachable;
+    const identityRecords = shared?.identityRecords ?? await identityRawEventStream(root, tip, indexEventRequests(root, tip, topologyOrd, topologyReachable)['identity-raw'], !transient, useCache);
+    if (!identityRecords.length)
+        return { versions, contentVersions, versionPaths, mergeVersions };
+    let commitPosition = 0;
+    const rawContent = new Set();
+    for (const record of identityRecords) {
+        const version = { hash: record.h, date: record.d, reason: record.r, session: record.s };
+        commitVersions.set(record.h, version);
+        if (!commitOrder.has(record.h))
+            commitOrder.set(record.h, commitPosition++);
+        for (const [, from, to, oldOid, newOid] of record.c) {
+            if (!from.startsWith('.spec/') && !to.startsWith('.spec/'))
+                continue;
+            if (!rawVersions.has(to))
+                rawVersions.set(to, []);
+            rawVersions.get(to).push(version);
+            if (oldOid !== newOid)
+                rawContent.add(`${to}\0${record.h}`);
+            if (from !== to) {
+                const renames = renamesByFrom.get(from) ?? [];
+                renames.push({ hash: record.h, to });
+                renamesByFrom.set(from, renames);
+            }
+        }
+    }
+    // Re-establish Git's date-order contract after records are parsed from a stream. An independent commit
+    // can appear before its child in a date-ordered result; repair that partial-order constraint with a stable
+    // topological pass. A comparator that
+    // materializes an ancestor Set/bitset for every sort comparison turns a 4k-commit history into an
+    // accidental quadratic walk; this queue visits each commit and parent edge once.
+    const originalOrder = new Map(commitOrder);
+    const childrenLeft = new Map();
+    for (const hash of commitVersions.keys())
+        childrenLeft.set(hash, 0);
+    for (const hash of commitVersions.keys())
+        for (const parent of topologyParents.get(hash) ?? [])
+            if (childrenLeft.has(parent))
+                childrenLeft.set(parent, childrenLeft.get(parent) + 1);
+    const heap = [];
+    const before = (a, b) => (originalOrder.get(a) ?? Number.MAX_SAFE_INTEGER) - (originalOrder.get(b) ?? Number.MAX_SAFE_INTEGER);
+    const push = (hash) => {
+        let i = heap.push(hash) - 1;
+        while (i > 0) {
+            const parent = (i - 1) >> 1;
+            if (before(heap[parent], hash) <= 0)
+                break;
+            heap[i] = heap[parent];
+            i = parent;
+        }
+        heap[i] = hash;
+    };
+    const pop = () => {
+        const first = heap[0], last = heap.pop();
+        if (heap.length) {
+            let i = 0;
+            while (true) {
+                const left = i * 2 + 1;
+                if (left >= heap.length)
+                    break;
+                let child = left;
+                const right = left + 1;
+                if (right < heap.length && before(heap[right], heap[left]) < 0)
+                    child = right;
+                if (before(heap[child], last) >= 0)
+                    break;
+                heap[i] = heap[child];
+                i = child;
+            }
+            heap[i] = last;
+        }
+        return first;
+    };
+    for (const [hash, left] of childrenLeft)
+        if (left === 0)
+            push(hash);
+    const ordered = [];
+    while (heap.length) {
+        const hash = pop();
+        ordered.push(hash);
+        for (const parent of topologyParents.get(hash) ?? []) {
+            if (!childrenLeft.has(parent))
+                continue;
+            const left = childrenLeft.get(parent) - 1;
+            childrenLeft.set(parent, left);
+            if (left === 0)
+                push(parent);
+        }
+    }
+    // A shallow or malformed topology should fail closed rather than silently dropping a version row.
+    if (ordered.length !== commitVersions.size)
+        for (const hash of commitVersions.keys())
+            if (!ordered.includes(hash))
+                ordered.push(hash);
+    commitOrder.clear();
+    ordered.forEach((hash, i) => commitOrder.set(hash, i));
+    const mergeIndex = shared?.mergeIndex
+        ?? await mergeHistoryEvents(root, tip, transient, topologyOrd, topologyReachable, useCache);
+    for (const rename of mergeIndex.renames) {
+        const renames = renamesByFrom.get(rename.from) ?? [];
+        renames.push({ hash: rename.hash, to: rename.to });
+        renamesByFrom.set(rename.from, renames);
+    }
+    const canonical = canonicalPathProjector(renamesByFrom, topology);
+    for (const [path, pathRows] of rawVersions) {
+        for (const row of pathRows)
+            for (const head of canonical(path, row.hash).filter((candidate) => currentPaths.has(candidate))) {
+                const rows = versions.get(head) ?? [];
+                if (!rows.some((existing) => existing.hash === row.hash))
+                    rows.push(row);
+                versions.set(head, rows);
+                const key = `${head}\0${row.hash}`;
+                if (rawContent.has(`${path}\0${row.hash}`))
+                    contentVersions.add(key);
+                if (!versionPaths.has(key))
+                    versionPaths.set(key, path);
+            }
+    }
+    for (const [path, mergeEvents] of mergeIndex.resolutions) {
+        if (!isSpecMd(path))
+            continue;
+        for (const { hash } of mergeEvents)
+            for (const head of canonical(path, hash)) {
+                const rows = versions.get(head) ?? [];
+                const version = commitVersions.get(hash);
+                if (!version || rows.some((row) => row.hash === hash))
+                    continue;
+                rows.push(version);
+                const key = `${head}\0${hash}`;
+                mergeVersions.add(key);
+                if (!versionPaths.has(key))
+                    versionPaths.set(key, path);
+                versions.set(head, rows);
+            }
+    }
+    for (const rows of versions.values()) {
+        rows.sort((a, b) => (commitOrder.get(a.hash) ?? Number.MAX_SAFE_INTEGER) - (commitOrder.get(b.hash) ?? Number.MAX_SAFE_INTEGER));
+    }
+    return { versions, contentVersions, versionPaths, mergeVersions };
+}
+// Pure lookups over a prebuilt index. Blob identity decides whether a one-parent row is a content version;
+// numstat remains display data and must not let attributes erase a version window.
+export function rowsFor(idx, relPath) {
+    const rows = idx.versions.get(relPath) ?? [];
+    return rows.filter((v) => idx.contentVersions.has(`${relPath}\0${v.hash}`) || idx.mergeVersions?.has(`${relPath}\0${v.hash}`));
+}
+// per-commit numstat summed over a SET of paths in one `git log` walk. No `--follow` (it takes a single
+// path), so no rename-tracking — same as the old `git show -- paths`; spec.md gets renames via the bulk index.
+export async function pathsStats(root, paths) {
+    const m = new Map();
+    if (!paths.length)
+        return m;
+    const out = await gitA(['-C', root, '-c', 'core.quotePath=false', 'log', '--format=%H', '--numstat', '--', ...paths]);
+    if (!out)
+        return m;
+    let cur = '';
+    for (const line of out.split('\n')) {
+        const t = line.trim();
+        if (isGitObjectId(root, t)) {
+            cur = t;
+            continue;
+        }
+        const n = line.match(/^(\d+|-)\t(\d+|-)\t/);
+        if (n && cur) {
+            const s = m.get(cur) ?? { additions: 0, deletions: 0, files: 0 };
+            s.files++;
+            s.additions += n[1] === '-' ? 0 : +n[1];
+            s.deletions += n[2] === '-' ? 0 : +n[2];
+            m.set(cur, s);
+        }
+    }
+    return m;
+}
+// History display stats are intentionally read only for the selected node: their text interpretation may
+// depend on working-tree attributes, so they cannot live in the shared immutable event ledger. One diff-tree
+// batch preserves every selected commit's historical path without turning a history page into N processes.
+export async function historyStats(root, idx, relPath) {
+    const rows = rowsFor(idx, relPath);
+    if (!rows.length)
+        return new Map();
+    const paths = new Map(rows.map((row) => [row.hash, idx.versionPaths.get(`${relPath}\0${row.hash}`) ?? relPath]));
+    const out = await gitA(['-C', root, '-c', 'core.quotePath=false', 'diff-tree', '--stdin', '--root', '-r', '--numstat', '-M', '-l0', `--format=${RS}%H`], `${rows.map((row) => row.hash).join('\n')}\n`);
+    const stats = new Map();
+    for (const record of out.split(RS)) {
+        const lines = record.replace(/^\n/, '').split('\n');
+        const hash = lines.shift()?.trim() ?? '';
+        const path = paths.get(hash);
+        if (!path)
+            continue;
+        const stat = { additions: 0, deletions: 0, files: 0 };
+        for (const line of lines) {
+            const match = line.match(/^(\d+|-)\t(\d+|-)\t(.+)$/);
+            if (!match || parseStatPath(match[3]).to !== path)
+                continue;
+            stat.files++;
+            stat.additions += match[1] === '-' ? 0 : Number(match[1]);
+            stat.deletions += match[2] === '-' ? 0 : Number(match[2]);
+        }
+        stats.set(hash, stat);
+    }
+    return stats;
+}
+// the patch a spec.md got in one commit (vs parent); resolve its path AT that commit (reparents move it)
+// via the stable leaf dir `…/<id>/spec.md`, then `git show` that path. `-M` keeps a rename+edit's body. '' on error.
+export async function fileDiffAt(root, relPath, hash) {
+    if (!hash || !relPath.endsWith('/spec.md'))
+        return '';
+    const leaf = relPath.slice(relPath.lastIndexOf('/', relPath.length - '/spec.md'.length - 1) + 1); // `<id>/spec.md`
+    const names = await gitA(['-C', root, '-c', 'core.quotePath=false', 'show', '--name-only', '--format=', '-M', hash]);
+    const at = names.split('\n').map((s) => s.trim()).find((p) => p.endsWith('/' + leaf) || p === leaf) ?? relPath;
+    return gitA(['-C', root, '-c', 'core.quotePath=false', 'show', '-M', '--format=', hash, '--', at]);
+}
+function emptyDriftIndex() {
+    return {
+        ord: new Map(), parents: new Map(), fileEvents: new Map(), lineageEvents: new Map(),
+        lineageKeys: (path) => [path], resolutionEvents: new Map(), acks: new Map(), selfAcks: new Map(),
+        specNodes: new Map(), anc: new Map(),
+    };
+}
+function decodeGitCPath(value) {
+    if (!value.startsWith('"'))
+        return value;
+    if (value.length < 2 || !value.endsWith('"'))
+        throw new Error(`malformed Git C-quoted path '${value}'`);
+    const bytes = [];
+    const plain = (part) => bytes.push(...Buffer.from(part, 'utf8'));
+    for (let index = 1; index < value.length - 1;) {
+        const point = value.codePointAt(index);
+        const char = String.fromCodePoint(point);
+        index += char.length;
+        if (char !== '\\') {
+            plain(char);
+            continue;
+        }
+        const escaped = value[index++];
+        if (escaped === undefined)
+            throw new Error(`malformed Git C-quoted path '${value}'`);
+        const simple = { a: 7, b: 8, f: 12, n: 10, r: 13, t: 9, v: 11, '"': 34, '\\': 92 };
+        if (escaped in simple) {
+            bytes.push(simple[escaped]);
+            continue;
+        }
+        const octal = `${escaped}${value.slice(index, index + 2)}`;
+        if (!/^[0-7]{3}$/.test(octal))
+            throw new Error(`malformed Git C-quoted path '${value}'`);
+        bytes.push(Number.parseInt(octal, 8));
+        index += 2;
+    }
+    return Buffer.from(bytes).toString('utf8');
+}
+// Dense combined diff prefixes have one column per parent. Ownership is a LINE fact, not a hunk fact:
+// all `+` means the result authored a line absent from every parent; all `-` means it deleted a line present
+// in every parent. Mixed columns inherit from at least one parent. Track every cursor through all displayed
+// lines so adjacent mixed/owned rows never widen one another.
+export function combinedDiffOwnedChanges(patch) {
+    const byPath = new Map();
+    let path = null;
+    let parents = 0;
+    let parentLines = [];
+    let parentPaths = [];
+    let resultLine = 0;
+    let inHunk = false;
+    for (const line of patch.split('\n')) {
+        if (line.startsWith('diff --cc ')) {
+            path = decodeGitCPath(line.slice('diff --cc '.length));
+            parents = 0;
+            parentPaths = [];
+            inHunk = false;
+            continue;
+        }
+        if (!inHunk && path !== null && line.startsWith('--- ')) {
+            const raw = decodeGitCPath(line.slice(4));
+            parentPaths.push(raw === '/dev/null' ? path : raw.replace(/^a\//, ''));
+            continue;
+        }
+        const header = line.match(/^(@{3,}) ((?:-\d+(?:,\d+)? )+)\+(\d+)(?:,\d+)? @+/);
+        if (header) {
+            parents = header[1].length - 1;
+            parentLines = [...header[2].matchAll(/-(\d+)/g)].map((match) => Number(match[1]));
+            resultLine = Number(header[3]);
+            inHunk = path !== null && parents >= 2 && parentLines.length === parents;
+            continue;
+        }
+        if (!inHunk || path === null || line.startsWith('\'))
+            continue;
+        const prefix = line.slice(0, parents);
+        if (prefix.length !== parents || !/^[ +\-]+$/.test(prefix)) {
+            inHunk = false;
+            continue;
+        }
+        const authoredAfter = [...prefix].every((c) => c === '+');
+        const authoredBefore = [...prefix].every((c) => c === '-');
+        if ((authoredAfter || authoredBefore) && parentPaths.length !== parents)
+            throw new Error(`combined diff for '${path}' declared ${parents} parents but exposed ${parentPaths.length} parent paths`);
+        const changes = byPath.get(path) ?? {
+            after: [],
+            before: Array.from({ length: parents }, () => []),
+            parentPaths: [...parentPaths],
+        };
+        if (authoredAfter)
+            changes.after.push([Math.max(1, resultLine), Math.max(1, resultLine)]);
+        if (authoredBefore) {
+            for (let parent = 0; parent < parents; parent++) {
+                const point = Math.max(1, parentLines[parent]);
+                changes.before[parent].push([point, point]);
+            }
+        }
+        if (authoredAfter || authoredBefore)
+            byPath.set(path, changes);
+        const resultExists = prefix.includes('+') || [...prefix].every((c) => c === ' ');
+        for (let parent = 0; parent < parents; parent++)
+            if (prefix[parent] === '-' || (prefix[parent] === ' ' && resultExists))
+                parentLines[parent]++;
+        if (resultExists)
+            resultLine++;
+    }
+    return byPath;
+}
+function parseMergeHistoryEvents(out) {
+    const resolutions = new Map();
+    const renames = [];
+    for (const rec of out.split(RS)) {
+        const normalized = rec.replace(/^\n/, '');
+        const newline = normalized.indexOf('\n');
+        const hash = (newline < 0 ? normalized : normalized.slice(0, newline)).trim();
+        if (!hash)
+            continue;
+        const patch = newline < 0 ? '' : normalized.slice(newline + 1);
+        for (const line of patch.split('\n')) {
+            const raw = line.match(/^(:{2,})[0-7]{6}(?: [0-7]{6})+ (?:[0-9a-f]+ )+[A-Z]+\t/);
+            if (!raw)
+                continue;
+            const parentCount = raw[1].length;
+            const fields = line.split('\t');
+            const status = fields[0].trim().split(/\s+/).at(-1) ?? '';
+            const paths = fields.slice(1).map(decodeGitCPath);
+            if (status.length !== parentCount || paths.length !== parentCount + 1)
+                throw new Error(`combined raw diff for ${hash} exposed ${status.length} statuses and ${paths.length} paths for ${parentCount} parents`);
+            const resultPath = paths[parentCount];
+            for (let parent = 0; parent < parentCount; parent++) {
+                if (status[parent] !== 'R' || paths[parent] === resultPath)
+                    continue;
+                renames.push({ hash, from: paths[parent], to: resultPath });
+            }
+        }
+        for (const [path, changes] of combinedDiffOwnedChanges(patch)) {
+            const events = resolutions.get(path) ?? [];
+            events.push({ hash, parentPaths: changes.parentPaths });
+            resolutions.set(path, events);
+        }
+    }
+    return { resolutions, renames };
+}
+async function mergeHistoryEvents(root, tip, transient, order, reachable, useCache = true) {
+    if (!useCache)
+        return parseMergeHistoryEvents(await strictEventGit(['-C', root, '-c', 'core.quotePath=false',
+            'log', '--merges', '--raw', '--patch', '--cc', '--combined-all-paths', '--unified=0', '--no-color', '--no-ext-diff', '-M', `--format=${RS}%H`, tip]));
+    return parseMergeHistoryEvents(await textEventStream(root, tip, indexEventRequests(root, tip, order, reachable).merge, !transient, useCache));
+}
+async function buildDriftIndex(root, tip, transient, useCache = true, shared) {
+    if (isUnbornHistoryTip(tip))
+        return emptyDriftIndex();
+    const ord = new Map(), parents = new Map();
+    const fileEvents = new Map();
+    const lineageEvents = new Map();
+    const acks = new Map(), selfAcks = new Map(), specNodes = new Map();
+    const ackCandidates = new Map(), ackCheckpoints = new Map();
+    const idx = { tip, ord, parents, fileEvents, lineageEvents, lineageKeys: (path) => [path], resolutionEvents: new Map(), acks, selfAcks, specNodes, anc: new Map() };
+    let currentPaths;
+    let topology;
+    if (shared) {
+        currentPaths = shared.allPaths;
+        topology = shared.topology;
+    }
+    else {
+        const [tipPathsOut, topologyOut] = await Promise.all([
+            strictEventGit(['-C', root, 'ls-tree', '-r', '-z', '--name-only', tip]),
+            strictEventGit(['-C', root, 'rev-list', '--parents', tip]),
+        ]);
+        currentPaths = new Set(tipPathsOut.split('\0').filter(Boolean));
+        topology = topologyProjection(topologyOut);
+    }
+    const topologyOrder = topology.order;
+    const topologyParents = topology.parents;
+    const topologyReachable = topology.reachable;
+    for (const [hash, position] of topologyOrder) {
+        ord.set(hash, position);
+        parents.set(hash, topologyParents.get(hash) ?? []);
+    }
+    // Raw identity records path pairs and immutable object ids once; projection owns forks and reuse.
+    const records = shared?.identityRecords ?? await identityRawEventStream(root, tip, indexEventRequests(root, tip, topologyOrder, topologyReachable)['identity-raw'], !transient, useCache);
+    if (!records.length)
+        return idx;
+    const rawFileEvents = new Map();
+    const renamesByFrom = new Map();
+    for (const record of records) {
+        const { h: hash, a: ackStr, c: changes } = record;
+        const ackSet = new Set(ackStr.split(',').map((s) => s.trim()).filter(Boolean));
+        if (ackSet.size) {
+            ackCandidates.set(hash, ackSet);
+            ackCheckpoints.set(hash, changes.length === 0);
+        }
+        const merge = (parents.get(hash) ?? []).length > 1;
+        for (const [, from, to] of changes) {
+            if (!merge) {
+                const events = rawFileEvents.get(to) ?? [];
+                const event = {
+                    commit: hash,
+                    historicalPath: to,
+                    parents: (parents.get(hash) ?? []).slice(0, 1).map((commit) => ({ commit, historicalPath: from })),
+                };
+                events.push(event);
+                rawFileEvents.set(to, events);
+            }
+            if (from !== to) {
+                const renames = renamesByFrom.get(from) ?? [];
+                renames.push({ hash, to });
+                renamesByFrom.set(from, renames);
+            }
+        }
+    }
+    const mergeIndex = shared?.mergeIndex
+        ?? await mergeHistoryEvents(root, tip, transient, topologyOrder, topologyReachable, useCache);
+    for (const rename of mergeIndex.renames) {
+        const renames = renamesByFrom.get(rename.from) ?? [];
+        renames.push({ hash: rename.hash, to: rename.to });
+        renamesByFrom.set(rename.from, renames);
+    }
+    const canonical = canonicalPathProjector(renamesByFrom, topology);
+    idx.lineageKeys = canonical;
+    // One projection per event serves both the lineage index and the current-path index; asking the
+    // projector the same question twice per event only pays for it twice.
+    const addEvent = (keys, event, target) => {
+        for (const key of keys) {
+            const events = target.get(key) ?? [];
+            if (!events.some((existing) => existing.commit === event.commit && existing.historicalPath === event.historicalPath))
+                events.push(event);
+            target.set(key, events);
+        }
+    };
+    for (const [path, rawEvents] of rawFileEvents)
+        for (const event of rawEvents) {
+            const keys = canonical(path, event.commit);
+            addEvent(keys, event, lineageEvents);
+            for (const head of keys.filter((candidate) => currentPaths.has(candidate))) {
+                const events = fileEvents.get(head) ?? [];
+                if (!events.some((existing) => existing.commit === event.commit && existing.historicalPath === event.historicalPath))
+                    events.push(event);
+                fileEvents.set(head, events);
+                if (isSpecMd(head)) {
+                    const nodes = specNodes.get(event.commit) ?? new Set();
+                    nodes.add(nodeIdOf(head));
+                    specNodes.set(event.commit, nodes);
+                }
+            }
+        }
+    for (const [hash, nodes] of ackCandidates) {
+        const parentList = parents.get(hash) ?? [];
+        const firstParent = parentList[0];
+        // A non-merge commit with no raw identity entries has the same tree as its sole parent.
+        const checkpoint = parentList.length === 1 && !!firstParent && ackCheckpoints.get(hash) === true;
+        (checkpoint ? acks : selfAcks).set(hash, nodes);
+    }
+    for (const [path, mergeEvents] of mergeIndex.resolutions)
+        for (const mergeEvent of mergeEvents) {
+            const mergeParents = topologyParents.get(mergeEvent.hash) ?? [];
+            if (mergeParents.length !== mergeEvent.parentPaths.length)
+                throw new Error(`merge ${mergeEvent.hash} has ${mergeParents.length} topology parents but ${mergeEvent.parentPaths.length} combined parent paths`);
+            const event = {
+                commit: mergeEvent.hash,
+                historicalPath: path,
+                parents: mergeParents.map((commit, index) => ({ commit, historicalPath: mergeEvent.parentPaths[index] })),
+            };
+            const keys = canonical(path, mergeEvent.hash);
+            addEvent(keys, event, lineageEvents);
+            for (const head of keys.filter((candidate) => currentPaths.has(candidate))) {
+                const events = idx.resolutionEvents.get(head) ?? [];
+                if (!events.some((existing) => existing.commit === event.commit && existing.historicalPath === event.historicalPath))
+                    events.push(event);
+                idx.resolutionEvents.set(head, events);
+                if (isSpecMd(head)) {
+                    const nodes = specNodes.get(mergeEvent.hash) ?? new Set();
+                    nodes.add(nodeIdOf(head));
+                    specNodes.set(mergeEvent.hash, nodes);
+                }
+            }
+        }
+    return idx;
+}
+export function driftIndex(root, tip = 'HEAD') {
+    if (tip !== 'HEAD') {
+        const resolved = git(['-C', root, 'rev-parse', `${tip}^{commit}`]).trim();
+        if (pendingOnlyIssues(root, resolved)) {
+            const parent = pendingParent(root, resolved);
+            if (parent) {
+                const head = headOrEmpty(root);
+                if (head === parent)
+                    return driftIndex(root);
+                return buildDriftIndex(root, parent, true, true);
+            }
+        }
+        return buildDriftIndex(root, resolved, true, true);
+    }
+    const head = headOrEmpty(root); // filesystem HEAD, no subprocess — see historyIndex
+    if (!head)
+        return buildDriftIndex(root, 'HEAD', false, true);
+    const cacheKey = indexCacheKey(root, head);
+    touchRoot(driftRoots, driftIdxCache, root, cacheKey);
+    const hit = driftIdxCache.get(cacheKey);
+    if (hit)
+        return hit;
+    const p = buildDriftIndex(root, head, false, true);
+    p.catch(() => { dropFailed(driftIdxCache, cacheKey, p); });
+    driftIdxCache.set(cacheKey, p);
+    return p;
+}
+function topologyProjection(out) {
+    const order = new Map(), parents = new Map(), reachable = new Set();
+    let position = 0;
+    for (const line of out.trim().split('\n')) {
+        const [hash, ...parentList] = line.split(' ');
+        if (!hash)
+            continue;
+        order.set(hash, position++);
+        parents.set(hash, parentList);
+        reachable.add(hash);
+    }
+    return { order, parents, reachable };
+}
+function textStream(value, kind) {
+    if (typeof value !== 'string')
+        throw new Error(`history event stream '${kind}' did not render text`);
+    return value;
+}
+function identityRawStream(value, kind) {
+    if (!Array.isArray(value) || value.some((record) => !('a' in record)))
+        throw new Error(`history event stream '${kind}' did not render identity records`);
+    return value;
+}
+async function buildIndexPair(root, tip, transient, useCache = true) {
+    if (isUnbornHistoryTip(tip))
+        return [emptyHistoryIndex(), emptyDriftIndex()];
+    const [allPathsOut, topologyOut] = await Promise.all([
+        strictEventGit(['-C', root, '-c', 'core.quotePath=false', 'ls-tree', '-r', '-z', '--name-only', tip]),
+        strictEventGit(['-C', root, 'rev-list', '--parents', tip]),
+    ]);
+    const topology = topologyProjection(topologyOut);
+    const allPaths = new Set(allPathsOut.split('\0').filter(Boolean));
+    const specPaths = new Set([...allPaths].filter((path) => path.startsWith('.spec/')));
+    const requests = indexEventRequests(root, tip, topology.order, topology.reachable);
+    const streams = await deriveEventStreams(root, tip, EVENT_STREAM_KINDS.map((kind) => requests[kind]), !transient, useCache);
+    const shared = {
+        allPaths,
+        specPaths,
+        topology,
+        identityRecords: identityRawStream(streams.get('identity-raw'), 'identity-raw'),
+        mergeIndex: parseMergeHistoryEvents(textStream(streams.get('merge'), 'merge')),
+    };
+    streams.clear();
+    return Promise.all([
+        buildIndex(root, tip, transient, useCache, shared),
+        buildDriftIndex(root, tip, transient, useCache, shared),
+    ]);
+}
+// Standing correctness oracle: same projection, but every immutable stream comes from Git root history.
+export function sourceIndexesFull(root, tip = 'HEAD') {
+    const head = tip === 'HEAD' ? headOrEmpty(root) : '';
+    const resolved = tip === 'HEAD'
+        ? (head || 'HEAD')
+        : git(['-C', root, 'rev-parse', `${tip}^{commit}`]).trim();
+    return buildIndexPair(root, resolved, true, false);
+}
+// History and drift are one product projection. Building them together is what gives one lint one ledger
+// transaction; the public single-index functions remain for consumers that genuinely need only one side.
+export function sourceIndexes(root, tip = 'HEAD') {
+    if (tip !== 'HEAD') {
+        const resolved = git(['-C', root, 'rev-parse', `${tip}^{commit}`]).trim();
+        if (pendingOnlyIssues(root, resolved)) {
+            const parent = pendingParent(root, resolved);
+            if (parent)
+                return headOrEmpty(root) === parent
+                    ? sourceIndexes(root)
+                    : buildIndexPair(root, parent, true, true);
+        }
+        return buildIndexPair(root, resolved, true, true);
+    }
+    const head = headOrEmpty(root);
+    if (!head)
+        return buildIndexPair(root, 'HEAD', false, true);
+    const cacheKey = indexCacheKey(root, head);
+    touchRoot(indexRoots, indexCache, root, cacheKey);
+    touchRoot(driftRoots, driftIdxCache, root, cacheKey);
+    const historyHit = indexCache.get(cacheKey), driftHit = driftIdxCache.get(cacheKey);
+    if (historyHit && driftHit)
+        return Promise.all([historyHit, driftHit]);
+    const pair = buildIndexPair(root, head, false, true);
+    const historyPromise = pair.then(([history]) => history);
+    const driftPromise = pair.then(([, drift]) => drift);
+    historyPromise.catch(() => { dropFailed(indexCache, cacheKey, historyPromise); });
+    driftPromise.catch(() => { dropFailed(driftIdxCache, cacheKey, driftPromise); });
+    indexCache.set(cacheKey, historyPromise);
+    driftIdxCache.set(cacheKey, driftPromise);
+    return pair;
+}
+export function historyCacheStats() {
+    return { historyHeads: indexCache.size, driftHeads: driftIdxCache.size, historyRoots: indexRoots.size, driftRoots: driftRoots.size };
+}
+// Tests deliberately clear process-local promises and path identity to exercise both cold and read-back paths.
+// Production callers retain the bounded index caches; this is not a correctness escape hatch.
+export function resetHistoryCachesForTests() {
+    indexCache.clear();
+    driftIdxCache.clear();
+    indexRoots.clear();
+    driftRoots.clear();
+    eventPathMemo.clear();
+    gitObjectFormatMemo.clear();
+}
+export function historyEventCachePathForTests(root) { return eventCacheLocation(root).path; }
+// @@@ one ordinary ancestry memo, with a batch entrance - every closure below has exactly the same dense
+// bitset shape in idx.anc. A caller that already knows several bases can prime them in one child-to-parent
+// topology pass; the short-lived frontier is released before returning. Unknown or ad-hoc revisions retain
+// this direct parent DFS, so neither path introduces a second reachability representation or persistent fact.
+// undefined when `sha` is not reachable from HEAD (rebased away, an unmerged branch, or never on any
+// ref) — callers apply their own conservative rule to that "can't prove" case.
+export function ancestorsOf(idx, sha) {
+    const hit = idx.anc.get(sha);
+    if (hit)
+        return hit;
+    const start = idx.ord.get(sha);
+    if (start === undefined)
+        return undefined;
+    const bits = new Uint8Array((idx.ord.size + 7) >> 3);
+    bits[start >> 3] |= 1 << (start & 7);
+    const stack = [sha];
+    while (stack.length) {
+        for (const p of idx.parents.get(stack.pop()) ?? []) {
+            const o = idx.ord.get(p);
+            if (o === undefined)
+                continue; // shallow-clone boundary: an unwalked parent ends the chain
+            const m = 1 << (o & 7);
+            if (bits[o >> 3] & m)
+                continue;
+            bits[o >> 3] |= m;
+            stack.push(p);
+        }
+    }
+    idx.anc.set(sha, bits);
+    return bits;
+}
+// Fill the existing ancestry memo for a known roster in one child-before-parent topology pass. At each
+// commit the transient row names requested descendants; emitting those bits into the ordinary closures makes
+// the resulting bytes identical to calling ancestorsOf() independently for every requested SHA.
+export function primeAncestorClosures(idx, shas) {
+    const endpoints = [...new Set(shas)].filter((sha) => !idx.anc.has(sha) && idx.ord.has(sha));
+    if (!endpoints.length)
+        return;
+    const count = idx.ord.size;
+    const width = (endpoints.length + 7) >> 3;
+    const closureWidth = (count + 7) >> 3;
+    const endpointAt = new Map(endpoints.map((sha, position) => [sha, position]));
+    const hashAt = new Array(count);
+    for (const [hash, position] of idx.ord)
+        hashAt[position] = hash;
+    // Every row waits until all of its children have contributed. Parents outside the walked topology are
+    // deliberately absent: they are the same shallow boundary ancestorsOf() stops at.
+    const childrenLeft = new Int32Array(count);
+    for (const parents of idx.parents.values())
+        for (const parent of parents) {
+            const position = idx.ord.get(parent);
+            if (position !== undefined)
+                childrenLeft[position]++;
+        }
+    const ready = [];
+    for (let position = 0; position < count; position++)
+        if (childrenLeft[position] === 0)
+            ready.push(position);
+    const closures = endpoints.map(() => new Uint8Array(closureWidth));
+    const rows = new Map(), pool = [];
+    const rowFor = (position) => {
+        const existing = rows.get(position);
+        if (existing)
+            return existing;
+        const row = pool.pop() ?? new Uint8Array(width);
+        rows.set(position, row);
+        return row;
+    };
+    let visited = 0;
+    while (ready.length) {
+        const position = ready.pop();
+        visited++;
+        const row = rowFor(position);
+        rows.delete(position);
+        const endpoint = endpointAt.get(hashAt[position]);
+        if (endpoint !== undefined)
+            row[endpoint >> 3] |= 1 << (endpoint & 7);
+        for (let byte = 0; byte < width; byte++) {
+            let pending = row[byte];
+            while (pending) {
+                const bit = 31 - Math.clz32(pending & -pending);
+                closures[(byte << 3) + bit][position >> 3] |= 1 << (position & 7);
+                pending &= pending - 1;
+            }
+        }
+        for (const parent of idx.parents.get(hashAt[position]) ?? []) {
+            const parentPosition = idx.ord.get(parent);
+            if (parentPosition === undefined)
+                continue;
+            const target = rowFor(parentPosition);
+            for (let byte = 0; byte < width; byte++)
+                target[byte] |= row[byte];
+            if (--childrenLeft[parentPosition] === 0)
+                ready.push(parentPosition);
+        }
+        row.fill(0);
+        pool.push(row);
+    }
+    if (visited !== count)
+        throw new Error(`cannot prime ancestry closures: topology yielded ${visited} of ${count} reachable commits`);
+    for (let position = 0; position < endpoints.length; position++)
+        idx.anc.set(endpoints[position], closures[position]);
+}
+export function inAncestors(idx, bits, sha) {
+    const o = idx.ord.get(sha);
+    return o !== undefined && (bits[o >> 3] & (1 << (o & 7))) !== 0;
+}
+// @@@ one walk for a whole roster of revisions, HEAD-reachable or not - the index above projects HEAD's
+// history, so a revision HEAD cannot reach (an unmerged branch, a rebased-away measurement anchor) has NO
+// ancestry there and `ancestorsOf` correctly answers undefined. A caller that needs those revisions' own
+// past gets it from the SAME projection shape, built by one `rev-list --parents` walk over the union of the
+// roster's histories, with the roster on stdin so argv never grows with it. Deliberately a SEPARATE
+// structure, never a graft into the shared index: making off-history tips reachable there would silently
+// switch every ancestry-vs-content decision that keys on `undefined`.
+export async function unionTopology(root, revisions) {
+    const roster = [...new Set(revisions)].filter(Boolean);
+    const reach = { ord: new Map(), parents: new Map(), anc: new Map() };
+    if (!roster.length)
+        return reach;
+    const out = await gitRequiredA(['-C', root, 'rev-list', '--parents', '--stdin'], 'cannot walk revision topology', {
+        input: roster.map((revision) => `${revision}\n`).join(''),
+        // the roster is already exact object ids; do not reinterpret them if refs/replace moves mid-read.
+        extraEnv: { GIT_NO_REPLACE_OBJECTS: '1' },
+    });
+    const projection = topologyProjection(out);
+    return { ord: projection.order, parents: projection.parents, anc: new Map() };
+}
+// @@@ reachability is membership, not a closure - `ancestorsOf` returns undefined for EXACTLY the shas
+// absent from `idx.ord` (both writers of `idx.anc` gate on ord: the single-sha path after its ord lookup
+// succeeds, the batch after an explicit `ord.has` filter), so asking it here answered a hash-table
+// question by walking the whole parent DAG and allocating an ord.size-wide bitset per distinct sha —
+// per eval reading, on every board build.
+export function commitReachable(idx, sha) {
+    return idx.ord.has(sha);
+}
+// the valid Spec-OK coverage for a node's version commit: `sinceHash` is the node's OWN latest version,
+// so the node(s) it's a version of (specNodes[sinceHash]) name the node being measured; an ack counts
+// only if its `Spec-OK:` set names one of those — `Spec-OK: A` quiets A's drift, never B's. An ack that
+// is itself an ancestor of the version can't speak for it (a re-version invalidates older acks); a valid
+// ack quiets exactly the commits reachable from it. Shared by driftFor (the count) and the anchor
+// engine's windowCommits (the commit set) so both read ONE ack rule.
+function targetNodes(idx, sinceHash, nodeId) {
+    return nodeId ? new Set([nodeId]) : idx.specNodes.get(sinceHash);
+}
+export function ackCoverFor(idx, sinceHash, nodeId) {
+    const base = ancestorsOf(idx, sinceHash);
+    if (!base)
+        return [];
+    const targets = targetNodes(idx, sinceHash, nodeId);
+    const cover = [];
+    if (targets) {
+        for (const [h, ackSet] of idx.acks) {
+            if (inAncestors(idx, base, h))
+                continue;
+            if (![...targets].some((t) => ackSet.has(t)))
+                continue;
+            const a = ancestorsOf(idx, h);
+            if (a)
+                cover.push(a);
+        }
+    }
+    return cover;
+}
+export function selfAckCovers(idx, sinceHash, hash, nodeId) {
+    const targets = targetNodes(idx, sinceHash, nodeId);
+    const declared = idx.selfAcks?.get(hash);
+    return !!targets && !!declared && [...targets].some((node) => declared.has(node));
+}
+export function pathEvents(idx, path) {
+    return [...(idx.fileEvents.get(path) ?? []), ...(idx.resolutionEvents?.get(path) ?? [])];
+}
+// Exact base..tip window for consumers whose subject is not a spec version. The path is an identity at
+// `identityRevision`; projecting it and every immutable event to the same terminal lineage keys preserves
+// rename chains, parallel forks, path reuse, and lineages deleted before the tip.
+export function pathRangeEvents(idx, sinceHash, path, identityRevision = idx.tip ?? sinceHash) {
+    const base = ancestorsOf(idx, sinceHash);
+    if (!base)
+        return null;
+    const seen = new Set();
+    const events = idx.lineageKeys(path, identityRevision).flatMap((key) => idx.lineageEvents.get(key) ?? []);
+    return events.filter((event) => {
+        const key = `${event.commit}\0${event.historicalPath}\0${event.parents.map((parent) => `${parent.commit}:${parent.historicalPath}`).join('\x1e')}`;
+        if (seen.has(key) || inAncestors(idx, base, event.commit))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+// @@@ eventsSince - THE meaning of "this path changed since <sha>", in one place. A commit touching `path`
+// lies in `sha..HEAD` exactly when it is NOT an ancestor of `sha` — true DAG reachability, wherever a
+// date-ordered log happens to place it. `null` is the honest third answer: the anchor commit is not reachable
+// (folded, rebased, cherry-picked away), so ancestry cannot testify at all and the caller must decide what to
+// do about that — the spec layer reports no window, the eval layer falls back to comparing content.
+// Callers add their OWN layer's decoration on top (ack cover is spec-only; the content probe is eval-only);
+// what none of them may do is restate the reachability rule, which is how it came to exist four times.
+export function eventsSince(idx, sinceHash, path) {
+    const base = ancestorsOf(idx, sinceHash);
+    if (!base)
+        return null;
+    return pathEvents(idx, path).filter((event) => !inAncestors(idx, base, event.commit));
+}
+export function driftPathWindow(idx, sinceHash, path, nodeId) {
+    const events = eventsSince(idx, sinceHash, path);
+    if (!events)
+        return null;
+    const cover = ackCoverFor(idx, sinceHash, nodeId);
+    return events.filter((event) => !cover.some((a) => inAncestors(idx, a, event.commit))
+        && !selfAckCovers(idx, sinceHash, event.commit, nodeId));
+}
+// pure lookup, no git: a commit to `path` is drift iff it is NOT an ancestor of `sinceHash` — it lies
+// in `sinceHash..HEAD` by true DAG reachability, wherever a date-ordered log happens to place it.
+// An off-history `sinceHash` → 0: no basis on HEAD to measure from.
+export function driftFor(idx, sinceHash, path, nodeId) {
+    if (!sinceHash)
+        return 0;
+    return new Set(driftPathWindow(idx, sinceHash, path, nodeId)?.map((event) => event.commit) ?? []).size;
+}
+// the paths git is about to commit (index vs HEAD), scoping the pre-commit drift gate to this commit's files.
+export function stagedFiles(root) {
+    try {
+        return git(['-C', root, '-c', 'core.quotePath=false', 'diff', '--cached', '--name-only'])
+            .split('\n').map((s) => s.trim()).filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+// node id = the directory holding the spec.md (basename of its parent dir). git always emits
+// forward-slash paths, so split rather than node:path (which is backslash-y on Windows).
+const nodeIdOf = (p) => { const s = p.split('/'); return s[s.length - 2] ?? p; };
+const isSpecMd = (p) => p.endsWith('/spec.md');
+// `git ... --name-status -M` rows: `A\tpath`, `M\tpath`, `D\tpath`, `R100\told\tnew`. Recover the
+// status letter plus from/to (to === from for non-renames) so callers map letter -> op uniformly.
+function parseNameStatus(out) {
+    const rows = [];
+    for (const line of out.split('\n')) {
+        if (!line)
+            continue;
+        const parts = line.split('\t');
+        const code = parts[0][0];
+        if ((code === 'R' || code === 'C') && parts.length >= 3)
+            rows.push({ code, from: parts[1], to: parts[2] });
+        else
+            rows.push({ code, from: parts[1], to: parts[1] });
+    }
+    return rows;
+}
+const DIFF_STATUS = { A: 'added', M: 'modified', D: 'deleted', R: 'renamed', C: 'copied', T: 'type-changed' };
+function parseStatPath(token) {
+    const b = token.indexOf('{'), arrow = token.indexOf(' => ', b), close = token.indexOf('}', arrow);
+    if (b >= 0 && arrow > b && close > arrow) {
+        const pre = token.slice(0, b), post = token.slice(close + 1);
+        return { from: `${pre}${token.slice(b + 1, arrow)}${post}`.replace(/\/\//g, '/'), to: `${pre}${token.slice(arrow + 4, close)}${post}`.replace(/\/\//g, '/') };
+    }
+    const arrowAt = token.indexOf(' => ');
+    return arrowAt >= 0 ? { from: token.slice(0, arrowAt), to: token.slice(arrowAt + 4) } : { from: token, to: token };
+}
+export async function mergeBaseDiff(wtPath, mainRef = 'main', headRef = 'HEAD') {
+    const run = (args) => gitA(['-C', wtPath, '-c', 'core.quotePath=false', ...args]);
+    const base = (await run(['merge-base', mainRef, headRef])).trim();
+    if (!base)
+        return [];
+    const [numstatOut, statusOut] = await Promise.all([
+        run(['diff', '--numstat', '-M', `${base}..${headRef}`]),
+        run(['diff', '--name-status', '-M', `${base}..${headRef}`]),
+    ]);
+    const status = new Map();
+    for (const r of parseNameStatus(statusOut))
+        status.set(r.to, { status: DIFF_STATUS[r.code] ?? r.code, from: r.from });
+    const files = [];
+    for (const line of numstatOut.split('\n')) {
+        const m = line.match(/^(-|\d+)\t(-|\d+)\t(.+)$/);
+        if (!m)
+            continue;
+        const { from, to } = parseStatPath(m[3]);
+        const detail = status.get(to);
+        files.push({
+            path: to,
+            ...(from !== to ? { oldPath: detail?.from ?? from } : {}),
+            status: detail?.status ?? 'modified',
+            additions: m[1] === '-' ? 0 : +m[1],
+            deletions: m[2] === '-' ? 0 : +m[2],
+        });
+    }
+    return files;
+}
+export function mergeConflicts(wtPath, mainRef = 'main', headRef = 'HEAD') {
+    return new Promise((resolve) => {
+        const env = { ...process.env };
+        delete env.GIT_DIR;
+        delete env.GIT_WORK_TREE;
+        delete env.GIT_INDEX_FILE;
+        delete env.GIT_OBJECT_DIRECTORY;
+        execFile(gitBinary(env), ['-C', wtPath, 'merge-tree', '--write-tree', '--no-messages', mainRef, headRef], { encoding: 'utf8', env, maxBuffer: 1 << 24 }, 
+        // execFile sets err.code to the numeric EXIT code on a non-zero exit (1 = conflicts), or a string
+        // errno (e.g. 'ENOENT') if git can't be spawned — only the exit-1 case is a real conflict verdict.
+        (err) => resolve(!!err && err.code === 1));
+    });
+}
+// this worktree's spec ops vs main ([[worktree-linker]]): an op must BOTH differ from main's current tip
+// (the proposal — the vs-main working diff supplies the op set and each op's TYPE, so merge terms are
+// spoken: content equal to main is no op, an existing node reads `edited` never `added`) AND have been
+// touched by this branch since its fork point (attribution — main's own post-fork movement is not this
+// worktree's op). A `status --porcelain` pass adds untracked spec.md, a third diff vs HEAD marks committed.
+function projectWorktreeSpecDelta(mainOut, workOut, commOut, statusOut) {
+    const proposals = parseNameStatus(mainOut);
+    // the branch's own footprint since its fork point — both sides of every row, so a rename matches
+    // whichever side the vs-main diff names.
+    const touched = new Set();
+    for (const r of parseNameStatus(workOut)) {
+        touched.add(r.to);
+        if (r.from)
+            touched.add(r.from);
+    }
+    const committed = new Set(parseNameStatus(commOut).map((r) => r.to));
+    // --untracked-files=all: list every untracked spec.md individually (the default collapses a wholly
+    // new node's directory to `.spec/.../node/`, which we'd never recognise as a spec.md add).
+    const dirty = new Set(), untracked = [];
+    for (const line of statusOut.split('\n')) {
+        if (!line)
+            continue;
+        const xy = line.slice(0, 2);
+        let path = line.slice(3);
+        const arrow = path.indexOf(' -> ');
+        if (arrow >= 0)
+            path = path.slice(arrow + 4);
+        dirty.add(path);
+        if (xy === '??' && isSpecMd(path))
+            untracked.push(path);
+    }
+    const codeFor = { A: 'added', M: 'edited', D: 'deleted', R: 'moved', C: 'added', T: 'edited' };
+    const ops = [], seen = new Set();
+    for (const r of proposals) {
+        const path = r.code === 'D' ? r.from : r.to;
+        if (!isSpecMd(path))
+            continue;
+        if (!touched.has(r.to) && !touched.has(r.from))
+            continue;
+        seen.add(path);
+        const op = codeFor[r.code] ?? 'edited';
+        ops.push({
+            nodeId: nodeIdOf(path), op, path,
+            ...(op === 'moved' ? { fromPath: r.from, toPath: r.to } : {}),
+            committed: committed.has(r.to) || committed.has(r.from),
+            dirty: dirty.has(path) || dirty.has(r.from),
+        });
+    }
+    for (const path of untracked) {
+        if (seen.has(path))
+            continue;
+        ops.push({ nodeId: nodeIdOf(path), op: 'added', path, committed: false, dirty: true });
+    }
+    return ops;
+}
+async function boundedMap(values, concurrency, fn) {
+    const results = new Array(values.length);
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+        while (true) {
+            const index = next++;
+            if (index >= values.length)
+                return;
+            results[index] = await fn(values[index]);
+        }
+    }));
+    return results;
+}
+// One cold layout demand across many linked worktrees. Merge-base and working-status are path facts, so they
+// stay per worktree under a fixed concurrency. Clean rows then collapse to immutable main→HEAD and base→HEAD
+// pairs in one framed child; dirty rows retain the ordinary worktree-aware projection.
+export async function worktreeSpecDeltas(root, mainSha, demands, interpretation = gitInterpretationIdentity(root)) {
+    const results = new Map();
+    if (!demands.length)
+        return results;
+    if (gitInterpretationIdentity(root) !== interpretation) {
+        const error = new Error('Git interpretation changed before the worktree overlay batch');
+        for (const demand of demands)
+            results.set(demand.path, { error });
+        return results;
+    }
+    const prepared = await boundedMap(demands, 4, async (demand) => {
+        try {
+            const run = (args) => gitARequired(['-C', demand.path, '-c', 'core.quotePath=false', ...args]);
+            const [baseOut, statusOut] = await Promise.all([
+                run(['merge-base', mainSha, demand.head]),
+                run(['status', '--porcelain', '--untracked-files=all', '--', '.spec']),
+            ]);
+            const base = baseOut.trim();
+            if (!base)
+                throw new Error(`git merge-base returned no base for ${demand.path}`);
+            return { ...demand, base, statusOut };
+        }
+        catch (error) {
+            results.set(demand.path, { error });
+            return null;
+        }
+    });
+    const clean = prepared.filter((row) => !!row && row.statusOut.trim() === '');
+    const dirty = prepared.filter((row) => !!row && row.statusOut.trim() !== '');
+    const pairs = [];
+    const pairIndex = new Map();
+    const addPair = (from, to) => {
+        const key = `${from}\0${to}`;
+        const hit = pairIndex.get(key);
+        if (hit != null)
+            return hit;
+        const index = pairs.length;
+        pairIndex.set(key, index);
+        pairs.push({ from, to });
+        return index;
+    };
+    const cleanIndexes = clean.map((row) => ({
+        row,
+        main: addPair(mainSha, row.head),
+        branch: addPair(row.base, row.head),
+    }));
+    if (pairs.length) {
+        try {
+            // diff-tree's stdin pair syntax is `<new> <old>`; reverse each ordinary from→to pair deliberately.
+            // --always is load-bearing: it emits a frame for an empty pair, preserving positional ownership.
+            const input = pairs.map(({ from, to }) => `${to} ${from}`).join('\n') + '\n';
+            const out = await gitARequired([
+                '-C', root, '-c', 'core.quotePath=false', 'diff-tree', '--stdin', '--no-commit-id', '--always',
+                '-r', '--name-status', '-M', `--format=${RS}%H`, '--', '.spec',
+            ], input);
+            // For two-tree stdin rows, diff-tree writes that row's name-status payload BEFORE its --format marker.
+            // The first split segment is therefore pair 0; each later pair lives after the previous marker, while
+            // the final marker carries no following pair. Treating markers as openers shifts every non-empty result.
+            const records = out.split(RS);
+            if (records.length - 1 !== pairs.length)
+                throw new Error(`git diff-tree --stdin returned ${records.length - 1} frames for ${pairs.length} pairs`);
+            const frames = pairs.map((_, index) => {
+                if (index === 0)
+                    return records[0].split('\n').filter(Boolean).join('\n');
+                const lines = records[index].replace(/^\n/, '').split('\n');
+                lines.shift();
+                return lines.filter(Boolean).join('\n');
+            });
+            for (const { row, main, branch } of cleanIndexes) {
+                results.set(row.path, { base: row.base, ops: projectWorktreeSpecDelta(frames[main], frames[branch], frames[branch], '') });
+            }
+        }
+        catch (error) {
+            for (const { row } of cleanIndexes)
+                results.set(row.path, { error });
+        }
+    }
+    await Promise.all(dirty.map(async (row) => {
+        try {
+            const run = (args) => gitARequired(['-C', row.path, '-c', 'core.quotePath=false', ...args]);
+            const [mainOut, workOut, commOut] = await Promise.all([
+                run(['diff', '--name-status', '-M', mainSha, '--', '.spec']),
+                run(['diff', '--name-status', '-M', row.base, '--', '.spec']),
+                run(['diff', '--name-status', '-M', `${row.base}...${row.head}`, '--', '.spec']),
+            ]);
+            results.set(row.path, { base: row.base, ops: projectWorktreeSpecDelta(mainOut, workOut, commOut, row.statusOut) });
+        }
+        catch (error) {
+            results.set(row.path, { error });
+        }
+    }));
+    if (gitInterpretationIdentity(root) !== interpretation) {
+        const error = new Error('Git interpretation changed during the worktree overlay batch');
+        for (const demand of demands)
+            results.set(demand.path, { error });
+    }
+    return results;
+}
+export async function worktreeSpecDelta(wtPath, mainRef, baseHint) {
+    const run = (args) => gitA(['-C', wtPath, '-c', 'core.quotePath=false', ...args]);
+    // fork point = where this worktree branched from main; '' (no common ancestor / unreadable ref) falls
+    // back to mainRef so we still surface changes rather than going silent. The caller (cachedDelta) already
+    // computes this same merge-base to key its cache, so it passes it in to avoid a redundant subprocess.
+    const base = baseHint || (await run(['merge-base', mainRef, 'HEAD'])).trim() || mainRef;
+    // the four queries are independent — run them in parallel.
+    const [mainOut, workOut, commOut, statusOut] = await Promise.all([
+        run(['diff', '--name-status', '-M', mainRef, '--', '.spec']),
+        run(['diff', '--name-status', '-M', base, '--', '.spec']),
+        run(['diff', '--name-status', '-M', `${base}...HEAD`, '--', '.spec']),
+        run(['status', '--porcelain', '--untracked-files=all', '--', '.spec']),
+    ]);
+    return projectWorktreeSpecDelta(mainOut, workOut, commOut, statusOut);
+}