@astrosheep/keiyaku 4.0.3 → 4.0.5

package/build/src/core/verbs/placement.js

@@ -1,16 +1,34 @@
 import { gatesSatisfied } from "../facts/gate.js";
-import { activeContract, prerequisiteStatus } from "../facts/observation.js";
+import { activeContract, contractState } from "../facts/observation.js";
+function unmetPrerequisites(prerequisites, observation) {
+    const unmet = [];
+    for (const contractId of prerequisites) {
+        const state = contractState(observation, contractId);
+        if (state === null) {
+            unmet.push({ contractId, state: "missing" });
+        }
+        else if (state.terminal?.kind === "abandoned") {
+            unmet.push({ contractId, state: "abandoned" });
+        }
+        else if (state.terminal?.kind !== "claimed") {
+            unmet.push({ contractId, state: "active" });
+        }
+    }
+    return unmet;
+}
 export function decidePlacement({ input, attempt, observation }) {
     const id = input.contractId;
     const current = activeContract(observation, id);
     if ("kind" in current)
         return { kind: "refused", refusal: current };
     const delivery = current.delivery;
-    if (!delivery) {
+    const integration = current.currentIntegration;
+    if (!delivery || !integration) {
         return { kind: "refused", refusal: { kind: "delivery-missing", contractId: id } };
     }
-    if (prerequisiteStatus(current.terms.after, observation) !== "claimed") {
-        return { kind: "refused", refusal: { kind: "prerequisites-unsatisfied", contractId: id } };
+    const unmet = unmetPrerequisites(current.terms.after, observation);
+    if (unmet.length > 0) {
+        return { kind: "refused", refusal: { kind: "prerequisites-unsatisfied", contractId: id, unmet } };
     }
     if (!gatesSatisfied(current)) {
         return { kind: "refused", refusal: { kind: "gates-unsatisfied", contractId: id } };
@@ -31,8 +49,8 @@ export function decidePlacement({ input, attempt, observation }) {
             ...(current.coordinates.target === undefined ? {} : {
                 target: {
                     target: current.coordinates.target,
-                    expectedOid: delivery.data.integration.predecessor,
-                    newOid: delivery.data.integration.snapshot,
+                    expectedOid: integration.predecessor,
+                    newOid: integration.snapshot,
                 },
             }),
         },

package/build/src/core/verbs/reintegrate.d.ts

@@ -0,0 +1,13 @@
+import type { DecideInput, OfferDecision, Preparation } from "../decide.js";
+import type { ActorId, ContractId, ReintegratedData } from "../facts/types.js";
+export type ReintegrateInput<Failure = never> = Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+    preparation: Preparation<ReintegratedData, Failure>;
+}>;
+export type ReintegrateRefusal = Readonly<{
+    kind: "contract-missing" | "delivery-missing" | "terminal";
+    contractId: ContractId;
+}>;
+export declare function decideReintegrate<Failure>({ input, attempt, observation, }: DecideInput<ReintegrateInput<Failure>>): OfferDecision<ReintegrateRefusal | Failure>;

package/build/src/core/verbs/reintegrate.js

@@ -0,0 +1,24 @@
+import { activeContract } from "../facts/observation.js";
+export function decideReintegrate({ input, attempt, observation, }) {
+    const state = activeContract(observation, input.contractId);
+    if ("kind" in state)
+        return { kind: "refused", refusal: state };
+    if (state.delivery === null) {
+        return { kind: "refused", refusal: { kind: "delivery-missing", contractId: input.contractId } };
+    }
+    if (input.preparation.kind === "refused")
+        return { kind: "refused", refusal: input.preparation.refusal };
+    const reintegrated = {
+        v: 1,
+        kind: "reintegrated",
+        contract: input.contractId,
+        entry: attempt.entryUlids[0],
+        at: input.at,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        data: input.preparation.data,
+    };
+    return {
+        kind: "offer",
+        offer: { facts: [{ contractId: input.contractId, expectedHead: state.head, entries: [reintegrated] }] },
+    };
+}

package/build/src/dispatch/index.d.ts

@@ -1,6 +1,6 @@
 import { type ContractId } from "../core/facts/types.js";
 import { type AkuId } from "../akuma/identity.js";
-import { type GitRepository } from "../git/repository.js";
+import type { GitRepository } from "../git/process.js";
 import { type GitReadObservation } from "../git/read-observation.js";
 export type Dispatch = Readonly<{
     akuId: AkuId;

package/build/src/dispatch/index.js

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
+import { join } from "node:path";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { contractId } from "../core/facts/types.js";
 import { parseAkuId } from "../akuma/identity.js";
+import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
 import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, readBlob, readGitPaths, updateGitTree, updateRefsAtomically, writeBlob, writeCommit, } from "../git/repository.js";
 import { withGitDecodeChannel, withGitReadObservation } from "../git/read-observation.js";
 const DISPATCH_ROOT = "dispatch";
@@ -123,46 +125,55 @@ export async function publishDispatch(input) {
     const owner = contractId(input.contractId);
     const intended = { akuId, contractId: owner, dispatchedAt: new Date().toISOString() };
     const path = pathFor(akuId);
-    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
-        const snapshot = await readGitPaths(input.repository, [path]);
-        const current = await dispatchFromSnapshot(input.repository, snapshot, akuId);
-        if (current !== null) {
-            return current.contractId === owner
-                ? { kind: "dispatched", dispatch: current }
-                : { kind: "failed", failure: { kind: "conflict", current } };
-        }
-        const changes = new Map();
-        if (snapshot.commit === null) {
-            changes.set(GIT_FORMAT_PATH, { oid: await writeBlob(input.repository, GIT_FORMAT_BYTES) });
-        }
-        changes.set(path, { oid: await writeBlob(input.repository, bytesFor(intended)) });
-        const tree = await updateGitTree(input.repository, snapshot.tree, changes);
-        const commit = await writeCommit({
-            repository: input.repository,
-            tree,
-            parent: snapshot.commit,
-            message: `dispatch ${akuId}`,
-            at: intended.dispatchedAt,
-        });
-        const publication = await updateRefsAtomically(input.repository, [{
-                ref: GIT_REF,
-                newOid: commit,
-                expectedOid: snapshot.commit,
-            }]);
-        if (publication.kind === "published")
-            return { kind: "dispatched", dispatch: intended };
-        const observed = await observedPublication(input.repository, akuId, owner);
-        if (observed !== null)
-            return observed;
-        if (publication.kind === "non-published") {
-            const fresh = await readGitPaths(input.repository, [path]);
-            if (fresh.commit === snapshot.commit) {
-                return {
-                    kind: "failed",
-                    failure: { kind: "publication-failed", diagnostic: diagnostic(publication.error) },
-                };
+    const held = await acquireSqliteTransactionLock({
+        path: join(input.repository.commonDirectory, "keiyaku", "locks", "dispatch.sqlite"),
+        mode: "immediate",
+    });
+    try {
+        for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
+            const snapshot = await readGitPaths(input.repository, [path]);
+            const current = await dispatchFromSnapshot(input.repository, snapshot, akuId);
+            if (current !== null) {
+                return current.contractId === owner
+                    ? { kind: "dispatched", dispatch: current }
+                    : { kind: "failed", failure: { kind: "conflict", current } };
+            }
+            const changes = new Map();
+            if (snapshot.commit === null) {
+                changes.set(GIT_FORMAT_PATH, { oid: await writeBlob(input.repository, GIT_FORMAT_BYTES) });
+            }
+            changes.set(path, { oid: await writeBlob(input.repository, bytesFor(intended)) });
+            const tree = await updateGitTree(input.repository, snapshot.tree, changes);
+            const commit = await writeCommit({
+                repository: input.repository,
+                tree,
+                parent: snapshot.commit,
+                message: `dispatch ${akuId}`,
+                at: intended.dispatchedAt,
+            });
+            const publication = await updateRefsAtomically(input.repository, [{
+                    ref: GIT_REF,
+                    newOid: commit,
+                    expectedOid: snapshot.commit,
+                }]);
+            if (publication.kind === "published")
+                return { kind: "dispatched", dispatch: intended };
+            const observed = await observedPublication(input.repository, akuId, owner);
+            if (observed !== null)
+                return observed;
+            if (publication.kind === "non-published") {
+                const fresh = await readGitPaths(input.repository, [path]);
+                if (fresh.commit === snapshot.commit) {
+                    return {
+                        kind: "failed",
+                        failure: { kind: "publication-failed", diagnostic: diagnostic(publication.error) },
+                    };
+                }
             }
         }
+        return { kind: "failed", failure: { kind: "contention" } };
+    }
+    finally {
+        held.close();
     }
-    return { kind: "failed", failure: { kind: "contention" } };
 }

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

@@ -1,6 +1,7 @@
 import type { Offer } from "../core/facts/offer.js";
 import type { GitAdmissionSnapshot } from "./observe.js";
-import { type GitRepository, type GitRefAssertion } from "./repository.js";
+import { type GitRefAssertion } from "./repository.js";
+import type { GitRepository } from "./process.js";
 import { type ContractHead } from "../core/facts/types.js";
 type Accepted = Readonly<{
     kind: "accepted";

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

@@ -1,4 +1,3 @@
-import { type Settings } from "../settings.js";
 export type HookCommand = Readonly<{
     argv: readonly string[];
     timeoutMs: number;
@@ -29,9 +28,6 @@ export type WorktreeHookLag = Readonly<{
     failure: HookFailure;
 }>;
 type HookPhase = "create" | "destroy";
-export declare function worktreeHooksFrom(input: Readonly<{
-    settings: Settings;
-}>): WorktreeHooks;
 export declare function hookMarkerPath(administrationDirectory: string): string;
 export type HookCommandRun = Readonly<{
     kind: "ok";

package/build/src/git/hooks.js

@@ -4,46 +4,10 @@ import { fileURLToPath } from "node:url";
 import { replaceFileDurably } from "../coordination/durable-file.js";
 import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
 import { runProcess, runProcessToExit } from "../runtime/proc/run.js";
-import { SettingsError } from "../settings.js";
 const MARKER_VERSION = 1;
 function object(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-export function worktreeHooksFrom(input) {
-    if (!object(input))
-        throw new TypeError("worktreeHooksFrom input must be an object");
-    const view = input.settings.namespace("worktree");
-    if (view.kind === "failed") {
-        throw new SettingsError(view.failures.map((failure) => `${failure.scope}: ${failure.diagnostic}`).join("; "));
-    }
-    for (const entry of view.entries) {
-        if (entry.name !== "create" && entry.name !== "destroy")
-            throw new SettingsError(`worktree has unknown entry: ${entry.name}`);
-    }
-    const commands = (phase) => {
-        const selected = view.entries.find((entry) => entry.name === phase);
-        if (selected === undefined)
-            return Object.freeze([]);
-        if (!Array.isArray(selected.value))
-            throw new SettingsError(`worktree.${phase} must be an array`);
-        return Object.freeze(selected.value.map((item, index) => {
-            if (!object(item))
-                throw new SettingsError(`worktree.${phase}[${index}] must be an object`);
-            const coordinate = `worktree.${phase}[${index}]`;
-            exactKeys(item, ["argv", "timeoutMs"], coordinate);
-            if (!Array.isArray(item.argv) || item.argv.length === 0 || !item.argv.every((value) => typeof value === "string")) {
-                throw new SettingsError(`${coordinate}.argv must be a nonempty string array`);
-            }
-            if (item.argv[0].trim().length === 0)
-                throw new SettingsError(`${coordinate}.argv[0] must be nonblank`);
-            if (!Number.isSafeInteger(item.timeoutMs) || item.timeoutMs < 1 || item.timeoutMs > 2_147_483_647) {
-                throw new SettingsError(`${coordinate}.timeoutMs must be an integer from 1 through 2147483647`);
-            }
-            return Object.freeze({ argv: Object.freeze([...item.argv]), timeoutMs: item.timeoutMs });
-        }));
-    };
-    return Object.freeze({ create: commands("create"), destroy: commands("destroy") });
-}
 function exactKeys(value, keys, coordinate) {
     const actual = Object.keys(value).sort();
     const expected = [...keys].sort();

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

@@ -1,8 +1,9 @@
 import type { Preparation } from "../core/decide.js";
 import type { ChangeId, ContractCoordinates, ContractId, SnapshotId } from "../core/facts/types.js";
 import { type GitObjectId } from "./identity.js";
-import { type GitRepository } from "./repository.js";
-import type { TenderCapture } from "./tender.js";
+import { type GitRepository } from "./process.js";
+import type { DeliveryCommitMetadata, TenderCapture } from "./tender.js";
+type IntegrationTender = Pick<TenderCapture, "head" | "tree">;
 declare const REQUIRED_GIT: "2.38";
 export type IntegrationPreparationRefusal = Readonly<{
     kind: "integration-failed";
@@ -26,12 +27,10 @@ export type IntegrationPlan = Readonly<{
 /** Mint the one worktree-content identity shared by review and delivery. */
 export declare function worktreeChangeId(repository: GitRepository, input: IntegrationCoordinates, tender: TenderCapture): Promise<ChangeId>;
 /** Materialize the exact integration tree against its observed predecessor. */
-export declare function materializeIntegrationSnapshot(repository: GitRepository, tree: GitObjectId, parent: SnapshotId, input: Readonly<{
-    contractId: ContractId;
-    title: string;
-    message?: string;
-}>): Promise<SnapshotId>;
-export declare function planIntegration(repository: GitRepository, input: IntegrationCoordinates, tender: TenderCapture, requireBranchesToBeUpToDate: boolean): Promise<Preparation<IntegrationPlan, Readonly<{
+export declare function materializeIntegrationSnapshot(repository: GitRepository, tree: GitObjectId, parent: SnapshotId, metadata: DeliveryCommitMetadata): Promise<SnapshotId>;
+export declare function persistedTender(repository: GitRepository, snapshot: SnapshotId): Promise<IntegrationTender>;
+export declare function materializeReintegrationSnapshot(repository: GitRepository, tree: GitObjectId, parent: SnapshotId, template: SnapshotId): Promise<SnapshotId>;
+export declare function planIntegration(repository: GitRepository, input: IntegrationCoordinates, tender: IntegrationTender, requireBranchesToBeUpToDate: boolean): Promise<Preparation<IntegrationPlan, Readonly<{
     kind: "target-missing";
     contractId: ContractId;
 }> | IntegrationPreparationRefusal>>;

package/build/src/git/integration.js

@@ -1,6 +1,7 @@
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { gitObjectId, gitObjectIdForSnapshot, mintChangeId, mintSnapshotId } from "./identity.js";
-import { decodeGitNameOnly, decodeGitNumstat, GitPlumbingError, readRef, runGit, runGitWithEnvironment, } from "./repository.js";
+import { decodeGitNameOnly, decodeGitNumstat, readRef, } from "./repository.js";
+import { GitPlumbingError, runGit, runGitWithEnvironment, } from "./process.js";
 const REQUIRED_GIT = "2.38";
 async function runAllowingNonzero(repository, args, input) {
     try {
@@ -44,14 +45,66 @@ export async function worktreeChangeId(repository, input, tender) {
     return mintChangeId(id === "" ? "0000000000000000000000000000000000000000" : id);
 }
 /** Materialize the exact integration tree against its observed predecessor. */
-export async function materializeIntegrationSnapshot(repository, tree, parent, input) {
-    const commit = (await runGitWithEnvironment(repository, ["commit-tree", tree, "-p", gitObjectIdForSnapshot(parent)], `${input.message ?? `${input.contractId}: ${input.title}`}\n\nKeiyaku-Contract: ${input.contractId}\n`, {
-        GIT_AUTHOR_NAME: "Keiyaku",
-        GIT_AUTHOR_EMAIL: "keiyaku@localhost",
-        GIT_COMMITTER_NAME: "Keiyaku",
-        GIT_COMMITTER_EMAIL: "keiyaku@localhost",
-        GIT_AUTHOR_DATE: "Thu, 01 Jan 1970 00:00:00 +0000",
-        GIT_COMMITTER_DATE: "Thu, 01 Jan 1970 00:00:00 +0000",
+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);
+}
+export async function persistedTender(repository, snapshot) {
+    const tree = (await runGit(repository, ["show", "-s", "--format=%T", gitObjectIdForSnapshot(snapshot)]))
+        .toString("ascii")
+        .trim();
+    return { head: snapshot, tree: gitObjectId(tree, "persisted tender tree") };
+}
+export async function materializeReintegrationSnapshot(repository, tree, parent, template) {
+    const templateObject = gitObjectIdForSnapshot(template);
+    let raw;
+    try {
+        raw = await runGit(repository, ["cat-file", "commit", templateObject]);
+    }
+    catch (error) {
+        if (error instanceof GitPlumbingError) {
+            throw new AuthorityCorruptionError(`recorded delivery snapshot cannot be read: ${template}`);
+        }
+        throw error;
+    }
+    const separator = raw.indexOf(Buffer.from("\n\n"));
+    if (separator < 0)
+        throw new AuthorityCorruptionError(`recorded delivery snapshot has no commit message: ${template}`);
+    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,
+        ])).toString("utf8").replace(/\n$/u, "");
+        fields = formatted.split("\0");
+    }
+    catch (error) {
+        if (error instanceof GitPlumbingError) {
+            throw new AuthorityCorruptionError(`recorded delivery snapshot metadata cannot be read: ${template}`);
+        }
+        throw error;
+    }
+    if (fields.length !== 6 || fields.some((field) => field.length === 0)) {
+        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, {
+        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);
 }

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

@@ -1,6 +1,7 @@
 import { type ContractId, type ContractState, type JournalEntry, type SnapshotId } from "../core/facts/types.js";
 import type { ContractsObservation } from "../core/facts/observation.js";
-import { type GitSnapshot, type GitOid, type GitRepository } from "./repository.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<{
     head: SnapshotId | null;

package/build/src/git/observe.js

@@ -2,7 +2,8 @@ import { decodeJournal } from "../core/facts/codec.js";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { foldJournal } from "../core/facts/fold.js";
 import { contractJournalPath, contractJournalPaths, mintContractHead, mintSnapshotId, } from "./identity.js";
-import { GitPlumbingError, isKeiyakuOwnedRef, runGit, } from "./repository.js";
+import { isKeiyakuOwnedRef, } from "./repository.js";
+import { GitPlumbingError, runGit } from "./process.js";
 import { readGitTreeSelection, withGitTargetedReadObservation, } from "./read-observation.js";
 export async function observeDeliveryTargetAt(observation, state) {
     const target = state.coordinates.target;
@@ -10,12 +11,12 @@ export async function observeDeliveryTargetAt(observation, state) {
         return null;
     const value = await observation.resolveRef(target);
     const head = value === null ? null : mintSnapshotId(value);
-    const delivery = state.delivery?.data;
-    if (delivery === undefined)
+    const integration = state.currentIntegration;
+    if (integration === null)
         return { head, drift: false };
     const expected = state.terminal?.kind === "claimed"
-        ? delivery.integration.snapshot
-        : delivery.integration.predecessor;
+        ? integration.snapshot
+        : integration.predecessor;
     return { head, drift: head !== expected };
 }
 const TARGET_COORDINATES_FORMAT = "%(refname)%00%(objectname)%00";

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

@@ -0,0 +1,26 @@
+export type GitRepository = Readonly<{
+    /** The executable selected when this repository capability is created. */
+    readonly gitPath: string;
+    /** The invocation's effective working directory, including a caller -C worktree. */
+    readonly effectiveCwd: string;
+    /** The canonical primary worktree root for this repository. */
+    readonly primaryWorktree: string;
+    /** The canonical common Git directory pinned when this capability is created. */
+    readonly commonDirectory: string;
+}>;
+export declare class GitPlumbingError extends Error {
+    readonly stdout: Buffer;
+    readonly stderr: Buffer;
+    readonly status: number | null;
+    readonly pid: number | null;
+    constructor(input: Readonly<{
+        stdout?: string | Uint8Array;
+        stderr: string | Uint8Array;
+        status: number | null;
+        message: string;
+        pid?: number | null;
+    }>);
+}
+export declare function runGit(repository: GitRepository, args: readonly string[], input?: string | Uint8Array): 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

@@ -0,0 +1,94 @@
+import { spawn } from "node:child_process";
+import { consumeProcessStdout } from "../runtime/proc/run.js";
+export class GitPlumbingError extends Error {
+    stdout;
+    stderr;
+    status;
+    pid;
+    constructor(input) {
+        super(input.message);
+        this.name = "GitPlumbingError";
+        this.stdout = Buffer.from(input.stdout ?? "");
+        this.stderr = Buffer.from(input.stderr);
+        this.status = input.status;
+        this.pid = input.pid ?? null;
+    }
+}
+const GIT_STDERR_BYTES = 16 * 1024;
+function commandError(command, error) {
+    const candidate = error;
+    const stderr = candidate.stderr === undefined ? Buffer.alloc(0) : Buffer.from(candidate.stderr);
+    const stdout = candidate.stdout === undefined ? Buffer.alloc(0) : Buffer.from(candidate.stdout);
+    const detail = stderr.length === 0 ? candidate.message ?? "git command failed" : stderr.toString("utf8");
+    return new GitPlumbingError({
+        stdout,
+        stderr,
+        status: candidate.status ?? null,
+        message: `${command.join(" ")}: ${detail}`,
+        pid: candidate.pid ?? null,
+    });
+}
+async function executeGit(repository, args, input, environment) {
+    const stdout = [];
+    const stderr = [];
+    let stderrBytes = 0;
+    let inputError;
+    const child = spawn(repository.gitPath, [...args], {
+        cwd: repository.effectiveCwd,
+        ...(environment === undefined ? {} : { env: { ...process.env, ...environment } }),
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => {
+        if (stderrBytes >= GIT_STDERR_BYTES)
+            return;
+        const retained = chunk.subarray(0, GIT_STDERR_BYTES - stderrBytes);
+        stderr.push(retained);
+        stderrBytes += retained.length;
+    });
+    child.stdin.on("error", (error) => { inputError = error; });
+    child.stdin.end(input);
+    const terminal = await new Promise((resolveTerminal) => {
+        child.once("error", (error) => resolveTerminal({ code: null, error }));
+        child.once("close", (code) => resolveTerminal({ code }));
+    });
+    const output = Buffer.concat(stdout);
+    if (terminal.code === 0 && inputError === undefined)
+        return output;
+    throw commandError(args, {
+        message: terminal.error?.message ?? inputError?.message ?? `git exited with status ${terminal.code ?? "unknown"}`,
+        stdout: output,
+        stderr: Buffer.concat(stderr),
+        status: terminal.code,
+        pid: child.pid,
+    });
+}
+export async function runGit(repository, args, input) {
+    return await executeGit(repository, args, input);
+}
+export async function consumeGitStdout(repository, args, consume) {
+    const result = await consumeProcessStdout({
+        argv: [repository.gitPath, ...args],
+        cwd: repository.effectiveCwd,
+    }, consume);
+    const { outcome } = result;
+    if (outcome.kind === "terminal" && outcome.code === 0)
+        return;
+    const status = outcome.kind === "terminal" ? outcome.code : null;
+    const stderr = outcome.kind === "terminal" ? outcome.stderr : "";
+    const message = outcome.kind === "terminal"
+        ? `git exited with status ${outcome.code}`
+        : outcome.kind === "spawn-error" || outcome.kind === "stream-error"
+            ? outcome.diagnostic
+            : `git process ended with ${outcome.kind}`;
+    throw commandError(args, {
+        message,
+        stderr,
+        status,
+        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.d.ts

@@ -1,5 +1,6 @@
 import { type TreeEntry } from "./tree.js";
-import { type GitOid, type GitRepository, type GitSnapshot } from "./repository.js";
+import { type GitOid, type GitSnapshot } from "./repository.js";
+import { type GitRepository } from "./process.js";
 declare const gitReadObservationBrand: unique symbol;
 declare const gitDecodeChannelBrand: unique symbol;
 export type GitBlobResult = Readonly<{

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

@@ -2,7 +2,8 @@ import { spawn } from "node:child_process";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { gitObjectId } from "./identity.js";
 import { parseTreeObject, validPath } from "./tree.js";
-import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, GitPlumbingError, readRef, } from "./repository.js";
+import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, readRef, } from "./repository.js";
+import { GitPlumbingError } from "./process.js";
 const gitReadObservationBrand = Symbol("GitReadObservation");
 const gitDecodeChannelBrand = Symbol("GitDecodeChannel");
 function streamCursor(stream) {
@@ -36,7 +37,7 @@ function streamCursor(stream) {
     return { line, exact };
 }
 function batchObjectReader(repository) {
-    const child = spawn("git", ["cat-file", "--batch"], {
+    const child = spawn(repository.gitPath, ["cat-file", "--batch"], {
         cwd: repository.effectiveCwd,
         stdio: ["pipe", "pipe", "pipe"],
         windowsHide: true,

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

@@ -1,5 +1,6 @@
-import { type GitOid, type GitRepository } from "./repository.js";
-import type { ContractId, ContractState } from "../core/facts/types.js";
+import { type GitOid } from "./repository.js";
+import { type GitRepository } from "./process.js";
+import type { ContractId, ContractState, SnapshotId } from "../core/facts/types.js";
 import type { GitDecodeChannel } from "./read-observation.js";
 import { type TargetCheckoutEffect, type TargetCheckoutLag } from "./target-placement.js";
 import { type WorktreeHookLag, type WorktreeHooks } from "./hooks.js";
@@ -8,6 +9,11 @@ export type Effect = Readonly<{
     kind: "worktree";
     path: string;
     action: "created" | "removed" | "unchanged";
+}> | Readonly<{
+    kind: "recovery-snapshot";
+    action: "created";
+    snapshot: SnapshotId;
+    retention: "ephemeral";
 }> | TargetCheckoutEffect | Readonly<{
     kind: "ref";
     name: string;