@astrosheep/keiyaku 4.0.0 → 4.0.2

package/build/src/git/reconcile.js

@@ -1,33 +1,68 @@
-import { existsSync, mkdirSync, realpathSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { access, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
-import { CANDIDATE_PIN_REF_NAMESPACE, commonGitDirectory, DELIVERY_REF_NAMESPACE, readRef, registeredWorktreePaths, runGit, worktreeGitDirectory, } from "./repository.js";
-import { contractId } from "../core/facts/types.js";
-import { contractLocator, gitObjectIdForSnapshot } from "./identity.js";
-import { observeContract } from "./observe.js";
+import { CANDIDATE_PIN_REF_NAMESPACE, commonGitDirectory, DELIVERY_REF_NAMESPACE, GitPlumbingError, isKeiyakuOwnedRef, readRef, registeredWorktreePaths, runGit, worktreeGitDirectory, } from "./repository.js";
+import { contractLocator, contractPhysicalName, gitObjectIdForSnapshot, mintSnapshotId, } from "./identity.js";
+import { observeContractAt } from "./observe.js";
+import { acquireTargetPlacementFence, recoverTargetPlacement, } from "./target-placement.js";
 import { runCreateHooks, runDestroyHooks, } from "./hooks.js";
-const WORKTREE_DIRECTORY = [".keiyaku-v4", "worktrees"];
-function materializedName(contract) { return contractId(contract).replace("/", "-"); }
-function deliveryRefFor(contract) { return `${DELIVERY_REF_NAMESPACE}/${materializedName(contract)}`; }
-function candidatePinRefFor(contract) { return `${CANDIDATE_PIN_REF_NAMESPACE}/${materializedName(contract)}`; }
-export function deliveryWorktreePath(repository, contract) { return resolve(realpathSync(repository.primaryWorktree), ...WORKTREE_DIRECTORY, materializedName(contract)); }
-function updateRef(repository, ref, desired) {
-    const before = readRef(repository, ref);
+import { worktreePath } from "./workspace.js";
+import { collectableScratchWorktrees } from "./scratch.js";
+import { terminalSealExpectations as decodeTerminalSealExpectations, terminalSealSnapshots, unsealedBytes, } from "./terminal-seal.js";
+const pathExists = (path) => access(path).then(() => true, () => false);
+function deliveryRefFor(contract) {
+    return `${DELIVERY_REF_NAMESPACE}/${contractPhysicalName(contract)}`;
+}
+function candidatePinRefFor(contract) {
+    return `${CANDIDATE_PIN_REF_NAMESPACE}/${contractPhysicalName(contract)}`;
+}
+function missingPlaceLag(repository) {
+    return {
+        kind: "reconcile-failed",
+        stage: "effect",
+        diagnostic: `managed Contract is unappointed: ${join(repository.commonDirectory, "keiyaku", "places.json")}`,
+    };
+}
+async function updateRef(repository, ref, desired) {
+    const before = await readRef(repository, ref);
     if (before === desired)
         return { kind: "ref", name: ref, action: "unchanged", before, after: desired };
-    runGit(repository, ["update-ref", "--no-deref", ref, gitObjectIdForSnapshot(desired), before ?? "0".repeat(desired.length)]);
+    await runGit(repository, [
+        "update-ref",
+        "--no-deref",
+        ref,
+        gitObjectIdForSnapshot(desired),
+        before ?? "0".repeat(desired.length),
+    ]);
     return { kind: "ref", name: ref, action: before === null ? "created" : "updated", before, after: desired };
 }
-function removeRef(repository, ref) {
-    const before = readRef(repository, ref);
+async function removeRef(repository, ref) {
+    const before = await readRef(repository, ref);
     if (before === null)
         return { kind: "ref", name: ref, action: "unchanged", before: null, after: null };
-    runGit(repository, ["update-ref", "--no-deref", "-d", ref, before]);
+    await runGit(repository, ["update-ref", "--no-deref", "-d", ref, before]);
+    return { kind: "ref", name: ref, action: "removed", before, after: null };
+}
+async function removeRefWithCustody(repository, ref, custodian, expectedCustodian) {
+    const before = await readRef(repository, ref);
+    if (before === null)
+        return { kind: "ref", name: ref, action: "unchanged", before: null, after: null };
+    if (await readRef(repository, custodian) !== expectedCustodian) {
+        return { kind: "ref", name: ref, action: "unchanged", before, after: before };
+    }
+    await runGit(repository, ["update-ref", "--stdin", "--no-deref"], [
+        "start",
+        `verify ${custodian} ${gitObjectIdForSnapshot(expectedCustodian)}`,
+        `delete ${ref} ${before}`,
+        "prepare",
+        "commit",
+        "",
+    ].join("\n"));
     return { kind: "ref", name: ref, action: "removed", before, after: null };
 }
-function acquireWorktreeTopology(repository) {
-    return { paths: new Set(registeredWorktreePaths(repository)) };
+async function acquireWorktreeTopology(repository) {
+    return { paths: new Set(await registeredWorktreePaths(repository)) };
 }
 function fromPrimaryWorktree(repository) {
     return { ...repository, effectiveCwd: repository.primaryWorktree };
@@ -47,44 +82,36 @@ function reconcileLockPath(repository, contract) {
     const locator = contractLocator(contract);
     return join(commonGitDirectory(repository), "keiyaku", "locks", "reconcile", locator.slice(0, 2), `${locator.slice(2)}.sqlite`);
 }
-function worktree(repository, topology, path, desired) {
+async function worktree(repository, topology, path, desired) {
     const registered = topology.paths.has(path);
-    if (registered && existsSync(path))
+    if (registered && await pathExists(path))
         return { kind: "worktree", path, action: "unchanged" };
     if (registered) {
-        runGit(repository, ["worktree", "remove", path]);
+        await runGit(repository, ["worktree", "remove", path]);
         topology.paths.delete(path);
     }
-    if (existsSync(path))
+    if (await pathExists(path))
         throw new Error(`delivery worktree path is occupied: ${path}`);
-    mkdirSync(dirname(path), { recursive: true });
-    runGit(repository, ["worktree", "add", "--detach", path, gitObjectIdForSnapshot(desired)]);
+    await mkdir(dirname(path), { recursive: true });
+    await runGit(repository, ["worktree", "add", "--detach", path, gitObjectIdForSnapshot(desired)]);
     topology.paths.add(path);
     return { kind: "worktree", path, action: "created" };
 }
-function canRemoveWorktree(repository, path, expected) {
-    if (runGit(repository, ["-C", path, "status", "--porcelain", "--untracked-files=all"]).length !== 0)
-        return false;
-    const [head, headTree] = runGit(repository, ["-C", path, "rev-parse", "HEAD", "HEAD^{tree}"])
-        .toString("utf8").trim().split("\n");
-    const matched = expected.find((snapshot) => head === gitObjectIdForSnapshot(snapshot));
-    if (matched === undefined)
-        return false;
-    const expectedTree = runGit(repository, ["-C", path, "rev-parse", `${gitObjectIdForSnapshot(matched)}^{tree}`])
-        .toString("utf8").trim();
-    return headTree === expectedTree;
-}
-function removeWorktree(repository, topology, path) {
+async function removeWorktree(repository, topology, path, force = false) {
     const registered = topology.paths.has(path);
-    if (!registered)
-        return { effect: { kind: "worktree", path, action: "unchanged" }, retained: false };
-    if (!existsSync(path)) {
-        runGit(repository, ["worktree", "remove", path]);
+    if (!registered) {
+        return {
+            effect: { kind: "worktree", path, action: "unchanged" },
+            retained: await pathExists(path),
+        };
+    }
+    if (!await pathExists(path)) {
+        await runGit(repository, ["worktree", "remove", path]);
         topology.paths.delete(path);
         return { effect: { kind: "worktree", path, action: "removed" }, retained: false };
     }
     try {
-        runGit(repository, ["worktree", "remove", path]);
+        await runGit(repository, ["worktree", "remove", ...(force ? ["--force"] : []), path]);
     }
     catch {
         return { effect: { kind: "worktree", path, action: "unchanged" }, retained: true };
@@ -92,68 +119,233 @@ function removeWorktree(repository, topology, path) {
     topology.paths.delete(path);
     return { effect: { kind: "worktree", path, action: "removed" }, retained: false };
 }
-async function reconcileWithTopology({ repository, hooks, retryHooks }, state, topology) {
+async function removeCollectableScratch(repository, topology, effects, lag) {
+    for (const scratch of await collectableScratchWorktrees(topology.paths)) {
+        try {
+            const removal = await removeWorktree(repository, topology, scratch.path, true);
+            effects.push(removal.effect);
+            if (removal.retained)
+                lag.push({ kind: "worktree-retained", path: scratch.path });
+        }
+        finally {
+            scratch.release();
+        }
+    }
+}
+async function refRows(repository) {
+    const output = (await runGit(repository, [
+        "for-each-ref",
+        "--format=%(refname)%00%(objectname)",
+    ])).toString("utf8");
+    if (output.length === 0)
+        return [];
+    return output.trimEnd().split("\n").map((row) => {
+        const [ref, oid, extra] = row.split("\0");
+        if (ref === undefined || oid === undefined || extra !== undefined)
+            throw new Error("Git ref row is malformed");
+        return { ref, oid };
+    });
+}
+async function snapshotCustodian(repository, snapshot) {
+    for (const row of await refRows(repository)) {
+        if (isKeiyakuOwnedRef(row.ref))
+            continue;
+        try {
+            await runGit(repository, ["merge-base", "--is-ancestor", gitObjectIdForSnapshot(snapshot), row.oid]);
+            return { ref: row.ref, oid: mintSnapshotId(row.oid) };
+        }
+        catch (error) {
+            if (error instanceof GitPlumbingError && error.status === 1)
+                continue;
+            throw error;
+        }
+    }
+    return null;
+}
+async function reconcileTargetCheckouts(repository, state) {
+    if (state.terminal?.kind !== "claimed" || state.coordinates.target === undefined || state.delivery === null) {
+        return complete();
+    }
+    let held;
+    try {
+        held = await acquireTargetPlacementFence(repository, state.coordinates.target);
+    }
+    catch (error) {
+        return failed("effect", error);
+    }
+    let result;
+    let exceptional;
+    try {
+        const recovered = await recoverTargetPlacement(repository, state);
+        result = complete(recovered.effects, recovered.lag);
+    }
+    catch (error) {
+        if (error instanceof AuthorityCorruptionError || error instanceof TypeError)
+            exceptional = error;
+        else
+            result = failed("effect", error);
+    }
+    let releaseFailure;
+    try {
+        held.close();
+    }
+    catch (error) {
+        releaseFailure = error;
+    }
+    if (exceptional !== undefined)
+        throw exceptional;
+    if (result === undefined)
+        throw new Error("target checkout reconcile produced no result");
+    if (releaseFailure !== undefined)
+        result = failed("effect", releaseFailure, result.effects, result.lag);
+    return result;
+}
+async function reconcileHereWorkspaceRefs({ repository }, state, { effects, lag }) {
+    const pin = candidatePinRefFor(state.id);
+    if (state.terminal) {
+        if (state.delivery === null)
+            effects.push(await removeRef(repository, pin));
+        else {
+            const integration = state.delivery.data.integration.snapshot;
+            const custodian = await snapshotCustodian(repository, integration);
+            effects.push(await (custodian === null
+                ? await updateRef(repository, pin, integration)
+                : await removeRefWithCustody(repository, pin, custodian.ref, custodian.oid)));
+        }
+    }
+    else if (state.bound) {
+        effects.push(await (state.delivery === null
+            ? await removeRef(repository, pin)
+            : await updateRef(repository, pin, state.delivery.data.integration.snapshot)));
+    }
+    return complete(effects, lag);
+}
+function retainTerminalWorktree(path, retainedLag, { effects, lag }) {
+    effects.push({ kind: "worktree", path, action: "unchanged" });
+    lag.push(retainedLag);
+    return complete(effects, lag);
+}
+async function terminalSealExpectations(channel, state) {
+    const snapshots = terminalSealSnapshots(state);
+    const objects = await channel.readObjects(snapshots.map(gitObjectIdForSnapshot));
+    return decodeTerminalSealExpectations(state, objects);
+}
+async function removeSealedTerminalWorktree({ repository, topology, path, expected, hooks, retryHooks, acc }) {
+    if (topology.paths.has(path) && await pathExists(path)) {
+        const beforeHooks = await unsealedBytes(repository, path, expected);
+        if (beforeHooks !== null)
+            return retainTerminalWorktree(path, beforeHooks, acc);
+        const hookLag = await runDestroyHooks(path, await worktreeGitDirectory(repository, path), hooks, retryHooks);
+        if (hookLag !== null)
+            return retainTerminalWorktree(path, hookLag, acc);
+        const afterHooks = await unsealedBytes(repository, path, expected);
+        if (afterHooks !== null)
+            return retainTerminalWorktree(path, afterHooks, acc);
+    }
+    const removal = await removeWorktree(repository, topology, path, true);
+    if (removal.retained)
+        return retainTerminalWorktree(path, { kind: "worktree-retained", path }, acc);
+    acc.effects.push(removal.effect);
+    return null;
+}
+async function targetCustodyForClaimedIntegration(repository, state, integration) {
+    return state.terminal?.kind === "claimed" && state.coordinates.target !== undefined
+        && await readRef(repository, state.coordinates.target) === integration
+        ? { ref: state.coordinates.target, oid: integration }
+        : null;
+}
+function sealedTree(expected, snapshot) {
+    const tree = expected.treeBySnapshot.get(snapshot);
+    if (tree === undefined)
+        throw new Error(`terminal seal tree was not resolved: ${snapshot}`);
+    return tree;
+}
+async function releaseTerminalCustody({ repository, state, expected, ref, pin, acc: { effects } }) {
+    if (state.delivery === null) {
+        const custodian = await snapshotCustodian(repository, state.coordinates.start);
+        if (custodian !== null)
+            effects.push(await removeRefWithCustody(repository, ref, custodian.ref, custodian.oid));
+        effects.push(await removeRef(repository, pin));
+        return;
+    }
+    const tender = state.delivery.data.tenderSnapshot;
+    const integration = state.delivery.data.integration.snapshot;
+    const target = await targetCustodyForClaimedIntegration(repository, state, integration);
+    if (sealedTree(expected, tender) === sealedTree(expected, integration) && target !== null) {
+        effects.push(await removeRefWithCustody(repository, ref, target.ref, target.oid));
+        effects.push(await removeRefWithCustody(repository, pin, target.ref, target.oid));
+    }
+    else if (tender === integration) {
+        effects.push(await removeRefWithCustody(repository, pin, ref, tender));
+    }
+    else if (target !== null) {
+        effects.push(await removeRefWithCustody(repository, pin, target.ref, target.oid));
+    }
+}
+async function reconcileTerminalManagedWorktree({ repository, channel, hooks, retryHooks, retainTerminalWorktree, place }, state, topology, acc) {
+    const primary = fromPrimaryWorktree(repository);
+    const ref = deliveryRefFor(state.id);
+    const pin = candidatePinRefFor(state.id);
+    const path = place === undefined ? undefined : worktreePath(repository, place);
+    if (path === undefined)
+        return complete(acc.effects, acc.lag);
+    const expected = await terminalSealExpectations(channel, state);
+    acc.effects.push(await updateRef(primary, ref, state.delivery?.data.tenderSnapshot ?? state.coordinates.start));
+    if (state.delivery !== null) {
+        acc.effects.push(await updateRef(primary, pin, state.delivery.data.integration.snapshot));
+    }
+    if (retainTerminalWorktree === true)
+        return complete(acc.effects, acc.lag);
+    const retained = await removeSealedTerminalWorktree({
+        repository: primary,
+        topology,
+        path,
+        expected,
+        hooks,
+        retryHooks,
+        acc,
+    });
+    if (retained !== null)
+        return retained;
+    await releaseTerminalCustody({ repository: primary, state, expected, ref, pin, acc });
+    return complete(acc.effects, acc.lag);
+}
+async function reconcileActiveManagedWorktree({ repository, hooks, retryHooks, place }, state, topology, { effects, lag }) {
+    if (place === undefined)
+        return complete(effects, [...lag, missingPlaceLag(repository)]);
+    const path = worktreePath(repository, place);
+    const desired = state.delivery?.data.tenderSnapshot ?? state.coordinates.start;
+    effects.push(await updateRef(repository, deliveryRefFor(state.id), desired));
+    effects.push(await worktree(repository, topology, path, desired));
+    const hookLag = await runCreateHooks(path, await worktreeGitDirectory(repository, path), hooks, retryHooks);
+    if (hookLag !== null)
+        lag.push(hookLag);
+    effects.push(await (state.delivery
+        ? await updateRef(repository, candidatePinRefFor(state.id), state.delivery.data.integration.snapshot)
+        : await removeRef(repository, candidatePinRefFor(state.id))));
+    return complete(effects, lag);
+}
+async function reconcileWithTopology(input, state, topology) {
+    const { repository } = input;
     const effects = [];
     const lag = [];
     try {
+        await removeCollectableScratch(repository, topology, effects, lag);
         if (!state)
             return complete(effects, lag);
-        const ref = deliveryRefFor(state.id), pin = candidatePinRefFor(state.id), path = deliveryWorktreePath(repository, state.id);
-        if (state.coordinates.workspace === "here") {
-            if (state.terminal)
-                effects.push(removeRef(repository, pin));
-            else if (state.bound)
-                effects.push(state.delivery === null
-                    ? removeRef(repository, pin)
-                    : updateRef(repository, pin, state.delivery.data.candidate));
-            return complete(effects, lag);
-        }
-        if (state.terminal) {
-            const expected = state.delivery === null
-                ? [state.coordinates.start]
-                : [state.delivery.data.candidate, state.coordinates.start];
-            const primary = fromPrimaryWorktree(repository);
-            const retain = (retainedLag) => {
-                effects.push(updateRef(primary, ref, state.delivery?.data.candidate ?? state.coordinates.start));
-                effects.push(state.delivery === null ? removeRef(primary, pin) : updateRef(primary, pin, state.delivery.data.candidate));
-                effects.push({ kind: "worktree", path, action: "unchanged" });
-                lag.push(retainedLag);
-                return complete(effects, lag);
-            };
-            const registered = topology.paths.has(path);
-            if (registered && existsSync(path)) {
-                if (!canRemoveWorktree(primary, path, expected))
-                    return retain({ kind: "worktree-retained", path });
-                const hookLag = await runDestroyHooks(path, worktreeGitDirectory(primary, path), hooks, retryHooks);
-                if (hookLag !== null)
-                    return retain(hookLag);
-            }
-            const removal = removeWorktree(primary, topology, path);
-            if (removal.retained)
-                return retain({ kind: "worktree-retained", path });
-            effects.push(removal.effect);
-            effects.push(removeRef(primary, ref));
-            effects.push(removeRef(primary, pin));
-            return complete(effects, lag);
-        }
-        if (!state.bound)
-            return complete(effects, lag);
-        const desired = state.delivery?.data.candidate ?? state.coordinates.start;
-        effects.push(updateRef(repository, ref, desired));
-        effects.push(worktree(repository, topology, path, desired));
-        const hookLag = await runCreateHooks(path, worktreeGitDirectory(repository, path), hooks, retryHooks);
-        if (hookLag !== null)
-            lag.push(hookLag);
-        effects.push(state.delivery ? updateRef(repository, pin, state.delivery.data.candidate) : removeRef(repository, pin));
-        return complete(effects, lag);
+        const targetCheckouts = await reconcileTargetCheckouts(repository, state);
+        effects.push(...targetCheckouts.effects);
+        lag.push(...targetCheckouts.lag);
+        if (state.coordinates.workspace === "here")
+            return await reconcileHereWorkspaceRefs(input, state, { effects, lag });
+        if (state.terminal)
+            return await reconcileTerminalManagedWorktree(input, state, topology, { effects, lag });
+        return await reconcileActiveManagedWorktree(input, state, topology, { effects, lag });
     }
     catch (error) {
         return failed("effect", error, effects, lag);
     }
 }
-function needsWorktreeTopology(state) {
-    return state !== null && state.coordinates.workspace === "worktree" && (state.terminal !== null || state.bound !== null);
-}
 function releaseFailure(held, observation) {
     try {
         held.close();
@@ -181,10 +373,8 @@ export async function reconcile(input) {
     let observation;
     let exceptional;
     try {
-        const state = observeContract(input.repository, input.contractId).state;
-        const topology = needsWorktreeTopology(state)
-            ? acquireWorktreeTopology(input.repository)
-            : { paths: new Set() };
+        const state = (await observeContractAt(input.repository, input.channel, input.contractId)).state;
+        const topology = await acquireWorktreeTopology(input.repository);
         observation = {
             state,
             result: await reconcileWithTopology(input, state, topology),
@@ -206,18 +396,24 @@ export async function reconcile(input) {
 export function reconcileObservationFailure(error) {
     return failed("observation", error);
 }
-async function reconcileBatchItem(repository, contract, hooks, retryHooks) {
-    const observation = await reconcile({ repository, contractId: contract, hooks, retryHooks });
-    return {
-        contract,
-        state: observation.state,
-        result: observation.result,
-    };
+export function reconcileEffectFailure(error, prior) {
+    return failed("effect", error, prior?.effects, prior?.lag);
 }
 /** Reconcile each discovered Contract through its own serialized, fresh observation. */
-export async function reconcileBatch(repository, contracts, hooks, retryHooks) {
+export async function reconcileBatch(repository, channel, contracts, options) {
     const items = [];
-    for (const contract of contracts)
-        items.push(await reconcileBatchItem(repository, contract, hooks, retryHooks));
+    for (const contract of contracts) {
+        const place = options.places?.get(contract);
+        const observation = await reconcile({
+            repository,
+            channel,
+            contractId: contract,
+            hooks: options.hooks,
+            retryHooks: options.retryHooks,
+            retainTerminalWorktree: options.retainTerminalWorktree,
+            ...(place === undefined ? {} : { place }),
+        });
+        items.push({ contract, state: observation.state, result: observation.result });
+    }
     return items;
 }

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

@@ -4,7 +4,7 @@ export declare const GIT_REF = "refs/heads/keiyaku-state";
 export declare const DELIVERY_REF_NAMESPACE = "refs/heads/keiyaku-delivery";
 export declare const CANDIDATE_PIN_REF_NAMESPACE = "refs/heads/keiyaku-candidate";
 export declare const GIT_FORMAT_PATH = "meta/format.json";
-export declare const GIT_FORMAT_BYTES = "{\"version\":3}\n";
+export declare const GIT_FORMAT_BYTES = "{\"version\":4}\n";
 export declare function isKeiyakuOwnedRef(ref: string): boolean;
 export type GitOid = string;
 export type RefPublication = Readonly<{
@@ -15,11 +15,17 @@ export type RefPublication = Readonly<{
 }> | Readonly<{
     readonly kind: "unknown";
 }>;
+export type GitRefAssertion = Readonly<{
+    readonly ref: string;
+    readonly oid: GitOid;
+}>;
 export type GitRepository = Readonly<{
     /** 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 type GitSnapshot = Readonly<{
     readonly commit: GitOid | null;
@@ -31,36 +37,46 @@ export declare class NoGitWorldError extends Error {
     constructor(path: 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 registeredWorktreePaths(repository: GitRepository): readonly string[];
-export declare function repositoryAt(cwd: string): GitRepository;
+export type RegisteredWorktree = Readonly<{
+    path: string;
+    branch: string | null;
+}>;
+export declare function registeredWorktrees(repository: GitRepository): Promise<readonly RegisteredWorktree[]>;
+export declare function registeredWorktreePaths(repository: GitRepository): Promise<readonly string[]>;
+export declare function repositoryAt(cwd: string): Promise<GitRepository>;
 export declare function commonGitDirectory(repository: GitRepository): string;
-export declare function worktreeGitDirectory(repository: GitRepository, worktree: string): string;
-export declare function runGit(repository: GitRepository, args: readonly string[], input?: string | Uint8Array): Buffer;
-export declare function runGitWithEnvironment(repository: GitRepository, args: readonly string[], input: string | Uint8Array | undefined, environment: NodeJS.ProcessEnv): Buffer;
-export declare function readRef(repository: GitRepository, ref: string): GitOid | null;
-export declare function readGit(repository: GitRepository): GitSnapshot;
+export declare function worktreeGitDirectory(repository: GitRepository, worktree: string): Promise<string>;
+export declare function worktreeRoot(repository: GitRepository): Promise<string>;
+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>;
+export declare function readRef(repository: GitRepository, ref: string): Promise<GitOid | null>;
+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[]): GitSnapshot;
+export declare function readGitPaths(repository: GitRepository, requestedPaths: readonly string[]): Promise<GitSnapshot>;
 /** Add paths from the same immutable Git tree without rereading its ref. */
-export declare function extendGitPaths(repository: GitRepository, snapshot: GitSnapshot, requestedPaths: readonly string[]): GitSnapshot;
+export declare function extendGitPaths(repository: GitRepository, snapshot: GitSnapshot, requestedPaths: readonly string[]): Promise<GitSnapshot>;
 /** Expand a targeted immutable snapshot to its complete already-pinned tree. */
-export declare function expandGitSnapshot(repository: GitRepository, snapshot: GitSnapshot): GitSnapshot;
-export declare function writeBlob(repository: GitRepository, bytes: string | Uint8Array): GitOid;
-export declare function readBlob(repository: GitRepository, oid: GitOid): Buffer;
-/** Read immutable Git objects through one structured, length-delimited batch. */
-export declare function readBlobs(repository: GitRepository, oids: readonly GitOid[]): ReadonlyMap<GitOid, Buffer>;
+export declare function expandGitSnapshot(repository: GitRepository, snapshot: GitSnapshot): Promise<GitSnapshot>;
+export declare function writeBlob(repository: GitRepository, bytes: string | Uint8Array): Promise<GitOid>;
+export declare function readBlob(repository: GitRepository, oid: GitOid): Promise<Buffer>;
 /** Copy only the changed paths' tree ancestors, preserving untouched subtrees by object ID. */
-export declare function updateGitTree(repository: GitRepository, baseTree: GitOid | null, changes: ReadonlyMap<string, TreeChange>): GitOid;
+export declare function updateGitTree(repository: GitRepository, baseTree: GitOid | null, changes: ReadonlyMap<string, TreeChange>): Promise<GitOid>;
+/** Write a tree update from directory entries frozen with the admitted base tree. */
+export declare function updateGitTreeFromFrozenDirectories(repository: GitRepository, baseTree: GitOid | null, directories: ReadonlyMap<string, ReadonlyMap<string, TreeEntry>>, changes: ReadonlyMap<string, TreeChange>): Promise<GitOid>;
 export declare function writeCommit(input: Readonly<{
     repository: GitRepository;
     tree: GitOid;
@@ -68,7 +84,7 @@ export declare function writeCommit(input: Readonly<{
     message?: string;
     actor?: string;
     at?: string;
-}>): GitOid;
+}>): Promise<GitOid>;
 export declare function updateRefsAtomically(repository: GitRepository, updates: readonly ({
     readonly ref: typeof GIT_REF;
     readonly newOid: GitOid;
@@ -77,4 +93,11 @@ export declare function updateRefsAtomically(repository: GitRepository, updates:
     readonly ref: string;
     readonly newOid: GitOid;
     readonly expectedOid: GitOid;
-})[]): RefPublication;
+})[], assertions?: readonly GitRefAssertion[]): Promise<RefPublication>;
+export type GitDiffStat = Readonly<{
+    filesChanged: number;
+    insertions: number;
+    deletions: number;
+}>;
+export declare function decodeGitNumstat(output: Buffer): GitDiffStat;
+export declare function decodeGitNameOnly(output: Buffer): readonly string[];