@astrosheep/keiyaku 4.6.3 → 4.6.6

package/build/src/git/repository.js

@@ -2,7 +2,7 @@ import { isAbsolute, resolve } from "node:path";
 import { realpath } from "node:fs/promises";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { gitObjectId } from "./identity.js";
-import { GitPlumbingError, runGit, runGitWithEnvironment } from "./process.js";
+import { executeGit, GitPlumbingError } from "./process.js";
 import { parseTreeObject, prepareTreeUpdate, treeUpdate, validPath, } from "./tree.js";
 export const GIT_REF = "refs/heads/keiyaku-state";
 export const DELIVERY_REF_NAMESPACE = "refs/keiyaku/delivery";
@@ -11,7 +11,7 @@ export const HANDOFF_RECEIPT_REF_NAMESPACE = "refs/keiyaku/handoff";
 export const GIT_FORMAT_PATH = "meta/format.json";
 const CURRENT_FORMAT_VERSION = 4;
 export const GIT_FORMAT_BYTES = `{"version":${CURRENT_FORMAT_VERSION}}\n`;
-export const STATE_COMMIT_SUBJECT = "keiyaku authority - do not delete or rewrite";
+const STATE_COMMIT_SUBJECT = "keiyaku authority - do not delete or rewrite";
 export function isKeiyakuOwnedRef(ref) {
     return (ref === GIT_REF ||
         ref === DELIVERY_REF_NAMESPACE ||
@@ -67,7 +67,7 @@ function worktreesFromPorcelain(output) {
     return worktrees;
 }
 export async function registeredWorktrees(repository) {
-    return await Promise.all(worktreesFromPorcelain(await runGit(repository, ["worktree", "list", "--porcelain", "-z"])).map(async (worktree) => {
+    return await Promise.all(worktreesFromPorcelain(await executeGit(repository, ["worktree", "list", "--porcelain", "-z"])).map(async (worktree) => {
         const { prunable, ...registered } = worktree;
         try {
             return { ...registered, path: await realpath(registered.path) };
@@ -111,7 +111,9 @@ export async function repositoryAt(cwd, gitPath = "git") {
     return { gitPath, effectiveCwd, invocationWorktree, primaryWorktree, commonDirectory };
 }
 async function absoluteGitPath(repository, args, label) {
-    const value = (await runGit(repository, ["rev-parse", "--path-format=absolute", ...args])).toString("utf8").trim();
+    const value = (await executeGit(repository, ["rev-parse", "--path-format=absolute", ...args]))
+        .toString("utf8")
+        .trim();
     if (value.length === 0)
         throw new Error(`${label} is empty`);
     return await realpath(resolve(isAbsolute(value) ? value : resolve(repository.effectiveCwd, value)));
@@ -123,7 +125,7 @@ export async function worktreeGitDirectory(repository, worktree) {
     const scoped = { ...repository, effectiveCwd: worktree };
     return await absoluteGitPath(scoped, ["--git-dir"], "worktree Git directory");
 }
-export async function worktreeRoot(repository) {
+async function worktreeRoot(repository) {
     return await absoluteGitPath(repository, ["--show-toplevel"], "worktree root");
 }
 function assertRef(ref) {
@@ -138,7 +140,7 @@ function assertAssertionRef(ref) {
 export async function readRef(repository, ref) {
     assertAssertionRef(ref);
     try {
-        const oid = (await runGit(repository, ["rev-parse", "--verify", "--quiet", ref])).toString("utf8").trim();
+        const oid = (await executeGit(repository, ["rev-parse", "--verify", "--quiet", ref])).toString("utf8").trim();
         return oid.length === 0 ? null : gitObjectId(oid, `ref ${ref}`);
     }
     catch (error) {
@@ -154,7 +156,7 @@ export async function readRefs(repository, refs) {
         assertAssertionRef(ref);
     if (refsToRead.length === 0)
         return new Map();
-    const output = (await runGit(repository, ["cat-file", "--batch-check=%(objectname)"], `${refsToRead.join("\n")}\n`)).toString("utf8");
+    const output = (await executeGit(repository, ["cat-file", "--batch-check=%(objectname)"], `${refsToRead.join("\n")}\n`)).toString("utf8");
     const records = output.split("\n");
     if (records.pop() !== "" || records.length !== refsToRead.length)
         throw new Error("Git ref batch output is malformed");
@@ -168,7 +170,7 @@ export async function readRefs(repository, refs) {
 }
 async function readTreeForCommit(repository, commit) {
     gitObjectId(commit, "Git commit");
-    const tree = (await runGit(repository, ["show", "-s", "--format=%T", commit])).toString("utf8").trim();
+    const tree = (await executeGit(repository, ["show", "-s", "--format=%T", commit])).toString("utf8").trim();
     gitObjectId(tree, "Git tree");
     return tree;
 }
@@ -190,21 +192,6 @@ function parseTreeEntries(output) {
     }
     return entries;
 }
-export async function readTreeEntries(repository, tree) {
-    gitObjectId(tree, "tree");
-    const output = await runGit(repository, ["ls-tree", "-r", "-z", "--full-tree", tree]);
-    return parseTreeEntries(output);
-}
-export async function readGit(repository) {
-    const commit = await readRef(repository, GIT_REF);
-    if (commit === null) {
-        return { commit: null, tree: null, paths: new Map() };
-    }
-    const tree = await readTreeForCommit(repository, commit);
-    const paths = await readTreeEntries(repository, tree);
-    await validateGitFormat(repository, paths);
-    return { commit, tree, paths };
-}
 /** Read only the requested private Git paths from one immutable Git tree. */
 export async function readGitPaths(repository, requestedPaths) {
     for (const path of requestedPaths)
@@ -213,18 +200,18 @@ export async function readGitPaths(repository, requestedPaths) {
     if (commit === null)
         return { commit: null, tree: null, paths: new Map() };
     const tree = await readTreeForCommit(repository, commit);
-    const paths = parseTreeEntries(await runGit(repository, ["ls-tree", "-z", "--full-tree", tree, "--", GIT_FORMAT_PATH, ...requestedPaths]));
+    const paths = parseTreeEntries(await executeGit(repository, ["ls-tree", "-z", "--full-tree", tree, "--", GIT_FORMAT_PATH, ...requestedPaths]));
     await validateGitFormat(repository, paths);
     return { commit, tree, paths };
 }
 export async function writeBlob(repository, bytes) {
-    const oid = (await runGit(repository, ["hash-object", "-w", "--stdin"], bytes)).toString("utf8").trim();
+    const oid = (await executeGit(repository, ["hash-object", "-w", "--stdin"], bytes)).toString("utf8").trim();
     gitObjectId(oid, "written blob");
     return oid;
 }
 export async function readBlob(repository, oid) {
     gitObjectId(oid, "blob");
-    return await runGit(repository, ["cat-file", "blob", oid]);
+    return await executeGit(repository, ["cat-file", "blob", oid]);
 }
 function malformedBatchOutput(detail) {
     throw new GitPlumbingError({
@@ -239,7 +226,7 @@ async function readObjects(repository, oids) {
         gitObjectId(oid, "Git object");
     if (unique.length === 0)
         return new Map();
-    const output = await runGit(repository, ["cat-file", "--batch"], `${unique.join("\n")}\n`);
+    const output = await executeGit(repository, ["cat-file", "--batch"], `${unique.join("\n")}\n`);
     const objects = new Map();
     let offset = 0;
     for (const oid of unique) {
@@ -290,7 +277,7 @@ async function baseTreeEntries(repository, baseTree, changedPaths, nodePaths) {
     const byPath = new Map();
     if (baseTree === null)
         return byPath;
-    const ancestry = parseTreeEntries(await runGit(repository, [
+    const ancestry = parseTreeEntries(await executeGit(repository, [
         "ls-tree",
         "-z",
         "-t",
@@ -323,7 +310,7 @@ async function baseTreeEntries(repository, baseTree, changedPaths, nodePaths) {
     return byPath;
 }
 async function writePreparedTrees(repository, prepared) {
-    const output = await runGit(repository, ["mktree", "--batch"], prepared.map(({ records }) => `${records}\n`).join(""));
+    const output = await executeGit(repository, ["mktree", "--batch"], prepared.map(({ records }) => `${records}\n`).join(""));
     const written = output.toString("ascii").trimEnd().split("\n");
     if (written.length !== prepared.length) {
         throw new GitPlumbingError({ stderr: output, status: null, message: "malformed mktree --batch output" });
@@ -364,7 +351,7 @@ async function writeCommitObject(input) {
     const args = ["commit-tree", tree];
     for (const parent of parents)
         args.push("-p", parent);
-    const commit = (await runGitWithEnvironment(repository, args, `${message}\n`, {
+    const commit = (await executeGit(repository, args, `${message}\n`, {
         GIT_AUTHOR_NAME: actor,
         GIT_AUTHOR_EMAIL: email,
         GIT_COMMITTER_NAME: actor,
@@ -420,7 +407,7 @@ export async function updateRefsAtomically(repository, updates, assertions = [])
     }
     const lines = ["start", ...assertions.map(refAssertionLine), ...updates.map(refUpdateLine), "prepare", "commit", ""];
     try {
-        await runGit(repository, ["update-ref", "--stdin"], lines.join("\n"));
+        await executeGit(repository, ["update-ref", "--stdin"], lines.join("\n"));
         return { kind: "published" };
     }
     catch (error) {

package/build/src/git/scratch.d.ts

@@ -1,23 +1,23 @@
 import { z } from "zod";
-import type { SnapshotId } from "../core/facts/types.js";
+import type { ContractId, SnapshotId } from "../core/facts/types.js";
 import { type GitRepository } from "./process.js";
 export type MaterializedScratchCandidate = Readonly<{
     cwd: string;
-    dispose: () => Promise<WorktreeLeak | null>;
+    dispose: (retain?: boolean) => Promise<WorktreeLeak | null>;
 }>;
 export declare const worktreeLeakSchema: z.ZodObject<{
-    path: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
     diagnostic: z.ZodString;
 }, z.core.$strict>;
 export type WorktreeLeak = z.infer<typeof worktreeLeakSchema>;
 type CollectableScratchRemoval = Readonly<{
     path: string;
-    action: "removed" | "unchanged";
+    /** False only when Git removed the path and absence was confirmed; retained removals own a diagnostic. */
     retained: boolean;
     diagnostic?: string;
 }>;
 /** Remove only abandoned Verification scratch worktrees whose ownership locks are held. */
-export declare function removeCollectableScratchWorktrees(repository: GitRepository, paths: Set<string>): Promise<readonly CollectableScratchRemoval[]>;
+export declare function removeCollectableScratchWorktrees(repository: GitRepository, paths: Set<string>, terminalContract?: ContractId): Promise<readonly CollectableScratchRemoval[]>;
 /** Materialize a disposable candidate worktree and own only its removal. */
-export declare function materializeScratchCandidate(repository: GitRepository, candidate: SnapshotId): Promise<MaterializedScratchCandidate>;
+export declare function materializeScratchCandidate(repository: GitRepository, candidate: SnapshotId, contract?: ContractId): Promise<MaterializedScratchCandidate>;
 export {};

package/build/src/git/scratch.js

@@ -1,18 +1,23 @@
 import { z } from "zod";
 import { randomBytes } from "node:crypto";
-import { access, realpath, unlink } from "node:fs/promises";
+import { lstat, realpath, unlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
-import { tryAcquireSqliteTransactionLock, } from "../coordination/sqlite-transaction-lock.js";
-import { gitObjectIdForSnapshot } from "./identity.js";
-import { runGit } from "./process.js";
+import { acquireSqliteTransactionLock, tryAcquireSqliteTransactionLock, } from "../coordination/sqlite-transaction-lock.js";
+import { contractLocator, gitRefLocator, gitObjectIdForSnapshot } from "./identity.js";
+import { executeGit } from "./process.js";
 const SCRATCH_PREFIX = "keiyaku-v4-verify-";
 const SCRATCH_ROOT = await realpath(tmpdir());
-const SCRATCH_PATTERN = /^keiyaku-v4-verify-([0-9a-f]{24})$/;
-export const worktreeLeakSchema = z.object({ path: z.string(), diagnostic: z.string() }).strict();
+const SCRATCH_PATTERN = /^keiyaku-v4-verify-([0-9a-f]{24}|[0-9a-f]{64}-[0-9a-f]{64})$/;
+/** One bounded removal attempt per scratch; expiry is reported, never retried inside this call. */
+const SCRATCH_REMOVAL_TIMEOUT_MS = 120_000;
+export const worktreeLeakSchema = z.object({ path: z.string().optional(), diagnostic: z.string() }).strict();
 function scratchPath() {
     return join(SCRATCH_ROOT, `${SCRATCH_PREFIX}${randomBytes(12).toString("hex")}`);
 }
+function retainedScratchPath(repository, contract) {
+    return join(SCRATCH_ROOT, `${SCRATCH_PREFIX}${gitRefLocator(repository.commonDirectory)}-${contractLocator(contract)}`);
+}
 function ownershipLockPath(path) {
     if (dirname(path) !== SCRATCH_ROOT)
         return null;
@@ -25,69 +30,132 @@ async function removeOwnershipLock(lockPath) {
             throw error;
     });
 }
-async function collectableScratchWorktrees(paths) {
+async function collectableScratchWorktrees(paths, terminalScratch) {
     const collectable = [];
     for (const path of paths) {
         const lockPath = ownershipLockPath(path);
         if (lockPath === null)
             continue;
+        if (basename(path).length !== SCRATCH_PREFIX.length + 24 && path !== terminalScratch)
+            continue;
         const lock = await tryAcquireSqliteTransactionLock({ path: lockPath, mode: "exclusive" });
         if (lock !== null)
             collectable.push({ path, lockPath, release: () => lock.close() });
     }
     return collectable;
 }
-const pathExists = (path) => access(path).then(() => true, () => false);
+/** Absence is ENOENT on the path entry itself: a dangling symlink is present residue, not a missing path. */
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+async function removeScratch(repository, path) {
+    const removal = AbortSignal.timeout(SCRATCH_REMOVAL_TIMEOUT_MS);
+    try {
+        const present = await pathExists(path);
+        await executeGit({ ...repository, signal: removal }, ["worktree", "remove", ...(present ? ["--force"] : []), path]);
+        return (await pathExists(path))
+            ? { path, diagnostic: `Git reported scratch worktree removal but the path remains: ${path}` }
+            : null;
+    }
+    catch (error) {
+        const original = error instanceof Error ? error.message : String(error);
+        return {
+            path,
+            diagnostic: removal.aborted
+                ? `scratch worktree removal timed out after ${SCRATCH_REMOVAL_TIMEOUT_MS}ms: ${original}`
+                : original,
+        };
+    }
+}
 /** Remove only abandoned Verification scratch worktrees whose ownership locks are held. */
-export async function removeCollectableScratchWorktrees(repository, paths) {
+export async function removeCollectableScratchWorktrees(repository, paths, terminalContract) {
     const removals = [];
-    for (const scratch of await collectableScratchWorktrees(paths)) {
+    const terminalScratch = terminalContract === undefined ? undefined : retainedScratchPath(repository, terminalContract);
+    for (const scratch of await collectableScratchWorktrees(paths, terminalScratch)) {
         let removed = false;
         try {
-            if (!(await pathExists(scratch.path))) {
-                await runGit(repository, ["worktree", "remove", scratch.path]);
-                paths.delete(scratch.path);
-                removed = true;
-                removals.push({ path: scratch.path, action: "removed", retained: false });
+            const leak = await removeScratch(repository, scratch.path);
+            if (leak !== null) {
+                removals.push({ path: scratch.path, retained: true, diagnostic: leak.diagnostic });
                 continue;
             }
-            try {
-                await runGit(repository, ["worktree", "remove", "--force", scratch.path]);
-                paths.delete(scratch.path);
-                removed = true;
-                removals.push({ path: scratch.path, action: "removed", retained: false });
-            }
-            catch (error) {
-                removals.push({
-                    path: scratch.path,
-                    action: "unchanged",
-                    retained: true,
-                    diagnostic: error instanceof Error ? error.message : String(error),
-                });
-            }
+            paths.delete(scratch.path);
+            removed = true;
+            removals.push({ path: scratch.path, retained: false });
         }
         finally {
             scratch.release();
-            if (removed)
+            if (removed && scratch.path !== terminalScratch)
                 await removeOwnershipLock(scratch.lockPath);
         }
     }
     return removals;
 }
+async function retainScratch(repository, cwd, contract) {
+    const retained = retainedScratchPath(repository, contract);
+    const lockPath = ownershipLockPath(retained);
+    if (lockPath === null)
+        throw new Error("scratch ownership lock path is invalid");
+    const { signal: _signal, ...retirementRepository } = repository;
+    const fallback = async (reason) => {
+        const ownLeak = await removeScratch(retirementRepository, cwd);
+        return {
+            ...(ownLeak === null ? {} : { path: ownLeak.path }),
+            diagnostic: `failed Verification scratch could not be retained: ${reason}${ownLeak === null ? "" : `; ${ownLeak.diagnostic}`}`,
+        };
+    };
+    let lock;
+    try {
+        lock = await acquireSqliteTransactionLock({
+            path: lockPath,
+            mode: "exclusive",
+            timeoutMs: SCRATCH_REMOVAL_TIMEOUT_MS,
+        });
+    }
+    catch (error) {
+        return await fallback(`retained scratch busy: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        const replaced = await pathExists(retained);
+        if (replaced) {
+            const leak = await removeScratch(retirementRepository, retained);
+            if (leak !== null)
+                return await fallback(leak.diagnostic);
+        }
+        await executeGit(retirementRepository, ["worktree", "move", cwd, retained]);
+        return {
+            path: retained,
+            diagnostic: `failed Verification scratch retained for diagnosis${replaced ? " (replaced the previous retained scratch)" : ""}`,
+        };
+    }
+    catch (error) {
+        return await fallback(error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        lock.close();
+    }
+}
 /** Materialize a disposable candidate worktree and own only its removal. */
-export async function materializeScratchCandidate(repository, candidate) {
+export async function materializeScratchCandidate(repository, candidate, contract) {
     const cwd = scratchPath();
     const lockPath = ownershipLockPath(cwd);
     if (lockPath === null)
         throw new Error("scratch ownership lock path is invalid");
-    const ownership = await tryAcquireSqliteTransactionLock({
+    const ownership = await acquireSqliteTransactionLock({
         path: lockPath,
         mode: "exclusive",
+        ...(repository.signal === undefined ? {} : { signal: repository.signal }),
     });
-    if (ownership === null)
-        throw new Error("new scratch ownership lock is unexpectedly held");
     try {
-        await runGit(repository, ["worktree", "add", "--detach", cwd, gitObjectIdForSnapshot(candidate)]);
+        await executeGit(repository, ["worktree", "add", "--detach", cwd, gitObjectIdForSnapshot(candidate)]);
     }
     catch (error) {
         ownership.close();
@@ -97,26 +165,22 @@ export async function materializeScratchCandidate(repository, candidate) {
     let disposed = false;
     return {
         cwd,
-        dispose: async () => {
+        dispose: async (retain = false) => {
             if (disposed)
                 return null;
             disposed = true;
-            let leak = null;
             try {
-                await runGit({ ...repository, signal: AbortSignal.timeout(5_000) }, ["worktree", "remove", "--force", cwd]);
-            }
-            catch (error) {
-                leak = {
-                    path: cwd,
-                    diagnostic: error instanceof Error ? error.message : String(error),
-                };
+                if (!retain)
+                    return await removeScratch(repository, cwd);
+                if (contract === undefined)
+                    return { path: cwd, diagnostic: "failed Verification scratch retained for diagnosis" };
+                return await retainScratch(repository, cwd, contract);
             }
             finally {
                 ownership.close();
-                if (leak === null)
+                if (!(await pathExists(cwd)))
                     await removeOwnershipLock(lockPath);
             }
-            return leak;
         },
     };
 }

package/build/src/git/target-placement.d.ts

@@ -30,7 +30,7 @@ export declare const targetCheckoutLagSchema: z.ZodObject<{
     diagnostic: z.ZodString;
 }, z.core.$strict>;
 type TargetCheckoutLag = z.infer<typeof targetCheckoutLagSchema>;
-export type TargetPlacementPhysicalResult = Readonly<{
+type TargetPlacementPhysicalResult = Readonly<{
     effects: readonly TargetCheckoutEffect[];
     lag: readonly TargetCheckoutLag[];
 }>;
@@ -42,7 +42,7 @@ export type PreparedTargetPlacement = Readonly<{
     target: RefOperation;
     arms: readonly FollowArm[];
 }>;
-export type TargetPlacementPreparation = Readonly<{
+type TargetPlacementPreparation = Readonly<{
     kind: "prepared";
     placement: PreparedTargetPlacement;
 }> | Readonly<{
@@ -63,16 +63,16 @@ export type TargetPlacementChanges = Readonly<{
 /** Only immutable commit contents are prepared outside the publication seat. */
 export declare function prepareTargetPlacementChanges(repository: GitRepository, target: RefOperation): Promise<TargetPlacementChanges>;
 export declare function acquireTargetPlacementFence(repository: GitRepository, target: string): Promise<HeldSqliteTransactionLock>;
-export type TargetedContractCoordinates = ContractState["coordinates"] & Readonly<{
+type TargetedContractCoordinates = ContractState["coordinates"] & Readonly<{
     target: string;
 }>;
-export type TargetPlacementObservationInput = Readonly<{
+type TargetPlacementObservationInput = Readonly<{
     contractId: ContractId;
     coordinates: TargetedContractCoordinates;
     predecessor: SnapshotId;
     candidate: SnapshotId;
 }>;
-export type TargetPlacementObservation = Readonly<{
+type TargetPlacementObservation = Readonly<{
     kind: "ready";
     arms: readonly FollowArm[];
 }> | Readonly<{

package/build/src/git/target-placement.js

@@ -6,7 +6,7 @@ import { resolve } from "node:path";
 import { acquireSqliteTransactionLock, } from "../coordination/sqlite-transaction-lock.js";
 import { gitObjectId, gitObjectIdForSnapshot, gitRefLocator, mintSnapshotId } from "./identity.js";
 import { commonGitDirectory, decodeGitNameOnly, readRef, registeredWorktrees } from "./repository.js";
-import { consumeGitStdout, GitPlumbingError, runGit } from "./process.js";
+import { consumeGitStdout, GitPlumbingError, executeGit } from "./process.js";
 import { captureWorkspaceTree } from "./workspace.js";
 export const checkoutNotFollowableRefusalSchema = z
     .object({
@@ -42,13 +42,15 @@ function diagnostic(error) {
     return error instanceof Error ? error.message : String(error);
 }
 async function gitPaths(repository, path, args) {
-    return [...new Set(decodeGitNameOnly(await runGit(repository, ["-C", path, ...args])))].sort();
+    return [...new Set(decodeGitNameOnly(await executeGit(repository, ["-C", path, ...args])))].sort();
 }
 function literalPath(path) {
     return `:(literal)${path}`;
 }
 async function commitTree(repository, snapshot) {
-    return gitObjectId((await runGit(repository, ["show", "-s", "--format=%T", gitObjectIdForSnapshot(snapshot)])).toString("utf8").trim(), "commit tree");
+    return gitObjectId((await executeGit(repository, ["show", "-s", "--format=%T", gitObjectIdForSnapshot(snapshot)]))
+        .toString("utf8")
+        .trim(), "commit tree");
 }
 export async function observedTreeEqualsCandidate(repository, observed, snapshot) {
     if (observed === null)
@@ -60,7 +62,7 @@ function checkoutRefusal(contractId, target, path, reason, paths) {
 }
 /** Only immutable commit contents are prepared outside the publication seat. */
 export async function prepareTargetPlacementChanges(repository, target) {
-    const records = (await runGit(repository, [
+    const records = (await executeGit(repository, [
         "diff",
         "--raw",
         "--no-renames",
@@ -175,27 +177,10 @@ async function untrackedRefusalWithinScopes(input, scopes) {
     const first = directories.find((scope) => found.has(scope.path));
     return first === undefined ? null : checkoutRefusal(contractId, target, path, "untracked", [first.path]);
 }
-async function indexMatchesTreeOnPaths(repository, path, tree, paths) {
-    return ((await gitPaths(repository, path, [
-        "diff-index",
-        "--cached",
-        "--name-only",
-        "-z",
-        tree,
-        "--",
-        ...paths.map(literalPath),
-    ])).length === 0);
-}
-async function workspaceMatchesTreeOnPaths(repository, path, tree, workspaceTree, paths) {
-    return ((await gitPaths(repository, path, [
-        "diff",
-        "--name-only",
-        "-z",
-        tree,
-        workspaceTree,
-        "--",
-        ...paths.map(literalPath),
-    ])).length === 0);
+/** Compare the index or a workspace tree against another tree over the given paths. */
+async function matchesTreeOnPaths(repository, path, command, trees, paths) {
+    const args = [...command, "--name-only", "-z", ...trees, "--", ...paths.map(literalPath)];
+    return (await gitPaths(repository, path, args)).length === 0;
 }
 /**
  * A checkout that git cannot carry is judged by the physical follow, which records its own lag.
@@ -207,7 +192,7 @@ async function ordinaryPrecheck(repository, contractId, target, path, changes) {
     const candidate = gitObjectIdForSnapshot(target.newOid);
     const observation = { repository, contractId, target, path, predecessor, candidate, changes };
     try {
-        await runGit(repository, ["-C", path, "read-tree", "--dry-run", "-m", "-u", predecessor, candidate]);
+        await executeGit(repository, ["-C", path, "read-tree", "--dry-run", "-m", "-u", predecessor, candidate]);
     }
     catch (error) {
         if (!(error instanceof GitPlumbingError) || repository.signal?.aborted === true)
@@ -311,7 +296,7 @@ export async function followTargetPlacement(repository, prepared, onPhysical) {
     for (const arm of prepared.arms) {
         const beforeEffects = effects.length, beforeLag = lag.length;
         try {
-            await runGit(repository, ["-C", arm.path, "read-tree", "-m", "-u", predecessor, candidate]);
+            await executeGit(repository, ["-C", arm.path, "read-tree", "-m", "-u", predecessor, candidate]);
             effects.push({ kind: "target-checkout", path: arm.path, target: prepared.target.target, action: "followed" });
         }
         catch (error) {
@@ -337,15 +322,15 @@ async function classifyCheckout(input) {
     if (changedPaths.length === 0)
         return { kind: "complete" };
     const workspaceTree = (await captureWorkspaceTree(repository, path)).tree;
-    const candidateIndex = await indexMatchesTreeOnPaths(repository, path, candidateTree, changedPaths);
-    const candidateWorkspace = await workspaceMatchesTreeOnPaths(repository, path, candidateTree, workspaceTree, changedPaths);
+    const candidateIndex = await matchesTreeOnPaths(repository, path, ["diff-index", "--cached"], [candidateTree], changedPaths);
+    const candidateWorkspace = await matchesTreeOnPaths(repository, path, ["diff"], [candidateTree, workspaceTree], changedPaths);
     if (candidateIndex && candidateWorkspace)
         return { kind: "complete" };
-    const predecessorIndex = await indexMatchesTreeOnPaths(repository, path, predecessorTree, changedPaths);
+    const predecessorIndex = await matchesTreeOnPaths(repository, path, ["diff-index", "--cached"], [predecessorTree], changedPaths);
     if (predecessorIndex && candidateWorkspace)
         return { kind: "recoverable", action: "index-merge" };
     return !predecessorIndex ||
-        !(await workspaceMatchesTreeOnPaths(repository, path, predecessorTree, workspaceTree, changedPaths))
+        !(await matchesTreeOnPaths(repository, path, ["diff"], [predecessorTree, workspaceTree], changedPaths))
         ? { kind: "retained" }
         : { kind: "recoverable", action: "worktree-merge" };
 }
@@ -365,7 +350,7 @@ async function recoverCheckout(input) {
         return "retained";
     const { repository, path, predecessor, candidate } = input;
     if (classified.action === "index-merge") {
-        await runGit(repository, [
+        await executeGit(repository, [
             "-C",
             path,
             "read-tree",
@@ -376,7 +361,7 @@ async function recoverCheckout(input) {
         ]);
         return "recovered";
     }
-    await runGit(repository, [
+    await executeGit(repository, [
         "-C",
         path,
         "read-tree",

package/build/src/git/tender.d.ts

@@ -4,7 +4,7 @@ import type { ActorId, ContractCoordinates, ContractId, SnapshotId } from "../co
 import { type GitObjectId } from "./identity.js";
 import { type GitRepository } from "./process.js";
 import { captureWorkspaceTree } from "./workspace.js";
-export type TenderCaptureCoordinates = Readonly<{
+type TenderCaptureCoordinates = Readonly<{
     contractId: ContractId;
     coordinates: ContractCoordinates;
     place?: string;
@@ -23,7 +23,7 @@ export declare const unmergedPathsRefusalSchema: z.ZodObject<{
     contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
     paths: z.ZodReadonly<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
-export type TenderCaptureRefusal = WorktreeMissingRefusal | z.infer<typeof unmergedPathsRefusalSchema>;
+type TenderCaptureRefusal = WorktreeMissingRefusal | z.infer<typeof unmergedPathsRefusalSchema>;
 export declare const workspaceDirtyDeltaSchema: z.ZodObject<{
     staged: z.ZodReadonly<z.ZodArray<z.ZodString>>;
     unstaged: z.ZodReadonly<z.ZodArray<z.ZodString>>;
@@ -81,6 +81,10 @@ export declare function prepareDeliveryCommitMetadata(repository: GitRepository,
     actor?: ActorId;
     message?: string;
 }>): Promise<DeliveryCommitMetadata>;
+/** The Git identity environment for one delivery snapshot commit. */
+export declare function deliveryEnvironment(commit: DeliveryCommitMetadata): NodeJS.ProcessEnv;
+/** Materialize one delivery snapshot commit over the given parents. */
+export declare function materializeSnapshotCommit(repository: GitRepository, tree: GitObjectId, parents: readonly SnapshotId[], message: string | Uint8Array, environment: NodeJS.ProcessEnv): Promise<SnapshotId>;
 /** Materialize the tender tree when it contains admitted dirty workspace bytes. */
 export declare function materializeTenderSnapshot(repository: GitRepository, tender: TenderCapture, commit: DeliveryCommitMetadata): Promise<SnapshotId>;
 export {};