wingfoil 0.2.1 → 0.3.0

package/dist/storage/commit.js

@@ -1,12 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EMPTY_TREE_SHA = void 0;
+exports.EMPTY_TREE_SHA = exports.CommitFailure = void 0;
 exports.commitPaths = commitPaths;
+exports.stagedPaths = stagedPaths;
+exports.commitEmpty = commitEmpty;
+exports.writeAndCommit = writeAndCommit;
+exports.commitFailureSummary = commitFailureSummary;
 exports.readPathAtRev = readPathAtRev;
+exports.committedBlobMatches = committedBlobMatches;
+exports.storesAsBlob = storesAsBlob;
 exports.pathPorcelainStatus = pathPorcelainStatus;
 exports.commitParent = commitParent;
 exports.changedPathsBetween = changedPathsBetween;
 exports.listPathsAtRev = listPathsAtRev;
+exports.listBlobEntriesAtRev = listBlobEntriesAtRev;
+exports.resolveCommitAtRev = resolveCommitAtRev;
+exports.readPathsAtRev = readPathsAtRev;
+exports.readRevisionPaths = readRevisionPaths;
+exports.listPathsAtRevs = listPathsAtRevs;
+exports.listBlobsAtRevs = listBlobsAtRevs;
+exports.readBlobs = readBlobs;
+exports.mergeBasesWith = mergeBasesWith;
 /**
  * The reusable git-commit primitive (task-018-implement-git-backed-storage, P1.1, REQ-SYS-01).
  *
@@ -18,7 +32,7 @@ exports.listPathsAtRev = listPathsAtRev;
  * commit, returning its full sha. Every mutating Wave-3 task (task-019 versioning, task-020 memory
  * add, task-025 dna set, task-029 `wingfoil init`) turns its writes into a single attributable
  * commit through this one helper, so the "one operation = one scoped commit" convention
- * (CLAUDE.md §5.1) has a single implementation rather than being re-derived per task.
+ * (AGENTS.md §5.1) has a single implementation rather than being re-derived per task.
  *
  * Mirrors the git-primitive style in `src/memory/git-log.ts`: `execFileSync('git', …)` (never a
  * shell), `-C <root>` to target the repository, and `env: process.env` passed **explicitly** — the
@@ -26,11 +40,18 @@ exports.listPathsAtRev = listPathsAtRev;
  * env silently drops `GIT_*` overrides a test sets (the task-014 env-isolation gotcha).
  */
 const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const build_stamp_1 = require("./build-stamp");
+const dry_run_1 = require("./dry-run");
+const errors_1 = require("./errors");
+const git_read_1 = require("./git-read");
+/** The environment git runs with: `process.env`, with {@link CommitOptions.env} merged over it. */
+function gitEnv(options) {
+    return options.env ? { ...process.env, ...options.env } : process.env;
+}
 function runGit(root, args, options) {
-    return (0, child_process_1.execFileSync)('git', ['-C', root, ...args], {
-        encoding: 'utf-8',
-        env: options.env ? { ...process.env, ...options.env } : process.env,
-    });
+    return (0, child_process_1.execFileSync)('git', ['-C', root, ...args], { encoding: 'utf-8', env: gitEnv(options) });
 }
 /**
  * {@link runGit} for a **probe** — an invocation whose failure is an expected answer rather than an
@@ -45,11 +66,29 @@ function runGit(root, args, options) {
  * has not been created yet. A non-zero exit still raises through `execFileSync` exactly as before.
  */
 function probeGit(root, args, options) {
-    return (0, child_process_1.execFileSync)('git', ['-C', root, ...args], {
-        encoding: 'utf-8',
-        env: options.env ? { ...process.env, ...options.env } : process.env,
-        stdio: ['ignore', 'pipe', 'ignore'],
-    });
+    return (0, child_process_1.execFileSync)('git', ['-C', root, ...args], { encoding: 'utf-8', env: gitEnv(options), stdio: ['ignore', 'pipe', 'ignore'] });
+}
+/** git's exit status for `fatal:` — an absent path, an unresolvable revision, no repository. */
+const GIT_FATAL = 128;
+/** {@link CommitOptions} as the read helper takes them, with the exit statuses that are answers. */
+function gitReadOptions(options, accepted) {
+    return options.env ? { accepted, env: options.env } : { accepted };
+}
+/**
+ * `message` with the build signature appended as the final trailer paragraph (task-192, `dl-111`): a blank
+ * line, then `WingFoil-Version: <semver> (<sha>)` ({@link readBuildStamp}). The caller's
+ * {@link CommitOptions.trailers}, when given, open that paragraph, the signature staying its last line
+ * (task-226's phase record, task-227's step linkage).
+ *
+ * A final paragraph of trailers, never a line merged into the caller's body: git reads trailers from the
+ * message's final paragraph only, and so does `parseReasonBlock` (`src/memory/commit-message.ts`),
+ * whose `Reason:` block ends where that paragraph begins. Merged into an `Approver:`/`Reason:` body
+ * (what `git commit --trailer` would do, since that body is itself trailer-shaped), the signature would
+ * turn the whole body into the trailer block and cut a multi-line reason short. The caller's message
+ * is trimmed of trailing whitespace first, which `--cleanup=whitespace` would drop anyway.
+ */
+function stampedMessage(message, trailers = []) {
+    return `${message.replace(/\s+$/, '')}\n\n${[...trailers, (0, build_stamp_1.formatVersionTrailer)((0, build_stamp_1.readBuildStamp)())].join('\n')}`;
 }
 /**
  * Stage exactly `paths` (root-relative or absolute; each passed verbatim after `--` so a path that
@@ -58,23 +97,299 @@ function probeGit(root, args, options) {
  * neither committed nor unstaged (bug-027) — this also holds for the first commit of an empty
  * repository (`wingfoil init`).
  *
+ * **What the commit records is `message` plus the build signature** (task-192, `dl-111`): a final
+ * trailer paragraph `WingFoil-Version: <semver> (<sha>)` ({@link stampedMessage}), so every commit
+ * WingFoil writes says which build wrote it and a hand-written one carries no such line. The body is
+ * normalized by `--cleanup=whitespace`, pinned rather than inherited from `commit.cleanup`
+ * (`bug-051`). Callers keep returning their own `message` in `CoreResult.commit`; the signature is
+ * this primitive's, not the operation's.
+ *
  * Determinism note (REQ-SYS-07): a git commit's sha necessarily incorporates the author/commit
  * timestamp, so two runs produce different shas — that is inherent to *creating* history and is not
  * a context-building read path (the determinism rule targets read/derivation paths, e.g.
  * `computeStateSnapshot`), so it is correct and intended here.
  *
+ * A mutating operation commits through {@link writeAndCommit}, which writes, commits and undoes a
+ * refused commit in one place; during a dry run this function throws instead of committing (task-210).
+ *
  * @throws whatever `git` raises (via `execFileSync`) — e.g. nothing staged to commit, or `root` is
  *   not a git repository. Callers that must translate those into a `CoreResult` do so at their layer
  *   (see `src/core/init.ts`); this primitive stays a thin, throwing mechanism by design.
  */
 function commitPaths(root, paths, message, options = {}) {
-    runGit(root, ['add', '--', ...paths], options);
+    (0, dry_run_1.refuseDuringDryRun)('commitPaths');
+    return commitPathsNow(root, paths, message, options);
+}
+/**
+ * {@link commitPaths} without the dry-run guard — what {@link writeAndCommit} runs once it has decided
+ * this is a real run. git's stderr is captured rather than inherited (task-210, `bug-217`): a refusing
+ * hook's text reaches the caller inside the error, which {@link writeAndCommit} rewords, instead of
+ * being printed raw to the operator's terminal before WingFoil's own message.
+ */
+function commitPathsNow(root, paths, message, options) {
+    quietGit(root, ['add', '--', ...paths], options);
     // `--only -- <paths>` records exactly these paths, whatever else is staged: anything a caller or
     // another tool already staged stays staged and uncommitted (bug-027). A plain `git commit` would
     // commit the whole index under a subject that names only this operation.
-    runGit(root, ['commit', '--only', '--quiet', '-m', message, '--', ...paths], options);
+    const commitOptions = withAuthor(options);
+    // `--cleanup=whitespace` (bug-051): the body's normal form — trailing whitespace stripped, blank-line
+    // runs collapsed, a `#` line kept — is the tool's, whatever `commit.cleanup` the operator's or the
+    // repository's git config sets. Unpinned, `strip` deleted a reason line opening with `#` and
+    // `verbatim` kept what `dl-067` clause 3 declares removed.
+    quietGit(root, ['commit', '--only', '--quiet', '--cleanup=whitespace', '-m', stampedMessage(message, options.trailers), '--', ...paths], commitOptions);
+    return runGit(root, ['rev-parse', 'HEAD'], options).trim();
+}
+/** {@link CommitOptions} with the pinned author, when one is given, in git's environment (task-132). */
+function withAuthor(options) {
+    return options.author ? { ...options, env: { ...options.env, GIT_AUTHOR_NAME: options.author.name, GIT_AUTHOR_EMAIL: options.author.email } } : options;
+}
+/**
+ * The root-relative paths the index holds a change to, against `HEAD` (`git diff --cached --name-only`),
+ * in git's order — what a plain `git commit` would record. Empty when the index matches `HEAD`.
+ */
+function stagedPaths(root, options = {}) {
+    return runGit(root, ['-c', 'core.quotePath=false', 'diff', '--cached', '--name-only', '-z'], options)
+        .split('\0')
+        .filter((path) => path.length > 0);
+}
+/**
+ * Make one commit that changes **no file** — `workflow finalize`'s phase record (`spec-017` §7.9, task-226) —
+ * with `message`, {@link CommitOptions.trailers} and the build signature in its final paragraph, returning
+ * its sha. The commit primitive's third form, beside {@link writeAndCommit}:
+ *
+ * - **`git commit --only --allow-empty`, no pathspec** — git's documented form for an empty commit that
+ *   records nothing the index holds: a change the operator staged is neither committed nor unstaged
+ *   (`bug-027`, `dl-106`), even when a caller skipped the dirty-index guard (`requireCleanIndex`,
+ *   `src/core/write-guard.ts`) that refuses it first.
+ * - **`--cleanup=whitespace`** pinned over `commit.cleanup` (`bug-051`), as for every tool commit.
+ * - **Dry run** (`dl-106` W2): inside `captureDryRun` nothing is committed; the plan is the subject, the
+ *   full message, no paths and no diff.
+ *
+ * @throws {@link CommitFailure} (`E_COMMIT_FAILED`) when git does not make the commit (a refusing hook);
+ *   nothing was written, so there is nothing to put back.
+ */
+function commitEmpty(root, message, options = {}) {
+    const stamped = stampedMessage(message, options.trailers);
+    if ((0, dry_run_1.isDryRunActive)()) {
+        (0, dry_run_1.stopWithPlan)({ dryRun: true, subject: /^.*/.exec(message)[0], message: stamped, paths: [], diff: '' }, options.plannedWarnings ?? options.warnings);
+    }
+    try {
+        quietGit(root, ['commit', '--only', '--allow-empty', '--quiet', '--cleanup=whitespace', '-m', stamped], withAuthor(options));
+    }
+    catch (error) {
+        throw new CommitFailure(root, [], gitExplanation(error), undefined);
+    }
     return runGit(root, ['rev-parse', 'HEAD'], options).trim();
 }
+/** {@link runGit} with stderr captured into the thrown error instead of inherited by the terminal. */
+function quietGit(root, args, options) {
+    return (0, child_process_1.execFileSync)('git', ['-C', root, ...args], { encoding: 'utf-8', env: gitEnv(options), stdio: ['ignore', 'pipe', 'pipe'] });
+}
+/** `path` relative to `root`, with `/` separators — the spelling git and the plan use. */
+function repoRelative(root, path) {
+    return ((0, path_1.isAbsolute)(path) ? (0, path_1.relative)(root, path) : path).split(path_1.sep).join('/');
+}
+/**
+ * Write `changes` and commit exactly those paths as one commit with `message`, returning its sha — the
+ * single primitive every mutating operation writes through (task-210), so that two behaviours are
+ * implemented once for all of them:
+ *
+ * - **Dry run** (`dl-106` W2, `spec-008` §2 `--dry-run`). Inside `captureDryRun` (`./dry-run`), nothing
+ *   is written: the commit the call would make — subject, full message with the `WingFoil-Version:`
+ *   trailer, sorted root-relative paths, and the diff from `HEAD` to the blobs it would record
+ *   (`planDiff`) — is recorded with {@link CommitOptions.warnings}, and the operation stops here. Every
+ *   guard and refusal the operation runs before its write has already run, so a dry run of a refused
+ *   operation is refused the same way.
+ * - **A failed commit leaves nothing behind** (`bug-217`). When writing a file or git's `add`/`commit`
+ *   fails (a refusing hook, a full disk, an unparseable author date, a held `index.lock`), the working
+ *   tree is put back first — a created file is deleted, then every directory the write created, deepest
+ *   first across all paths; an overwritten or deleted file gets its bytes back — and then, when it
+ *   differs from what it was, the index entry of every path, whatever the operator had staged there. So
+ *   a retry of `memory add` gets the same id and nothing rides into the operator's next commit. A git
+ *   failure is then reported as {@link CommitFailure} (`E_COMMIT_FAILED`), naming the paths repository-
+ *   relative and quoting git's explanation with the project root removed — and, if the index could not
+ *   be put back, saying so. A filesystem failure is rethrown as it was raised (the index is untouched by
+ *   then).
+ *
+ * Callers run their confinement and dirty-target guards before calling: this primitive writes where it
+ * is told.
+ */
+function writeAndCommit(root, changes, message, options = {}) {
+    const planned = changes.map((change) => ({
+        absolute: (0, path_1.isAbsolute)(change.path) ? change.path : (0, path_1.join)(root, change.path),
+        relative: repoRelative(root, change.path),
+        content: change.content,
+    }));
+    if ((0, dry_run_1.isDryRunActive)()) {
+        const sorted = [...planned].sort((a, b) => Number(a.relative > b.relative) - Number(a.relative < b.relative));
+        (0, dry_run_1.stopWithPlan)({
+            dryRun: true,
+            subject: /^.*/.exec(message)[0],
+            message: stampedMessage(message, options.trailers),
+            paths: sorted.map((change) => change.relative),
+            diff: sorted.map((change) => (0, dry_run_1.planDiff)(root, change.relative, change.content, gitEnv(options))).join(''),
+        }, options.plannedWarnings ?? options.warnings);
+    }
+    const relativePaths = planned.map((change) => change.relative);
+    const indexBefore = indexEntries(root, relativePaths, options);
+    const bytesBefore = planned.map((change) => ((0, fs_1.existsSync)(change.absolute) ? (0, fs_1.readFileSync)(change.absolute) : null));
+    const createdDirectories = [];
+    const restoreWorkingTree = () => {
+        planned.forEach((change, index) => {
+            const bytes = bytesBefore[index] ?? null;
+            if (bytes !== null)
+                (0, fs_1.writeFileSync)(change.absolute, bytes);
+            else if ((0, fs_1.existsSync)(change.absolute))
+                (0, fs_1.unlinkSync)(change.absolute);
+        });
+        removeCreatedDirectories(createdDirectories);
+    };
+    try {
+        for (const change of planned) {
+            if (change.content === null) {
+                (0, fs_1.unlinkSync)(change.absolute);
+            }
+            else {
+                const created = (0, fs_1.mkdirSync)((0, path_1.dirname)(change.absolute), { recursive: true });
+                if (created !== undefined)
+                    createdDirectories.push({ file: change.absolute, created });
+                (0, fs_1.writeFileSync)(change.absolute, change.content, 'utf-8');
+            }
+        }
+    }
+    catch (error) {
+        restoreWorkingTree();
+        throw error;
+    }
+    try {
+        return commitPathsNow(root, changes.map((change) => change.path), message, options);
+    }
+    catch (error) {
+        restoreWorkingTree();
+        const indexProblem = restoreIndexIfChanged(root, relativePaths, indexBefore, options);
+        throw new CommitFailure(root, relativePaths, gitExplanation(error), indexProblem === undefined ? undefined : withoutRoot(root, indexProblem));
+    }
+}
+/**
+ * `E_COMMIT_FAILED` (task-210, `bug-217`): git did not make the commit of a write, and
+ * {@link writeAndCommit} has put the working tree back. Carries its parts so a caller that must word
+ * the failure differently (approve's supersede recovery) does not parse the message.
+ */
+class CommitFailure extends errors_1.StorageError {
+    /** The repository-relative paths the commit would have contained. */
+    paths;
+    /** git's explanation, on one line, with the project root removed. */
+    gitDetail;
+    /** Why the index entries could not be put back, when they could not; `undefined` when they were. */
+    indexProblem;
+    constructor(root, paths, raw, indexProblem) {
+        const gitDetail = withoutRoot(root, raw);
+        const outcome = indexProblem === undefined
+            ? 'nothing was committed, and the working tree and the index are as they were'
+            : `nothing was committed and the working tree is as it was, but the index entries of ${paths.join(', ')} could not be put back (${indexProblem}): check them with git status`;
+        super(errors_1.E_COMMIT_FAILED, `git did not commit ${committedWhat(paths)}: ${gitDetail} — ${outcome}`);
+        this.name = 'CommitFailure';
+        this.paths = paths;
+        this.gitDetail = gitDetail;
+        this.indexProblem = indexProblem;
+        Object.setPrototypeOf(this, CommitFailure.prototype);
+    }
+}
+exports.CommitFailure = CommitFailure;
+/**
+ * The reason a caller quotes for a failed write it reports in its own words (approve's supersede
+ * recovery, task-210 review F5): for a {@link CommitFailure}, `E_COMMIT_FAILED: git did not commit
+ * <paths>: <explanation>` — without the clause saying the working tree is as it was, which such a caller
+ * is about to make untrue — plus the index problem, if any; for anything else, `String(error)`.
+ */
+function commitFailureSummary(error) {
+    if (!(error instanceof CommitFailure))
+        return String(error);
+    const index = error.indexProblem === undefined ? '' : ` (the index entries could not be put back: ${error.indexProblem})`;
+    return `${errors_1.E_COMMIT_FAILED}: git did not commit ${committedWhat(error.paths)}: ${error.gitDetail}${index}`;
+}
+/** What a failed commit would have recorded: its paths, or `an empty commit` for {@link commitEmpty}'s. */
+function committedWhat(paths) {
+    return paths.length === 0 ? 'an empty commit' : paths.join(', ');
+}
+/** `git ls-files -s -z` of `paths`: the `mode oid stage\tpath` records the index holds for them. */
+function indexEntries(root, paths, options) {
+    return runGit(root, ['ls-files', '-s', '-z', '--', ...paths], options)
+        .split('\0')
+        .filter((record) => record.length > 0);
+}
+/**
+ * Put the index entries of `paths` back to `entries` when they differ from them now — drop what was not
+ * there, reinstate what was. Best effort: a failure (a held `index.lock`) is returned as git's
+ * explanation rather than thrown, so the caller still reports the commit failure in its own words.
+ */
+function restoreIndexIfChanged(root, paths, entries, options) {
+    try {
+        if (indexEntries(root, paths, options).join('\0') === entries.join('\0'))
+            return undefined;
+        quietGit(root, ['update-index', '--force-remove', '--', ...paths], options);
+        if (entries.length > 0) {
+            (0, child_process_1.execFileSync)('git', ['-C', root, 'update-index', '-z', '--index-info'], {
+                input: entries.map((entry) => `${entry}\0`).join(''),
+                env: gitEnv(options),
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        return undefined;
+    }
+    catch (error) {
+        return gitExplanation(error);
+    }
+}
+/**
+ * Remove every directory a write created — for each file, from its own directory up to and including the
+ * first directory `mkdirSync({recursive})` created for it — **deepest first across all files**, so a
+ * directory emptied by removing a deeper one is removed in turn. One that is not empty stays: something
+ * else now lives there, and it is not this write's to remove.
+ */
+function removeCreatedDirectories(created) {
+    const directories = new Set();
+    for (const entry of created) {
+        for (let directory = (0, path_1.dirname)(entry.file);; directory = (0, path_1.dirname)(directory)) {
+            directories.add(directory);
+            if (directory === entry.created || (0, path_1.dirname)(directory) === directory)
+                break;
+        }
+    }
+    const depth = (path) => path.split(path_1.sep).length;
+    for (const directory of [...directories].sort((a, b) => depth(b) - depth(a) || Number(a < b) - Number(a > b))) {
+        try {
+            (0, fs_1.rmdirSync)(directory);
+        }
+        catch {
+            // Not empty: it holds something this write did not create.
+        }
+    }
+}
+/** git's explanation of a failed run: its stderr when it wrote one, else the error's own message. */
+function gitExplanation(error) {
+    const captured = error.stderr;
+    // A commit with nothing to record explains itself on stdout only; the message (`Command failed: git
+    // -C <root> …`) is then what there is, and its root is removed by `withoutRoot`.
+    return typeof captured === 'string' && captured.trim().length > 0 ? captured : error.message;
+}
+/**
+ * `text` on one line, with every spelling of the project root removed — `<root>/x` becomes `x`, a bare
+ * `<root>` becomes `.` — so no absolute path reaches the operator (the `bug-251` class).
+ */
+function withoutRoot(root, text) {
+    // The longer spelling first, so that one spelling being a prefix of the other leaves no fragment.
+    const real = (0, fs_1.realpathSync)(root);
+    let detail = text;
+    for (const spelling of real.length >= root.length ? [real, root] : [root, real]) {
+        detail = detail.split(`${spelling}${path_1.sep}`).join('').split(spelling).join('.');
+    }
+    return detail
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .join('; ');
+}
 // --- Read primitives for asserting what a commit CONTAINS (task-088, bug-076) ------------------
 //
 // `commitPaths` above bounds a commit by *pathspec*; nothing bounded it by *content*, so a path that
@@ -88,21 +403,61 @@ function commitPaths(root, paths, message, options = {}) {
  */
 exports.EMPTY_TREE_SHA = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
 /**
- * The content of `path` at revision `rev`, or `null` when the path does not exist there (git exits
- * non-zero, which `execFileSync` raises).
+ * The content of `path` at revision `rev`, or `null` when git answers with its `fatal:` exit `128`:
+ * the path is absent there, or `rev` does not resolve (or `root` is no repository).
+ *
+ * Read through `runGitRead` (`./git-read`, task-142 review): stderr is captured, never inherited, and
+ * the buffer is `GIT_READ_MAX_BUFFER`. Before, a document past Node's 1 MiB default made
+ * `execFileSync` throw `ENOBUFS` and a blanket `catch` answered `null` — "absent" for a document that
+ * is there, which `memory amend`, the loaders and the write guard turned into a wrong refusal. A
+ * failure that is not git's answer — git that cannot be spawned, an answer past the buffer — now
+ * throws `StorageError` `E_GIT_READ_FAILED`. Exit `128` stays `null`: git gives it to an absent path
+ * and to an unreadable object alike, and this read does not tell them apart.
  *
  * `rev` is any revision git accepts before a `:` — a sha, `HEAD`, or the index stage `:0`, which is
  * how a caller reads what the user has **staged** as opposed to what is in the working tree. The two
  * can disagree, and the difference is load-bearing: `git add` would silently replace a staged version
  * with the working-tree one.
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when git cannot be spawned or its answer exceeds
+ *   the read buffer (task-142 review).
  */
 function readPathAtRev(root, rev, path, options = {}) {
-    try {
-        return probeGit(root, ['show', `${rev}:${path}`], options);
-    }
-    catch {
-        return null;
-    }
+    const run = (0, git_read_1.runGitRead)(root, ['show', `${rev}:${path}`], gitReadOptions(options, [0, GIT_FATAL]));
+    return run.status === GIT_FATAL ? null : run.stdout;
+}
+/**
+ * Whether `content`, put through the filters git applies when it stores `path` (`core.autocrlf`,
+ * `.gitattributes` `eol`/`text`/`filter`), is exactly the blob `rev` holds at `path` — git's own
+ * answer to "is this what was committed", rather than a byte comparison with `git show`, which on a
+ * machine that normalizes line endings sees an LF blob where the working tree holds CRLF (task-193
+ * review). Compares object ids: `git hash-object --path=<path> --stdin` of the bytes against
+ * `git rev-parse <rev>:<path>`. `false` when `rev` does not hold `path`.
+ *
+ * @param root - The repository.
+ * @param rev - The revision whose blob is compared (a commit sha).
+ * @param path - Root-relative path, which selects the filters as well as the blob.
+ * @param content - The text as it was written to the working tree.
+ * @param options - {@link CommitOptions} (the environment git runs with).
+ */
+function committedBlobMatches(root, rev, path, content, options = {}) {
+    const blob = (0, git_read_1.runGitRead)(root, ['rev-parse', '--verify', '--quiet', `${rev}:${path}`], gitReadOptions(options, [0, 1, GIT_FATAL]));
+    if (blob.status !== 0)
+        return false;
+    const hashed = (0, git_read_1.runGitRead)(root, ['hash-object', `--path=${path}`, '--stdin'], { ...gitReadOptions(options, [0]), input: content });
+    return hashed.stdout.trim() === blob.stdout.trim();
+}
+/**
+ * Whether git would store `content`, written to the working tree at `path`, as exactly the blob
+ * `blob` — `content` put through the filters git applies to `path` (`core.autocrlf`, `.gitattributes`),
+ * `blob` taken as-is. The counterpart of {@link committedBlobMatches} for a blob that exists only in
+ * memory (`memory submit`'s rendering of the committed document, task-209 review F1): it compares
+ * `git hash-object --path=<path> --stdin` with `git hash-object --no-filters --stdin`.
+ */
+function storesAsBlob(root, path, content, blob, options = {}) {
+    const filtered = (0, git_read_1.runGitRead)(root, ['hash-object', `--path=${path}`, '--stdin'], { ...gitReadOptions(options, [0]), input: content });
+    const raw = (0, git_read_1.runGitRead)(root, ['hash-object', '--no-filters', '--stdin'], { ...gitReadOptions(options, [0]), input: blob });
+    return filtered.stdout.trim() === raw.stdout.trim();
 }
 /**
  * The two-character `git status --porcelain` code for `path` (index status, then working-tree
@@ -179,23 +534,442 @@ const LS_TREE_BLOB_RECORD = /^\d+ blob [0-9a-f]+\t/;
  * @param prefix - Root-relative directory to limit the listing to; **omitted or empty lists the whole
  *   tree**, because `git ls-tree -- ''` is an error rather than a match-all. Passed verbatim after
  *   `--`, so a path that looks like a flag is never misread.
- * @returns The paths, or `null` when `rev` does not resolve.
+ * @returns The paths, or `null` when `rev` does not resolve (git's exit `128`).
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when git cannot be spawned or its answer exceeds
+ *   the read buffer (task-142 review).
  */
 function listPathsAtRev(root, rev, prefix = '', options = {}) {
+    return listBlobEntriesAtRev(root, rev, prefix, options)?.map((entry) => entry.path) ?? null;
+}
+/** The mode git records for a symbolic link. */
+const LS_TREE_SYMLINK_MODE = '120000';
+/**
+ * {@link listPathsAtRev} with each blob's kind: the same paths, in the same order, each marked when git
+ * records it as a **symbolic link** (mode `120000`). A link is a blob, so `listPathsAtRev` lists it and
+ * `readPathAtRev` reads back its target text; a reader that must not take that text for a document
+ * (the Memory scan, task-171, `bug-189`) asks here instead. Same `null` and same errors as
+ * {@link listPathsAtRev}.
+ */
+function listBlobEntriesAtRev(root, rev, prefix, options = {}) {
     const pathspec = prefix.length === 0 ? [] : ['--', prefix];
-    let records;
-    try {
-        // `probeGit`: an unresolvable revision is an expected answer here, and git's `fatal: Not a valid
-        // object name` must not reach the user's terminal beside the CLI's own message.
-        records = probeGit(root, ['ls-tree', '-r', '-z', '--full-tree', rev, ...pathspec], options);
-    }
-    catch {
+    // `runGitRead` (task-142 review): an unresolvable revision is git's exit `128`, an expected answer
+    // here, and its `fatal: Not a valid object name` stays in a captured pipe. A listing past Node's
+    // 1 MiB default no longer reads as "this revision does not resolve".
+    const run = (0, git_read_1.runGitRead)(root, ['ls-tree', '-r', '-z', '--full-tree', rev, ...pathspec], gitReadOptions(options, [0, GIT_FATAL]));
+    if (run.status === GIT_FATAL)
         return null;
-    }
-    return records
+    return run.stdout
         .split('\0')
         .filter((record) => LS_TREE_BLOB_RECORD.test(record))
-        .map((record) => record.slice(record.indexOf('\t') + 1))
-        .sort();
+        .map((record) => ({ path: record.slice(record.indexOf('\t') + 1), symlink: record.startsWith(`${LS_TREE_SYMLINK_MODE} `) }))
+        // Code-unit order, as `listPathsAtRev`'s plain `.sort()` always gave, without a branch.
+        .sort((a, b) => Number(a.path > b.path) - Number(a.path < b.path));
+}
+// --- Resolving a revision, and reading MANY paths at it (task-137) -----------------------------
+/**
+ * The full 40-hex sha of the **commit** `rev` names, or `null` when it names none: an unknown name, an
+ * unborn `HEAD` in a repository with no commits, a tree or a blob (`git rev-parse --verify --quiet`
+ * exits `1` for all of them).
+ *
+ * The `…AtRev` readers (`src/core/loaders.ts`, `src/memory/query.ts`) resolve their revision through
+ * this **once**, then read every byte at the sha, so one read cannot mix two commits when a ref moves
+ * while it runs. `^{commit}` peels a tag to its commit and refuses anything that is not one.
+ *
+ * **A failure is not "no such commit"** (task-137 review): a `root` git cannot read as a repository
+ * (exit `128`) or a `git` that cannot be spawned throws {@link StorageError} `E_GIT_READ_FAILED`, so a
+ * caller never reports a broken environment as a missing revision.
+ *
+ * The syntax of `rev` is the caller's to check — the core resolver (`resolveRevision`,
+ * `src/core/revision.ts`) refuses a malformed one before it gets here, so that nothing shaped like a
+ * flag ever reaches git's argument list.
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when git cannot answer at all.
+ */
+function resolveCommitAtRev(root, rev, options = {}) {
+    const run = (0, child_process_1.spawnSync)('git', ['-C', root, 'rev-parse', '--verify', '--quiet', `${rev}^{commit}`], {
+        encoding: 'utf-8',
+        env: options.env ? { ...process.env, ...options.env } : process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    // `--verify --quiet` exits 1, printing nothing on stdout, for a name that resolves to no commit.
+    if (run.status === 1)
+        return null;
+    if (run.error !== undefined || run.status !== 0) {
+        const detail = run.error !== undefined ? run.error.message : run.stderr.trim();
+        throw new errors_1.StorageError(errors_1.E_GIT_READ_FAILED, `git rev-parse ${rev} failed in ${root}: ${detail}`);
+    }
+    // `--verify` prints exactly one object name on success: the sha.
+    return run.stdout.trim();
+}
+/** Large enough for every Memory document of a repository; a larger answer fails loudly, never truncates. */
+const BATCH_READ_MAX_BUFFER = 256 * 1024 * 1024;
+/** One `git cat-file --batch` header for an object it found: `<oid> SP <type> SP <size>`. */
+const CAT_FILE_HEADER = /^[0-9a-f]+ ([a-z]+) (\d+)$/;
+/**
+ * The content of each of `paths` at revision `rev`, in input order — the bytes as UTF-8, or `null` when
+ * the revision does not hold that path as a **file** — read through **one** `git cat-file --batch`
+ * process instead of one `git show` per path. For a file or an absent path that is what
+ * {@link readPathAtRev} answers; for a directory it is `null`, where `git show` would print the tree's
+ * listing, which is no file's content.
+ *
+ * Why it exists (task-137): `spec-017` §1.1 reads every Memory document at `HEAD` on every workflow
+ * read, and `spec-012` builds an agent context from a commit. On this repository's 664 Memory and plan
+ * documents one `git show` per file took 5.49 s, the batch 0.39 s (task-137 design notes).
+ *
+ * **Fails closed.** A batch that cannot run, exits non-zero or answers past
+ * {@link BATCH_READ_MAX_BUFFER} throws {@link StorageError} `E_GIT_READ_FAILED`: a failed read must not
+ * pass for "every path is absent". `null` is reserved for a path the revision really does not hold.
+ *
+ * A path holding a newline or a carriage return cannot travel on the line-based batch protocol (git
+ * ends the request at the newline and strips a trailing CR); it is read on its own with
+ * {@link readPathAtRev}, which gives the same answer. Pass a resolved sha as `rev` when several calls
+ * must see one commit.
+ *
+ * @param root - Project root (the git repository).
+ * @param rev - A revision naming one commit — best a sha already resolved (`resolveCommitAtRev`). It
+ *   travels inside each request line, so a rev holding a newline, a carriage return, a `:` or a NUL is
+ *   refused with {@link StorageError} `E_INVALID_REVISION`: a newline would shift every answer onto
+ *   the wrong path, and a `:` would change which path is read.
+ * @param paths - Root-relative POSIX paths.
+ * @returns One entry per path, in the same order.
+ * @throws {@link StorageError} `E_INVALID_REVISION` for such a rev; `E_GIT_READ_FAILED` when the
+ *   batch read fails.
+ */
+function readPathsAtRev(root, rev, paths, options = {}) {
+    if (/[\n\r:\0]/.test(rev)) {
+        throw new errors_1.StorageError(errors_1.E_INVALID_REVISION, `revision ${JSON.stringify(rev)} cannot be read in a batch: it holds a newline, a carriage return, a ':' or a NUL`);
+    }
+    const batched = paths.filter((path) => !/[\n\r]/.test(path));
+    const answers = new Map();
+    if (batched.length > 0) {
+        const run = (0, child_process_1.spawnSync)('git', ['-C', root, 'cat-file', '--batch'], {
+            input: batched.map((path) => `${rev}:${path}\n`).join(''),
+            env: options.env ? { ...process.env, ...options.env } : process.env,
+            maxBuffer: BATCH_READ_MAX_BUFFER,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        if (run.error !== undefined || run.status !== 0) {
+            const detail = run.error !== undefined ? run.error.message : run.stderr.toString('utf-8').trim();
+            throw new errors_1.StorageError(errors_1.E_GIT_READ_FAILED, `git cat-file --batch at ${rev} failed in ${root}: ${detail}`);
+        }
+        const out = run.stdout;
+        let offset = 0;
+        for (const path of batched) {
+            const newline = out.indexOf(0x0a, offset);
+            if (newline === -1)
+                throw new errors_1.StorageError(errors_1.E_GIT_READ_FAILED, `git cat-file --batch at ${rev} in ${root}: truncated answer`);
+            const header = CAT_FILE_HEADER.exec(out.subarray(offset, newline).toString('utf-8'));
+            offset = newline + 1;
+            if (header === null) {
+                // `<object> missing` (or `ambiguous`): the revision does not hold this path.
+                answers.set(path, null);
+                continue;
+            }
+            const size = Number(header[2]);
+            // Every found object is followed by its bytes and one LF — a tree included, which is skipped.
+            answers.set(path, header[1] === 'blob' ? out.subarray(offset, offset + size).toString('utf-8') : null);
+            offset += size + 1;
+        }
+    }
+    return paths.map((path) => (answers.has(path) ? answers.get(path) : readPathAtRev(root, rev, path, options)));
+}
+/**
+ * The content of each `<rev>:<path>` request — each at its OWN revision — in input order: the bytes as
+ * UTF-8, or `null` when that revision does not hold that path as a file, a revision that names no
+ * commit included (the first parent of a root commit, `<sha>^1`). The many-revision counterpart of
+ * {@link readPathsAtRev}, with its answers and its refusals, in **one** `git cat-file --batch`.
+ *
+ * Why it exists (`task-278`, `bug-308`): `reconstructMemoryTransitions` (`src/memory/audit.ts`) reads
+ * a document at every commit of its history AND at each commit's first parent; one `git show` per
+ * read would double the spawns of the governance check's slowest path, a batch replaces them all.
+ *
+ * @param root - Project root (the git repository).
+ * @param requests - The revisions and paths to read.
+ * @param options - {@link CommitOptions} (the environment git runs with).
+ * @returns One entry per request, in the same order.
+ * @throws {@link StorageError} `E_INVALID_REVISION` for a rev holding a newline, a carriage return, a
+ *   `:` or a NUL; `E_GIT_READ_FAILED` when the batch read fails.
+ */
+function readRevisionPaths(root, requests, options = {}) {
+    for (const { rev } of requests) {
+        if (/[\n\r:\0]/.test(rev)) {
+            throw new errors_1.StorageError(errors_1.E_INVALID_REVISION, `revision ${JSON.stringify(rev)} cannot be read in a batch: it holds a newline, a carriage return, a ':' or a NUL`);
+        }
+    }
+    // A path holding a newline or a carriage return cannot travel on the line-based protocol: read alone.
+    const batched = requests.filter(({ path }) => !/[\n\r]/.test(path));
+    const objects = catFileBatch(root, batched.map(({ rev, path }) => `${rev}:${path}`), options);
+    const answers = new Map();
+    batched.forEach((request, index) => {
+        const object = objects[index] ?? null;
+        answers.set(request, object !== null && object.type === 'blob' ? object.content.toString('utf-8') : null);
+    });
+    return requests.map((request) => (answers.has(request) ? answers.get(request) : readPathAtRev(root, request.rev, request.path, options)));
+}
+// --- Listing a directory at MANY revisions in a constant number of processes (task-142) -------
+/** The object-type bits of a tree entry's mode (`S_IFMT`). */
+const MODE_TYPE_MASK = 0o170000;
+/** Type bits of a subtree. Compared as bits, not as text: a legacy writer's zero-padded `040000` is a directory too (task-142 review). */
+const MODE_TREE = 0o040000;
+/** Type bits of a gitlink (submodule): an entry of the tree, but not a file anyone can read back. */
+const MODE_GITLINK = 0o160000;
+/** Ask one `git cat-file --batch` for every request, answering in request order. */
+function catFileBatch(root, requests, options) {
+    if (requests.length === 0)
+        return [];
+    const out = (0, git_read_1.runGitReadBytes)(root, ['cat-file', '--batch'], {
+        input: requests.map((request) => `${request}\n`).join(''),
+        ...(options.env ? { env: options.env } : {}),
+    }).stdout;
+    const answers = [];
+    let offset = 0;
+    for (const request of requests) {
+        const newline = out.indexOf(0x0a, offset);
+        if (newline === -1)
+            throw new errors_1.StorageError(errors_1.E_GIT_READ_FAILED, `git cat-file --batch in ${root}: truncated answer for ${request}`);
+        const header = /^([0-9a-f]+) ([a-z]+) (\d+)$/.exec(out.subarray(offset, newline).toString('utf-8'));
+        offset = newline + 1;
+        if (header === null) {
+            // `<request> missing` (or `ambiguous`): no object answers that name.
+            answers.push(null);
+            continue;
+        }
+        const size = Number(header[3]);
+        answers.push({ oid: header[1], type: header[2], content: out.subarray(offset, offset + size) });
+        offset += size + 1;
+    }
+    return answers;
+}
+/** The entries of a raw tree object: `<mode> SP <name> NUL <binary oid>`, repeated. */
+function treeEntries(tree, oidBytes) {
+    const entries = [];
+    let offset = 0;
+    while (offset < tree.length) {
+        const space = tree.indexOf(0x20, offset);
+        const nul = tree.indexOf(0x00, space);
+        entries.push({
+            mode: tree.subarray(offset, space).toString('utf-8'),
+            name: tree.subarray(space + 1, nul).toString('utf-8'),
+            oid: tree.subarray(nul + 1, nul + 1 + oidBytes).toString('hex'),
+        });
+        offset = nul + 1 + oidBytes;
+    }
+    return entries;
+}
+/**
+ * Every **file** any of `revs` holds under `prefix`, as one sorted, de-duplicated list of
+ * root-relative POSIX paths — the union of {@link listPathsAtRev} over `revs`, read in a number of git
+ * processes that does not depend on how many revisions there are (`bug-178`, absorbed by `task-142`).
+ *
+ * `memory add`'s id counter reads every local branch and remote-tracking ref (`dl-101` §2 (a)); one
+ * `git ls-tree` per ref made its cost grow with the clone's branch count. Here one
+ * `git cat-file --batch` resolves every revision's tree at `prefix`, and each further level of the
+ * directory costs one more batch, asking only for the subtrees no earlier answer already held — so the
+ * process count is the depth of the directory under `prefix` plus one, and branches that share a
+ * subtree (most of them, most of the time) read it once.
+ *
+ * It answers what {@link listPathsAtRev} answers, unioned — compared case by case in
+ * `test/storage/list-paths-at-revs.test.ts` rather than claimed by construction: blobs only (a symbolic
+ * link is a blob, a gitlink is not a file), a subtree recognised by its mode's **type bits** so a
+ * legacy zero-padded `040000` is still a directory, the path bytes as UTF-8, sorted (REQ-SYS-07). The
+ * prefix is taken in canonical spelling — leading `./` segments and trailing `/` are dropped — and a
+ * prefix naming a file lists that file unless it ends in `/`. Other non-canonical spellings (`..`,
+ * `//` inside) are not normalised, and `ls-tree`'s pathspec matching may answer them differently.
+ *
+ * @param root - Project root (the git repository).
+ * @param revs - Revisions naming commits — best full shas. One that names no commit fails the read.
+ * @param prefix - Root-relative directory or file, canonical spelling (see above); empty lists whole trees.
+ * @returns The union of the paths, sorted.
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when a revision names no commit or tree, or the
+ *   batch read fails; `E_INVALID_REVISION` for a revision that cannot travel on the batch protocol.
+ */
+function listPathsAtRevs(root, revs, prefix = '', options = {}) {
+    for (const rev of revs) {
+        if (/[\n\r:\0]/.test(rev)) {
+            throw new errors_1.StorageError(errors_1.E_INVALID_REVISION, `revision ${JSON.stringify(rev)} cannot be read in a batch: it holds a newline, a carriage return, a ':' or a NUL`);
+        }
+    }
+    // Canonical spelling: `git ls-tree --full-tree -- ./docs/` reads `docs/`, and so must the batch.
+    const directory = prefix.replace(/^(?:\.\/+)+/, '').replace(/\/+$/, '');
+    if (/[\n\r]/.test(directory)) {
+        // Not expressible on the line-based batch protocol: read revision by revision instead.
+        const paths = new Set();
+        for (const rev of revs) {
+            const listed = listPathsAtRev(root, rev, prefix, options);
+            if (listed === null)
+                throw new errors_1.StorageError(errors_1.E_GIT_READ_FAILED, `git ls-tree ${rev} failed in ${root}: the tree could not be listed`);
+            for (const path of listed)
+                paths.add(path);
+        }
+        return [...paths].sort();
+    }
+    // Round one: each revision's root tree (which proves it names a commit or a tree) and, under a
+    // prefix, its tree at that prefix — absent when the revision has no such directory.
+    const requests = revs.flatMap((rev) => (directory.length === 0 ? [`${rev}^{tree}`] : [`${rev}^{tree}`, `${rev}:${directory}`]));
+    const answers = catFileBatch(root, requests, options);
+    const paths = new Set();
+    const cache = new Map();
+    let frontier = [];
+    let oidBytes = 20;
+    for (let index = 0; index < requests.length; index += 1) {
+        const answer = answers[index] ?? null;
+        const request = requests[index];
+        if (request.endsWith('^{tree}')) {
+            if (answer === null || answer.type !== 'tree') {
+                throw new errors_1.StorageError(errors_1.E_GIT_READ_FAILED, `git cat-file --batch in ${root}: ${request.slice(0, -'^{tree}'.length)} names no commit whose tree can be listed`);
+            }
+            oidBytes = answer.oid.length / 2;
+            if (directory.length > 0)
+                continue;
+        }
+        else if (answer !== null && answer.type === 'blob' && !prefix.endsWith('/')) {
+            // A prefix naming a file lists that file, as `ls-tree -- <file>` does; with a trailing `/` it
+            // names a directory, and a file there lists nothing.
+            paths.add(directory);
+            continue;
+        }
+        else if (answer === null || answer.type !== 'tree') {
+            continue;
+        }
+        const tree = answer;
+        cache.set(tree.oid, tree.content);
+        frontier.push({ oid: tree.oid, dir: directory });
+    }
+    // Each later round reads one level deeper, fetching only the subtrees not already read.
+    const seen = new Set();
+    while (frontier.length > 0) {
+        const unread = [...new Set(frontier.map((node) => node.oid).filter((oid) => !cache.has(oid)))].sort();
+        catFileBatch(root, unread, options).forEach((answer, index) => {
+            if (answer === null)
+                throw new errors_1.StorageError(errors_1.E_GIT_READ_FAILED, `git cat-file --batch in ${root}: tree ${unread[index]} is missing`);
+            cache.set(answer.oid, answer.content);
+        });
+        const next = [];
+        for (const node of frontier) {
+            const key = `${node.oid}\0${node.dir}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            for (const entry of treeEntries(cache.get(node.oid), oidBytes)) {
+                const path = node.dir.length === 0 ? entry.name : `${node.dir}/${entry.name}`;
+                const type = Number.parseInt(entry.mode, 8) & MODE_TYPE_MASK;
+                if (type === MODE_TREE)
+                    next.push({ oid: entry.oid, dir: path });
+                else if (type !== MODE_GITLINK)
+                    paths.add(path);
+            }
+        }
+        frontier = next;
+    }
+    return [...paths].sort();
+}
+/**
+ * The blobs each of `revs` holds under `directory`, one sorted list per revision, in input order —
+ * {@link listPathsAtRevs}' batched walk (task-142, `bug-178`), keeping per revision what it holds and
+ * each blob's oid. The walk asks one `git cat-file --batch` per directory level for the trees no earlier
+ * answer held, so revisions that share a subtree read it once, and the process count is the directory's
+ * depth plus one whatever the number of revisions (task-274, the WIP-limit count across refs).
+ *
+ * A revision without `directory` holds nothing there. Gitlinks are skipped; a symbolic link is listed,
+ * marked. `directory` is root-relative, without a trailing `/`; empty means the whole tree.
+ *
+ * @throws {@link StorageError} `E_INVALID_REVISION` for a revision that cannot travel on the batch
+ *   protocol; `E_GIT_READ_FAILED` when a revision names no commit or tree, or the batch read fails.
+ */
+function listBlobsAtRevs(root, revs, directory, options = {}) {
+    for (const rev of revs) {
+        if (/[\n\r:\0]/.test(rev)) {
+            throw new errors_1.StorageError(errors_1.E_INVALID_REVISION, `revision ${JSON.stringify(rev)} cannot be read in a batch: it holds a newline, a carriage return, a ':' or a NUL`);
+        }
+    }
+    if (/[\n\r]/.test(directory)) {
+        throw new errors_1.StorageError(errors_1.E_INVALID_REVISION, `directory ${JSON.stringify(directory)} cannot be read in a batch: it holds a newline or a carriage return`);
+    }
+    const answers = catFileBatch(root, revs.flatMap((rev) => [`${rev}^{tree}`, directory.length === 0 ? `${rev}^{tree}` : `${rev}:${directory}`]), options);
+    const trees = new Map();
+    const roots = revs.map((rev, index) => {
+        const commit = answers[2 * index] ?? null;
+        if (commit === null || commit.type !== 'tree') {
+            throw new errors_1.StorageError(errors_1.E_GIT_READ_FAILED, `git cat-file --batch in ${root}: ${rev} names no commit whose tree can be listed`);
+        }
+        const at = answers[2 * index + 1] ?? null;
+        if (at === null || at.type !== 'tree')
+            return null;
+        trees.set(at.oid, at.content);
+        return at.oid;
+    });
+    const oidBytes = (roots.find((oid) => oid !== null) ?? '0'.repeat(40)).length / 2;
+    // Read every subtree, one batch per level, each tree once.
+    let frontier = [...new Set(roots.filter((oid) => oid !== null))];
+    while (frontier.length > 0) {
+        const next = new Set();
+        for (const oid of frontier) {
+            for (const entry of treeEntries(trees.get(oid), oidBytes)) {
+                if ((Number.parseInt(entry.mode, 8) & MODE_TYPE_MASK) === MODE_TREE && !trees.has(entry.oid))
+                    next.add(entry.oid);
+            }
+        }
+        const unread = [...next].sort();
+        catFileBatch(root, unread, options).forEach((answer, index) => {
+            if (answer === null)
+                throw new errors_1.StorageError(errors_1.E_GIT_READ_FAILED, `git cat-file --batch in ${root}: tree ${unread[index]} is missing`);
+            trees.set(answer.oid, answer.content);
+        });
+        frontier = unread;
+    }
+    // Flatten each tree once, relative to itself; a revision's listing is its root tree's, prefixed.
+    const flat = new Map();
+    const flatten = (oid) => {
+        const known = flat.get(oid);
+        if (known !== undefined)
+            return known;
+        const out = [];
+        for (const entry of treeEntries(trees.get(oid), oidBytes)) {
+            const type = Number.parseInt(entry.mode, 8) & MODE_TYPE_MASK;
+            if (type === MODE_TREE) {
+                for (const inner of flatten(entry.oid))
+                    out.push({ ...inner, path: `${entry.name}/${inner.path}` });
+            }
+            else if (type !== MODE_GITLINK) {
+                out.push({ path: entry.name, oid: entry.oid, symlink: entry.mode === LS_TREE_SYMLINK_MODE });
+            }
+        }
+        flat.set(oid, out);
+        return out;
+    };
+    return roots.map((oid) => oid === null
+        ? []
+        : flatten(oid)
+            .map((blob) => ({ ...blob, path: directory.length === 0 ? blob.path : `${directory}/${blob.path}` }))
+            .sort((a, b) => Number(a.path > b.path) - Number(a.path < b.path)));
+}
+/**
+ * The content of each blob `oids` names, as UTF-8, read through one `git cat-file --batch` (task-274).
+ * Duplicates are read once.
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when an oid names no blob or the batch read fails.
+ */
+function readBlobs(root, oids, options = {}) {
+    const unique = [...new Set(oids)].sort();
+    const contents = new Map();
+    catFileBatch(root, unique, options).forEach((answer, index) => {
+        if (answer === null || answer.type !== 'blob')
+            throw new errors_1.StorageError(errors_1.E_GIT_READ_FAILED, `git cat-file --batch in ${root}: blob ${unique[index]} is missing`);
+        contents.set(unique[index], answer.content.toString('utf-8'));
+    });
+    return contents;
+}
+/**
+ * The best common ancestor of `base` with each of `revs` (`git merge-base`), in input order, or `null`
+ * for a revision that shares no history with `base` (task-274: a ref's copy of an element counts only
+ * when the ref changed it since this commit). One `git merge-base` per revision.
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when git fails for another reason.
+ */
+function mergeBasesWith(root, base, revs, options = {}) {
+    return revs.map((rev) => {
+        const run = (0, git_read_1.runGitRead)(root, ['merge-base', base, rev], gitReadOptions(options, [0, 1]));
+        return run.status === 1 ? null : run.stdout.trim();
+    });
 }
 //# sourceMappingURL=commit.js.map