@astrosheep/keiyaku 4.6.4 → 4.6.7

package/build/src/git/integration.js

@@ -3,13 +3,15 @@ import { z } from "zod";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { gitObjectId, gitObjectIdForSnapshot, mintChangeId, mintSnapshotId } from "./identity.js";
 import { decodeGitNameOnly, decodeGitNumstat, readRef } from "./repository.js";
-import { GitPlumbingError, runGit, runGitPipe, runGitWithEnvironment } from "./process.js";
+import { executeGit, GitPlumbingError, runGitPipe } from "./process.js";
+import { deliveryEnvironment, materializeSnapshotCommit, } from "./tender.js";
 import { workspaceMergeStatePresent } from "./workspace.js";
+import { withGitDecodeChannel } from "./read-observation.js";
 export { workspaceMergeStatePresent };
 const REQUIRED_GIT = "2.38";
 async function runAllowingNonzero(repository, args, input) {
     try {
-        return { stdout: await runGit(repository, args, input), stderr: Buffer.alloc(0), status: 0 };
+        return { stdout: await executeGit(repository, args, input), stderr: Buffer.alloc(0), status: 0 };
     }
     catch (error) {
         if (!(error instanceof GitPlumbingError))
@@ -76,22 +78,34 @@ export async function worktreeChangeId(repository, input, tender) {
     const id = result.toString("utf8").trim().split(/\s/, 1)[0] ?? "";
     return mintChangeId(id === "" ? "0000000000000000000000000000000000000000" : id);
 }
+/** Reuse only recorded commits with this exact tree and sole predecessor. */
+export async function reusableIntegrationSnapshot(repository, tree, parent, recordedSnapshots) {
+    if (recordedSnapshots.length === 0)
+        return undefined;
+    return await withGitDecodeChannel(repository, async (channel) => {
+        for (const snapshot of recordedSnapshots) {
+            const oid = gitObjectIdForSnapshot(snapshot);
+            const object = (await channel.readObjects([oid])).get(oid);
+            if (object.kind === "missing")
+                continue;
+            if (object.type !== "commit") {
+                throw new AuthorityCorruptionError(`recorded integration snapshot is not a Git commit: ${snapshot}`);
+            }
+            const headers = object.bytes.toString("utf8").split("\n\n", 1)[0].split("\n");
+            const parents = headers.filter((line) => line.startsWith("parent "));
+            if (headers[0] === `tree ${tree}` && parents.length === 1 && parents[0] === `parent ${parent}`) {
+                return snapshot;
+            }
+        }
+        return undefined;
+    });
+}
 /** Materialize the exact integration tree against its observed predecessor. */
 export async function materializeIntegrationSnapshot(repository, tree, parent, metadata) {
-    const commit = (await runGitWithEnvironment(repository, ["commit-tree", tree, "-p", gitObjectIdForSnapshot(parent)], metadata.message, {
-        GIT_AUTHOR_NAME: metadata.identity.name,
-        GIT_AUTHOR_EMAIL: metadata.identity.email,
-        GIT_COMMITTER_NAME: metadata.identity.name,
-        GIT_COMMITTER_EMAIL: metadata.identity.email,
-        GIT_AUTHOR_DATE: metadata.at,
-        GIT_COMMITTER_DATE: metadata.at,
-    }))
-        .toString("utf8")
-        .trim();
-    return mintSnapshotId(commit);
+    return await materializeSnapshotCommit(repository, tree, [parent], metadata.message, deliveryEnvironment(metadata));
 }
 export async function persistedTender(repository, snapshot) {
-    const tree = (await runGit(repository, ["show", "-s", "--format=%T", gitObjectIdForSnapshot(snapshot)]))
+    const tree = (await executeGit(repository, ["show", "-s", "--format=%T", gitObjectIdForSnapshot(snapshot)]))
         .toString("ascii")
         .trim();
     return { head: snapshot, tree: gitObjectId(tree, "persisted tender tree") };
@@ -100,7 +114,7 @@ export async function materializeReintegrationSnapshot(repository, tree, parent,
     const templateObject = gitObjectIdForSnapshot(template);
     let raw;
     try {
-        raw = await runGit(repository, ["cat-file", "commit", templateObject]);
+        raw = await executeGit(repository, ["cat-file", "commit", templateObject]);
     }
     catch (error) {
         if (error instanceof GitPlumbingError) {
@@ -114,7 +128,7 @@ export async function materializeReintegrationSnapshot(repository, tree, parent,
     const message = raw.subarray(separator + 2);
     let fields;
     try {
-        const formatted = (await runGit(repository, ["show", "-s", "--format=%an%x00%ae%x00%aI%x00%cn%x00%ce%x00%cI", templateObject]))
+        const formatted = (await executeGit(repository, ["show", "-s", "--format=%an%x00%ae%x00%aI%x00%cn%x00%ce%x00%cI", templateObject]))
             .toString("utf8")
             .replace(/\n$/u, "");
         fields = formatted.split("\0");
@@ -129,17 +143,14 @@ export async function materializeReintegrationSnapshot(repository, tree, parent,
         throw new AuthorityCorruptionError(`recorded delivery snapshot metadata is malformed: ${template}`);
     }
     const [authorName, authorEmail, authorDate, committerName, committerEmail, committerDate] = fields;
-    const commit = (await runGitWithEnvironment(repository, ["commit-tree", tree, "-p", gitObjectIdForSnapshot(parent)], message, {
+    return await materializeSnapshotCommit(repository, tree, [parent], message, {
         GIT_AUTHOR_NAME: authorName,
         GIT_AUTHOR_EMAIL: authorEmail,
         GIT_AUTHOR_DATE: authorDate,
         GIT_COMMITTER_NAME: committerName,
         GIT_COMMITTER_EMAIL: committerEmail,
         GIT_COMMITTER_DATE: committerDate,
-    }))
-        .toString("utf8")
-        .trim();
-    return mintSnapshotId(commit);
+    });
 }
 async function isAncestor(repository, ancestor, descendant) {
     const result = await runAllowingNonzero(repository, [
@@ -302,7 +313,7 @@ export async function planIntegration(repository, input, tender, requireBranches
 }
 async function deliverySnapshotAvailability(repository, predecessor, candidate) {
     const objects = [gitObjectIdForSnapshot(predecessor), gitObjectIdForSnapshot(candidate)];
-    const types = (await runGit(repository, ["cat-file", "--batch-check=%(objectname) %(objecttype)"], `${objects.join("\n")}\n`))
+    const types = (await executeGit(repository, ["cat-file", "--batch-check=%(objectname) %(objecttype)"], `${objects.join("\n")}\n`))
         .toString("ascii")
         .trimEnd()
         .split("\n")
@@ -323,7 +334,7 @@ export const deliveryDiffScopeSchema = z
 })
     .strict();
 export async function readDeliveryScope(repository, predecessor, candidate, includePaths) {
-    const scope = decodeGitNumstat(await runGit(repository, [
+    const scope = decodeGitNumstat(await executeGit(repository, [
         "diff",
         "--numstat",
         "-z",
@@ -334,7 +345,7 @@ export async function readDeliveryScope(repository, predecessor, candidate, incl
         return scope;
     return {
         ...scope,
-        paths: decodeGitNameOnly(await runGit(repository, [
+        paths: decodeGitNameOnly(await executeGit(repository, [
             "diff",
             "--name-only",
             "--no-renames",
@@ -349,7 +360,7 @@ export async function readDeliveryDiff(repository, predecessor, candidate) {
     if ((await deliverySnapshotAvailability(repository, predecessor, candidate)) === "unavailable")
         return null;
     try {
-        return (await runGit(repository, [
+        return (await executeGit(repository, [
             "diff",
             "--no-ext-diff",
             "--no-color",

package/build/src/git/nuke.js

@@ -1,7 +1,7 @@
 import { access, lstat, realpath, rm } from "node:fs/promises";
 import { isAbsolute, relative, sep } from "node:path";
 import { nukeEmptyPlaceAuthority, readPlaceRegister, releaseManagedWorktrees, withPlaceAuthorityFence, } from "../workspace-place.js";
-import { GitPlumbingError, runGit } from "./process.js";
+import { GitPlumbingError, executeGit } from "./process.js";
 import { confirmPrivateStatePublication, withPrivateStatePublicationSeat, } from "./private-state-seat.js";
 import { CANDIDATE_PIN_REF_NAMESPACE, DELIVERY_REF_NAMESPACE, GIT_REF, NoGitWorldError, readRef, registeredWorktrees, repositoryAt, worktreeGitDirectory, } from "./repository.js";
 import { worktreePath } from "./workspace.js";
@@ -89,7 +89,7 @@ async function removeManagedWorktree(repository, entry) {
         return await removeUnregisteredResidue(repository, entry);
     if (registered.branch !== null)
         return false;
-    await runGit(repository, ["worktree", "remove", "--force", entry.path]);
+    await executeGit(repository, ["worktree", "remove", "--force", entry.path]);
     if ((await registeredWorktrees(repository)).some((candidate) => candidate.path === entry.path)) {
         throw new GitResetStopError(`managed Place worktree remains registered: ${entry.path}`);
     }
@@ -104,7 +104,7 @@ async function removeManagedWorktree(repository, entry) {
     throw new GitResetStopError(`managed Place worktree remains present: ${entry.path}`);
 }
 async function deleteRefAt(repository, ref, expectedOid) {
-    await runGit(repository, ["update-ref", "--no-deref", "-d", ref, expectedOid]);
+    await executeGit(repository, ["update-ref", "--no-deref", "-d", ref, expectedOid]);
 }
 async function deleteObservedStateRef(repository, expectedOid, seat) {
     try {
@@ -126,7 +126,7 @@ async function removeOwnedRefs(repository, onRemoved) {
     let removed = 0;
     const roots = [DELIVERY_REF_NAMESPACE, CANDIDATE_PIN_REF_NAMESPACE];
     for (const root of roots) {
-        const refs = (await runGit(repository, ["for-each-ref", "--format=%(refname)", root]))
+        const refs = (await executeGit(repository, ["for-each-ref", "--format=%(refname)", root]))
             .toString("utf8")
             .split("\n")
             .filter((ref) => ref.length > root.length && ref.startsWith(`${root}/`));

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

@@ -3,7 +3,7 @@ import type { ContractsObservation } from "../core/facts/observation.js";
 import { type GitSnapshot, type GitOid } from "./repository.js";
 import { type GitRepository } from "./process.js";
 import { type GitDecodeChannel, type GitReadObservation, type GitTreeSelection } from "./read-observation.js";
-export type TargetObservation = Readonly<{
+type TargetObservation = Readonly<{
     head: SnapshotId | null;
     drift: boolean;
 }>;
@@ -12,11 +12,11 @@ type GitJournalRecord = Readonly<{
     entries: readonly JournalEntry[];
     state: ContractState | null;
 }>;
-export type ContractWorldObservation = Readonly<{
+type ContractWorldObservation = Readonly<{
     snapshot: SnapshotId | null;
     contracts: ReadonlyMap<ContractId, GitJournalRecord>;
 }>;
-export type ActiveContractWorldObservation = ContractWorldObservation & Readonly<{
+type ActiveContractWorldObservation = ContractWorldObservation & Readonly<{
     eligibility: ContractsObservation;
 }>;
 export type GitAdmissionSnapshot = Readonly<{
@@ -34,7 +34,7 @@ export type BindCoordinatesObservation = Readonly<{
     target?: string;
     branch: string | null;
 }>;
-export type UnbornHeadObservation = Readonly<{
+type UnbornHeadObservation = Readonly<{
     kind: "unborn-head";
     branch: string | null;
 }>;

package/build/src/git/observe.js

@@ -3,7 +3,7 @@ import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { foldJournal } from "../core/facts/fold.js";
 import { contractJournalPath, contractJournalPaths, mintContractHead, mintSnapshotId, } from "./identity.js";
 import { isKeiyakuOwnedRef } from "./repository.js";
-import { GitPlumbingError, runGit } from "./process.js";
+import { GitPlumbingError, executeGit } from "./process.js";
 import { readBlobResults, readGitTreeSelection, withGitTargetedReadObservation, } from "./read-observation.js";
 export async function observeDeliveryTargetAt(observation, state) {
     const target = state.coordinates.target;
@@ -29,7 +29,7 @@ export async function normalizeTargetBranch(repository, input) {
     if (branch.length === 0 || branch.startsWith("-") || isKeiyakuOwnedRef(target))
         return null;
     try {
-        const checked = (await runGit(repository, ["check-ref-format", "--branch", branch])).toString("utf8").trim();
+        const checked = (await executeGit(repository, ["check-ref-format", "--branch", branch])).toString("utf8").trim();
         return checked === branch ? target : null;
     }
     catch (error) {
@@ -41,7 +41,7 @@ export async function normalizeTargetBranch(repository, input) {
 /** Read one worktree's attached branch, or null for detached HEAD. */
 export async function currentBranch(repository, path) {
     try {
-        const ref = (await runGit(repository, [...(path === undefined ? [] : ["-C", path]), "symbolic-ref", "--quiet", "HEAD"]))
+        const ref = (await executeGit(repository, [...(path === undefined ? [] : ["-C", path]), "symbolic-ref", "--quiet", "HEAD"]))
             .toString("utf8")
             .trim();
         return ref.startsWith("refs/heads/") ? ref : null;
@@ -64,7 +64,7 @@ function structuredFields(output, fieldCount) {
 async function observeHeadCoordinates(repository) {
     try {
         return {
-            start: mintSnapshotId((await runGit(repository, ["rev-parse", "--verify", "HEAD"])).toString("utf8").trim()),
+            start: mintSnapshotId((await executeGit(repository, ["rev-parse", "--verify", "HEAD"])).toString("utf8").trim()),
             branch: await currentBranch(repository),
         };
     }
@@ -84,7 +84,7 @@ export async function observeBindCoordinates(repository, selection = { kind: "ta
         if (isKeiyakuOwnedRef(requestedTarget)) {
             throw new Error(`bind target names a Keiyaku-owned ref: ${requestedTarget}`);
         }
-        const output = await runGit(repository, [
+        const output = await executeGit(repository, [
             "for-each-ref",
             `--format=${TARGET_COORDINATES_FORMAT}`,
             "--",

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

@@ -16,8 +16,6 @@ export type GitRepository = Readonly<{
     /** Test-only hook after the private-state seat close attempt. */
     readonly onPrivateStateSeatClose?: () => void;
 }>;
-/** Give one caller's Git capability view its cancellation boundary. */
-export declare function withGitAbortSignal(repository: GitRepository, signal: AbortSignal | undefined): GitRepository;
 export declare class GitPlumbingError extends Error {
     readonly stdout: Buffer;
     readonly stderr: Buffer;
@@ -31,8 +29,7 @@ export declare class GitPlumbingError extends Error {
         pid?: number | null;
     }>);
 }
-export declare function runGit(repository: GitRepository, args: readonly string[], input?: string | Uint8Array): Promise<Buffer>;
+export declare function executeGit(repository: GitRepository, args: readonly string[], input?: string | Uint8Array, environment?: NodeJS.ProcessEnv): Promise<Buffer>;
 /** Connect two owned Git commands without materializing the intermediate output. */
 export declare function runGitPipe(repository: GitRepository, sourceArgs: readonly string[], sinkArgs: readonly string[]): Promise<Buffer>;
 export declare function consumeGitStdout(repository: GitRepository, args: readonly string[], consume: (chunk: Buffer) => void): Promise<void>;
-export declare function runGitWithEnvironment(repository: GitRepository, args: readonly string[], input: string | Uint8Array | undefined, environment: NodeJS.ProcessEnv): Promise<Buffer>;

package/build/src/git/process.js

@@ -1,9 +1,5 @@
 import { consumeProcessStdout, spawnCancellableProcess } from "../runtime/proc/run.js";
 import { pipeline } from "node:stream/promises";
-/** Give one caller's Git capability view its cancellation boundary. */
-export function withGitAbortSignal(repository, signal) {
-    return signal === undefined ? repository : { ...repository, signal };
-}
 export class GitPlumbingError extends Error {
     stdout;
     stderr;
@@ -32,7 +28,7 @@ function commandError(command, error) {
         pid: candidate.pid ?? null,
     });
 }
-async function executeGit(repository, args, input, environment) {
+export async function executeGit(repository, args, input, environment) {
     if (repository.signal?.aborted === true) {
         throw commandError(args, { message: "git process cancelled", status: null });
     }
@@ -81,9 +77,6 @@ async function executeGit(repository, args, input, environment) {
         pid: child.pid,
     });
 }
-export async function runGit(repository, args, input) {
-    return await executeGit(repository, args, input);
-}
 function boundedPipeOutput(child, args) {
     const stdout = [];
     let bytes = 0;
@@ -212,6 +205,3 @@ export async function consumeGitStdout(repository, args, consume) {
         pid: result.pid ?? undefined,
     });
 }
-export async function runGitWithEnvironment(repository, args, input, environment) {
-    return await executeGit(repository, args, input, environment);
-}

package/build/src/git/read-observation.js

@@ -6,7 +6,7 @@ import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, readRef } from "./repositor
 import { GitPlumbingError } from "./process.js";
 const gitReadObservationBrand = Symbol("GitReadObservation");
 const gitDecodeChannelBrand = Symbol("GitDecodeChannel");
-const BATCH_RETIREMENT_GRACE_MS = 1_000;
+const BATCH_RETIREMENT_GRACE_MS = 5_000;
 function streamCursor(stream) {
     const iterator = stream[Symbol.asyncIterator]();
     let buffer = Buffer.alloc(0);

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

@@ -142,7 +142,7 @@ type ReconcileBatchItem = Readonly<{
     state: ContractState | null;
     result: ReconcileResult;
 }>;
-export type GitReconcileObservation = Readonly<{
+type GitReconcileObservation = Readonly<{
     state: ContractState | null;
     result: ReconcileResult;
 }>;

package/build/src/git/reconcile.js

@@ -8,7 +8,7 @@ import { dirname, join } from "node:path";
 import { acquireSqliteTransactionLock, SqliteTransactionLockError, } from "../coordination/sqlite-transaction-lock.js";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { CANDIDATE_PIN_REF_NAMESPACE, commonGitDirectory, DELIVERY_REF_NAMESPACE, registeredWorktreePaths, } from "./repository.js";
-import { runGit, GitPlumbingError } from "./process.js";
+import { executeGit, GitPlumbingError } from "./process.js";
 import { contractLocator, contractPhysicalName, gitObjectIdForSnapshot } from "./identity.js";
 import { observeContractAt } from "./observe.js";
 import { acquireTargetPlacementFence, recoverTargetPlacement } from "./target-placement.js";
@@ -158,25 +158,27 @@ async function worktree(repository, topology, path, desired) {
     if (registered && (await pathExists(path)))
         return { kind: "worktree", path, action: "unchanged" };
     if (registered) {
-        await runGit(repository, ["worktree", "remove", path]);
+        await executeGit(repository, ["worktree", "remove", path]);
         topology.paths.delete(path);
     }
     if (await pathExists(path))
         throw new WorktreeCustodyError(`delivery worktree path is occupied: ${path}`);
     await mkdir(dirname(path), { recursive: true });
-    await runGit(repository, ["worktree", "add", "--detach", path, gitObjectIdForSnapshot(desired)]);
+    await executeGit(repository, ["worktree", "add", "--detach", path, gitObjectIdForSnapshot(desired)]);
     topology.paths.add(path);
     return { kind: "worktree", path, action: "created" };
 }
-async function removeCollectableScratch(repository, topology, acc) {
-    for (const removal of await removeCollectableScratchWorktrees(repository, topology.paths)) {
-        acc.recordEffect({ kind: "worktree", path: removal.path, action: removal.action });
-        if (removal.retained)
-            acc.recordLag({
-                kind: "worktree-retained",
-                path: removal.path,
-                ...(removal.diagnostic === undefined ? {} : { diagnostic: removal.diagnostic }),
-            });
+async function removeCollectableScratch(repository, topology, acc, terminalContract) {
+    for (const removal of await removeCollectableScratchWorktrees(repository, topology.paths, terminalContract)) {
+        if (!removal.retained) {
+            acc.recordEffect({ kind: "worktree", path: removal.path, action: "removed" });
+            continue;
+        }
+        acc.recordLag({
+            kind: "worktree-retained",
+            path: removal.path,
+            ...(removal.diagnostic === undefined ? {} : { diagnostic: removal.diagnostic }),
+        });
     }
 }
 async function reconcileTargetCheckouts(repository, state, onPhysical) {
@@ -288,7 +290,7 @@ async function reconcileWithTopology(input, state, topology) {
     const acc = reconcileAccumulation(input.onPhysical);
     const { effects, lag, hookRuns } = acc;
     try {
-        await removeCollectableScratch(repository, topology, acc);
+        await removeCollectableScratch(repository, topology, acc, state?.terminal ? state.id : undefined);
         if (!state)
             return complete(effects, lag);
         const targetCheckouts = await reconcileTargetCheckouts(repository, state, input.onPhysical);

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

@@ -7,7 +7,6 @@ export declare const CANDIDATE_PIN_REF_NAMESPACE = "refs/keiyaku/candidate";
 export declare const HANDOFF_RECEIPT_REF_NAMESPACE = "refs/keiyaku/handoff";
 export declare const GIT_FORMAT_PATH = "meta/format.json";
 export declare const GIT_FORMAT_BYTES = "{\"version\":4}\n";
-export declare const STATE_COMMIT_SUBJECT = "keiyaku authority - do not delete or rewrite";
 export declare function isKeiyakuOwnedRef(ref: string): boolean;
 export type GitOid = string;
 export type RefPublication = Readonly<{
@@ -31,7 +30,7 @@ export declare class NoGitWorldError extends Error {
     readonly path: string;
     constructor(path: string);
 }
-export type RegisteredWorktree = Readonly<{
+type RegisteredWorktree = Readonly<{
     path: string;
     branch: string | null;
 }>;
@@ -40,12 +39,9 @@ export declare function registeredWorktreePaths(repository: GitRepository): Prom
 export declare function repositoryAt(cwd: string, gitPath?: string): Promise<GitRepository>;
 export declare function commonGitDirectory(repository: GitRepository): string;
 export declare function worktreeGitDirectory(repository: GitRepository, worktree: string): Promise<string>;
-export declare function worktreeRoot(repository: GitRepository): Promise<string>;
 export declare function readRef(repository: GitRepository, ref: string): Promise<GitOid | null>;
 /** Read an explicit set of asserted refs from one fresh Git observation. */
 export declare function readRefs(repository: GitRepository, refs: readonly string[]): Promise<Map<any, any>>;
-export declare function readTreeEntries(repository: GitRepository, tree: GitOid): Promise<Map<string, TreeEntry>>;
-export declare function readGit(repository: GitRepository): Promise<GitSnapshot>;
 /** Read only the requested private Git paths from one immutable Git tree. */
 export declare function readGitPaths(repository: GitRepository, requestedPaths: readonly string[]): Promise<GitSnapshot>;
 export declare function writeBlob(repository: GitRepository, bytes: string | Uint8Array): Promise<GitOid>;
@@ -74,7 +70,7 @@ export declare function updateRefsAtomically(repository: GitRepository, updates:
     readonly newOid: GitOid;
     readonly expectedOid: GitOid;
 })[], assertions?: readonly GitRefAssertion[]): Promise<RefPublication>;
-export type GitDiffStat = Readonly<{
+type GitDiffStat = Readonly<{
     filesChanged: number;
     insertions: number;
     deletions: number;

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 {};