@astrosheep/keiyaku 4.0.0 → 4.0.1

package/build/src/git/repository.js

@@ -7,7 +7,7 @@ export const GIT_REF = "refs/heads/keiyaku-state";
 export const DELIVERY_REF_NAMESPACE = "refs/heads/keiyaku-delivery";
 export const CANDIDATE_PIN_REF_NAMESPACE = "refs/heads/keiyaku-candidate";
 export const GIT_FORMAT_PATH = "meta/format.json";
-const CURRENT_FORMAT_VERSION = 3;
+const CURRENT_FORMAT_VERSION = 4;
 export const GIT_FORMAT_BYTES = `{"version":${CURRENT_FORMAT_VERSION}}\n`;
 export function isKeiyakuOwnedRef(ref) {
     return ref === GIT_REF
@@ -25,20 +25,22 @@ export class NoGitWorldError extends Error {
     }
 }
 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;
     }
 }
-function worktreePathsFromPorcelain(output) {
+function worktreesFromPorcelain(output) {
     const fields = output.toString("utf8").split("\0");
-    const paths = [];
+    const worktrees = [];
     let record = [];
     const finishRecord = () => {
         if (record.length === 0)
@@ -50,7 +52,11 @@ function worktreePathsFromPorcelain(output) {
         const path = worktree.slice("worktree ".length);
         if (path.length === 0)
             throw new Error("Git worktree porcelain output has an empty worktree path");
-        paths.push(resolve(path));
+        const branchField = record.find((field) => field.startsWith("branch "));
+        const branch = branchField === undefined ? null : branchField.slice("branch ".length);
+        if (branch !== null && !branch.startsWith("refs/"))
+            throw new Error("Git worktree porcelain output has an invalid branch");
+        worktrees.push({ path: resolve(path), branch });
         record = [];
     };
     for (const field of fields) {
@@ -61,22 +67,29 @@ function worktreePathsFromPorcelain(output) {
         record.push(field);
     }
     finishRecord();
-    if (paths.length === 0)
+    if (worktrees.length === 0)
         throw new Error("Git worktree porcelain output has no worktrees");
-    return paths;
+    return worktrees;
 }
-export function registeredWorktreePaths(repository) {
-    return worktreePathsFromPorcelain(runGit(repository, ["worktree", "list", "--porcelain", "-z"]));
+export function registeredWorktrees(repository) {
+    return worktreesFromPorcelain(runGit(repository, ["worktree", "list", "--porcelain", "-z"]));
 }
+export function registeredWorktreePaths(repository) { return registeredWorktrees(repository).map((worktree) => worktree.path); }
 export function repositoryAt(cwd) {
     if (typeof cwd !== "string" || cwd.length === 0) {
         throw new Error("repository path must be a nonempty string");
     }
     const effectiveCwd = resolve(cwd);
-    const provisional = { effectiveCwd, primaryWorktree: effectiveCwd };
+    const provisional = {
+        effectiveCwd,
+        primaryWorktree: effectiveCwd,
+        commonDirectory: effectiveCwd,
+    };
     let primaryWorktree;
+    let commonDirectory;
     try {
         primaryWorktree = registeredWorktreePaths(provisional)[0];
+        commonDirectory = absoluteGitPath(provisional, ["--git-common-dir"], "common Git directory");
     }
     catch (error) {
         if (error instanceof GitPlumbingError && error.status === 128) {
@@ -84,7 +97,7 @@ export function repositoryAt(cwd) {
         }
         throw error;
     }
-    return { effectiveCwd, primaryWorktree };
+    return { effectiveCwd, primaryWorktree, commonDirectory };
 }
 function absoluteGitPath(repository, args, label) {
     const value = runGit(repository, ["rev-parse", "--path-format=absolute", ...args]).toString("utf8").trim();
@@ -93,17 +106,22 @@ function absoluteGitPath(repository, args, label) {
     return resolve(isAbsolute(value) ? value : resolve(repository.effectiveCwd, value));
 }
 export function commonGitDirectory(repository) {
-    return absoluteGitPath(repository, ["--git-common-dir"], "common Git directory");
+    return repository.commonDirectory;
 }
 export function worktreeGitDirectory(repository, worktree) {
     const scoped = { ...repository, effectiveCwd: worktree };
     return absoluteGitPath(scoped, ["--git-dir"], "worktree Git directory");
 }
+export function worktreeRoot(repository) {
+    return absoluteGitPath(repository, ["--show-toplevel"], "worktree root");
+}
 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}`,
@@ -145,8 +163,12 @@ function assertRef(ref) {
         throw new Error(`invalid Git ref: ${ref}`);
     }
 }
+function assertAssertionRef(ref) {
+    if (ref !== "HEAD")
+        assertRef(ref);
+}
 export function readRef(repository, ref) {
-    assertRef(ref);
+    assertAssertionRef(ref);
     try {
         const oid = runGit(repository, ["rev-parse", "--verify", "--quiet", ref]).toString("utf8").trim();
         if (oid.length === 0)
@@ -162,7 +184,7 @@ export function readRef(repository, ref) {
 }
 function readTreeForCommit(repository, commit) {
     assertOid(commit, "Git commit");
-    const tree = runGit(repository, ["rev-parse", "--verify", `${commit}^{tree}`]).toString("utf8").trim();
+    const tree = runGit(repository, ["show", "-s", "--format=%T", commit]).toString("utf8").trim();
     assertOid(tree, "Git tree");
     return tree;
 }
@@ -184,7 +206,7 @@ function parseTreeEntries(output) {
     }
     return entries;
 }
-function readTreeEntries(repository, tree) {
+export function readTreeEntries(repository, tree) {
     assertOid(tree, "tree");
     const output = runGit(repository, ["ls-tree", "-r", "-z", "--full-tree", tree]);
     return parseTreeEntries(output);
@@ -299,16 +321,6 @@ function readObjects(repository, oids) {
         malformedBatchOutput("trailing bytes");
     return objects;
 }
-/** Read immutable Git objects through one structured, length-delimited batch. */
-export function readBlobs(repository, oids) {
-    const blobs = new Map();
-    for (const [oid, object] of readObjects(repository, oids)) {
-        if (object.type !== "blob")
-            malformedBatchOutput(`expected blob for ${oid}, found ${object.type}`);
-        blobs.set(oid, object.bytes);
-    }
-    return blobs;
-}
 function validateGitFormat(repository, paths) {
     const format = paths.get(GIT_FORMAT_PATH);
     if (format === undefined)
@@ -375,13 +387,27 @@ function writePreparedTrees(repository, prepared) {
 export function updateGitTree(repository, baseTree, changes) {
     const update = treeUpdate(changes);
     const bases = baseTreeEntries(repository, baseTree, [...changes.keys()], update.nodePaths);
-    const representativeOid = baseTree ?? changes.values().next().value?.oid;
+    const representativeOid = baseTree ?? [...changes.values()].find((change) => change !== null)?.oid;
     if (representativeOid === undefined)
         throw new Error("cannot write an empty Git tree without an object format");
     const prepared = prepareTreeUpdate({ update, bases, oidBytes: representativeOid.length / 2 });
     writePreparedTrees(repository, prepared.trees);
     return prepared.root;
 }
+/** Write a tree update from directory entries frozen with the admitted base tree. */
+export function updateGitTreeFromFrozenDirectories(repository, baseTree, directories, changes) {
+    const update = treeUpdate(changes);
+    const representativeOid = baseTree ?? [...changes.values()].find((change) => change !== null)?.oid;
+    if (representativeOid === undefined)
+        throw new Error("cannot write an empty Git tree without an object format");
+    const prepared = prepareTreeUpdate({
+        update,
+        bases: directories,
+        oidBytes: representativeOid.length / 2,
+    });
+    writePreparedTrees(repository, prepared.trees);
+    return prepared.root;
+}
 function writeCommitObject(input) {
     const { repository, tree, parents, message, actor, email, at } = input;
     assertOid(tree, "commit tree");
@@ -413,7 +439,23 @@ export function writeCommit(input) {
         ...(input.at === undefined ? {} : { at: input.at }),
     });
 }
-export function updateRefsAtomically(repository, updates) {
+function refAssertionLine(assertion) {
+    assertAssertionRef(assertion.ref);
+    assertOid(assertion.oid, `expected oid for ${assertion.ref}`);
+    return `${assertion.ref === "HEAD" ? "" : "option no-deref\n"}verify ${assertion.ref} ${assertion.oid}`;
+}
+function refUpdateLine(update, index) {
+    assertRef(update.ref);
+    if (index > 0 && update.ref === GIT_REF)
+        throw new Error(`duplicate ref update: ${update.ref}`);
+    if (index > 0 && update.expectedOid === null)
+        throw new Error("target ref updates require non-null OIDs");
+    assertOid(update.newOid, `new oid for ${update.ref}`);
+    if (update.expectedOid !== null)
+        assertOid(update.expectedOid, `expected oid for ${update.ref}`);
+    return `option no-deref\nupdate ${update.ref} ${update.newOid} ${update.expectedOid ?? "0".repeat(update.newOid.length)}`;
+}
+export function updateRefsAtomically(repository, updates, assertions = []) {
     if (updates.length === 0)
         throw new Error("an atomic ref transaction needs a Git update");
     if (updates.length > 2)
@@ -422,24 +464,16 @@ export function updateRefsAtomically(repository, updates) {
     if (git === undefined || git.ref !== GIT_REF) {
         throw new Error(`the first atomic update must be the Git ref: ${GIT_REF}`);
     }
-    const lines = ["start"];
-    for (const [index, update] of updates.entries()) {
-        assertRef(update.ref);
-        if (index > 0 && update.ref === GIT_REF) {
-            throw new Error(`duplicate ref update: ${update.ref}`);
-        }
-        if (index > 0 && (update.newOid === null || update.expectedOid === null)) {
-            throw new Error("target ref updates require non-null OIDs");
-        }
-        assertOid(update.newOid, `new oid for ${update.ref}`);
-        if (update.expectedOid !== null)
-            assertOid(update.expectedOid, `expected oid for ${update.ref}`);
-        const expectedOid = update.expectedOid ?? "0".repeat(update.newOid.length);
-        lines.push(`update ${update.ref} ${update.newOid} ${expectedOid}`);
-    }
-    lines.push("prepare", "commit", "");
+    const lines = [
+        "start",
+        ...assertions.map(refAssertionLine),
+        ...updates.map(refUpdateLine),
+        "prepare",
+        "commit",
+        "",
+    ];
     try {
-        runGit(repository, ["update-ref", "--stdin", "--no-deref"], lines.join("\n"));
+        runGit(repository, ["update-ref", "--stdin"], lines.join("\n"));
         return { kind: "published" };
     }
     catch (error) {

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

@@ -0,0 +1,13 @@
+import type { SnapshotId } from "../core/facts/types.js";
+import { type GitRepository } from "./repository.js";
+export type MaterializedScratchCandidate = Readonly<{
+    cwd: string;
+    dispose: () => WorktreeLeak | null;
+}>;
+export type WorktreeLeak = Readonly<{
+    path: string;
+    diagnostic: string;
+}>;
+export declare function orphanedScratchWorktrees(paths: Iterable<string>): readonly string[];
+/** Materialize a disposable candidate worktree and own only its removal. */
+export declare function materializeScratchCandidate(repository: GitRepository, candidate: SnapshotId): MaterializedScratchCandidate;

package/build/src/git/scratch.js

@@ -0,0 +1,66 @@
+import { randomBytes } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gitObjectIdForSnapshot } from "./identity.js";
+import { runGit } from "./repository.js";
+import { currentProcessIdentity, probeProcessIdentity, } from "../runtime/proc/run.js";
+const SCRATCH_PREFIX = "keiyaku-v4-verify-";
+const SCRATCH_ROOT = realpathSync(tmpdir());
+function scratchPath() {
+    const owner = currentProcessIdentity();
+    const identity = Buffer.from(owner.spawnedAt, "utf8").toString("base64url");
+    return join(SCRATCH_ROOT, `${SCRATCH_PREFIX}${owner.pid}-${identity}-${randomBytes(12).toString("hex")}`);
+}
+function scratchOwner(path) {
+    const prefix = join(SCRATCH_ROOT, SCRATCH_PREFIX);
+    if (!path.startsWith(prefix))
+        return null;
+    const suffix = path.slice(prefix.length);
+    const match = /^([1-9][0-9]*)-([A-Za-z0-9_-]+)-([0-9a-f]{24})$/.exec(suffix);
+    if (match === null)
+        return null;
+    const pid = Number(match[1]);
+    if (!Number.isSafeInteger(pid))
+        return null;
+    let spawnedAt;
+    try {
+        spawnedAt = Buffer.from(match[2], "base64url").toString("utf8");
+    }
+    catch {
+        return null;
+    }
+    return spawnedAt.length === 0 ? null : { pid, spawnedAt };
+}
+export function orphanedScratchWorktrees(paths) {
+    const orphaned = [];
+    for (const path of paths) {
+        const owner = scratchOwner(path);
+        if (owner === null)
+            continue;
+        const state = probeProcessIdentity(owner);
+        if (state.kind === "gone" || state.kind === "replaced")
+            orphaned.push(path);
+    }
+    return orphaned;
+}
+/** Materialize a disposable candidate worktree and own only its removal. */
+export function materializeScratchCandidate(repository, candidate) {
+    const cwd = scratchPath();
+    runGit(repository, ["worktree", "add", "--detach", cwd, gitObjectIdForSnapshot(candidate)]);
+    return {
+        cwd,
+        dispose: () => {
+            try {
+                runGit(repository, ["worktree", "remove", "--force", cwd]);
+                return null;
+            }
+            catch (error) {
+                return {
+                    path: cwd,
+                    diagnostic: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+    };
+}

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

@@ -0,0 +1,56 @@
+import { type HeldSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
+import type { ContractId, ContractState, SnapshotId } from "../core/facts/types.js";
+import type { RefOperation } from "../core/facts/offer.js";
+import { type GitRepository } from "./repository.js";
+export type WorkspaceNotOnTargetRefusal = Readonly<{
+    kind: "workspace-not-on-target";
+    contractId: ContractId;
+    target: string;
+    branch: string | null;
+}>;
+export type CheckoutNotFollowableRefusal = Readonly<{
+    kind: "checkout-not-followable";
+    contractId: ContractId;
+    target: string;
+    path: string;
+    reason: "staged" | "conflict" | "untracked";
+    paths: readonly string[];
+}>;
+export type TargetPlacementRefusal = CheckoutNotFollowableRefusal | WorkspaceNotOnTargetRefusal;
+export type TargetCheckoutEffect = Readonly<{
+    kind: "target-checkout";
+    path: string;
+    target: string;
+    action: "followed" | "recovered";
+}>;
+export type TargetCheckoutLag = Readonly<{
+    kind: "target-checkout-retained";
+    path: string;
+    target: string;
+    diagnostic: string;
+}>;
+export type TargetPlacementPhysicalResult = Readonly<{
+    effects: readonly TargetCheckoutEffect[];
+    lag: readonly TargetCheckoutLag[];
+}>;
+type FollowArm = Readonly<{
+    kind: "ordinary" | "here";
+    path: string;
+}>;
+export type PreparedTargetPlacement = Readonly<{
+    target: RefOperation;
+    arms: readonly FollowArm[];
+}>;
+export type TargetPlacementPreparation = Readonly<{
+    kind: "prepared";
+    placement: PreparedTargetPlacement;
+}> | Readonly<{
+    kind: "refused";
+    refusal: TargetPlacementRefusal;
+}>;
+export declare function observeTargetHead(repository: GitRepository, target: string): SnapshotId | null;
+export declare function acquireTargetPlacementFence(repository: GitRepository, target: string): Promise<HeldSqliteTransactionLock>;
+export declare function prepareTargetPlacement(repository: GitRepository, state: ContractState, target: RefOperation): TargetPlacementPreparation;
+export declare function followTargetPlacement(repository: GitRepository, prepared: PreparedTargetPlacement): TargetPlacementPhysicalResult;
+export declare function recoverTargetPlacement(repository: GitRepository, state: ContractState): TargetPlacementPhysicalResult;
+export {};

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

@@ -0,0 +1,255 @@
+import { resolve } from "node:path";
+import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
+import { gitObjectId, gitObjectIdForSnapshot, gitRefLocator, mintSnapshotId } from "./identity.js";
+import { currentBranch } from "./observe.js";
+import { commonGitDirectory, GitPlumbingError, readRef, registeredWorktrees, runGit, } from "./repository.js";
+import { captureWorkspaceTree, withPrivateGitIndex } from "./workspace.js";
+export function observeTargetHead(repository, target) {
+    const value = readRef(repository, target);
+    return value === null ? null : mintSnapshotId(value);
+}
+function diagnostic(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function nulPaths(bytes) {
+    const fields = bytes.toString("utf8").split("\0");
+    if (fields.at(-1) !== "")
+        throw new Error("Git path output is not NUL terminated");
+    return [...new Set(fields.slice(0, -1))].sort();
+}
+function gitPaths(repository, path, args) {
+    return nulPaths(runGit(repository, ["-C", path, ...args]));
+}
+function commitTree(repository, snapshot) {
+    return gitObjectId(runGit(repository, ["show", "-s", "--format=%T", gitObjectIdForSnapshot(snapshot)])
+        .toString("utf8")
+        .trim(), "commit tree");
+}
+function pathsOverlap(left, right) {
+    return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+function intersection(left, right) {
+    return left.filter((candidate) => right.some((path) => pathsOverlap(candidate, path))).sort();
+}
+function failurePaths(error) {
+    if (!(error instanceof GitPlumbingError))
+        return [];
+    const paths = new Set();
+    for (const match of error.stderr.toString("utf8").matchAll(/(?:Entry|Untracked working tree file) '([^']+)'/gu)) {
+        paths.add(match[1]);
+    }
+    return [...paths].sort();
+}
+function checkoutRefusal(contractId, target, path, reason, error) {
+    const paths = failurePaths(error);
+    if (paths.length === 0)
+        throw error;
+    return { kind: "checkout-not-followable", contractId, target: target.target, path, reason, paths };
+}
+function indexMatchesTreeOnPaths(repository, path, tree, paths) {
+    return gitPaths(repository, path, ["diff-index", "--cached", "--name-only", "-z", tree, "--", ...paths]).length === 0;
+}
+function workspaceMatchesTreeOnPaths(repository, path, tree, workspaceTree, paths) {
+    return gitPaths(repository, path, ["diff", "--name-only", "-z", tree, workspaceTree, "--", ...paths]).length === 0;
+}
+function sourceWorktree(repository) {
+    return resolve(runGit(repository, ["rev-parse", "--show-toplevel"]).toString("utf8").trim());
+}
+function ordinaryPrecheck(repository, contractId, target, path) {
+    const predecessor = gitObjectIdForSnapshot(target.expectedOid);
+    const candidate = gitObjectIdForSnapshot(target.newOid);
+    try {
+        withPrivateGitIndex((environment) => {
+            runGit(repository, ["-C", path, "read-tree", "-i", `--index-output=${environment.GIT_INDEX_FILE}`, "-m", predecessor, candidate]);
+        });
+    }
+    catch (error) {
+        return checkoutRefusal(contractId, target, path, "staged", error);
+    }
+    const changed = gitPaths(repository, path, ["diff", "--name-only", "-z", predecessor, candidate]);
+    const dirty = gitPaths(repository, path, ["diff-files", "--name-only", "-z"]);
+    const conflicts = intersection(changed, dirty);
+    if (conflicts.length > 0) {
+        return {
+            kind: "checkout-not-followable",
+            contractId,
+            target: target.target,
+            path,
+            reason: "conflict",
+            paths: conflicts,
+        };
+    }
+    const additions = gitPaths(repository, path, ["diff", "--name-only", "--diff-filter=A", "-z", predecessor, candidate]);
+    const untracked = gitPaths(repository, path, ["ls-files", "--others", "-z"]);
+    const collisions = intersection(additions, untracked);
+    if (collisions.length > 0) {
+        return {
+            kind: "checkout-not-followable",
+            contractId,
+            target: target.target,
+            path,
+            reason: "untracked",
+            paths: collisions,
+        };
+    }
+    try {
+        runGit(repository, ["-C", path, "read-tree", "--dry-run", "-m", "-u", predecessor, candidate]);
+    }
+    catch (error) {
+        const reason = error instanceof GitPlumbingError && /untracked working tree file/iu.test(error.stderr.toString("utf8"))
+            ? "untracked"
+            : "conflict";
+        return checkoutRefusal(contractId, target, path, reason, error);
+    }
+    return null;
+}
+export async function acquireTargetPlacementFence(repository, target) {
+    const locator = gitRefLocator(target);
+    return acquireSqliteTransactionLock({
+        path: resolve(commonGitDirectory(repository), "keiyaku", "locks", "target-placement", `${locator}.sqlite`),
+        mode: "immediate",
+    });
+}
+export function prepareTargetPlacement(repository, state, target) {
+    if (state.coordinates.target !== target.target || state.delivery?.data.integration.snapshot !== target.newOid) {
+        throw new Error("placement state does not match its offered target movement");
+    }
+    const worktrees = registeredWorktrees(repository)
+        .filter((worktree) => worktree.branch === target.target)
+        .sort((left, right) => left.path.localeCompare(right.path));
+    const hereSource = state.coordinates.workspace === "here" ? sourceWorktree(repository) : null;
+    if (hereSource !== null) {
+        const branch = currentBranch(repository, hereSource);
+        if (branch !== target.target) {
+            return {
+                kind: "refused",
+                refusal: {
+                    kind: "workspace-not-on-target",
+                    contractId: state.id,
+                    target: target.target,
+                    branch,
+                },
+            };
+        }
+    }
+    const arms = [];
+    for (const worktree of worktrees) {
+        const kind = hereSource !== null && resolve(worktree.path) === hereSource ? "here" : "ordinary";
+        if (kind === "ordinary") {
+            const refusal = ordinaryPrecheck(repository, state.id, target, worktree.path);
+            if (refusal !== null)
+                return { kind: "refused", refusal };
+        }
+        arms.push({ kind, path: worktree.path });
+    }
+    if (hereSource !== null && !arms.some((arm) => arm.kind === "here")) {
+        throw new Error("targeted here workspace is not a registered checkout of its target");
+    }
+    return { kind: "prepared", placement: { target, arms } };
+}
+export function followTargetPlacement(repository, prepared) {
+    const effects = [];
+    const lag = [];
+    const predecessor = gitObjectIdForSnapshot(prepared.target.expectedOid);
+    const candidate = gitObjectIdForSnapshot(prepared.target.newOid);
+    for (const arm of prepared.arms) {
+        try {
+            if (arm.kind === "here")
+                runGit(repository, ["-C", arm.path, "read-tree", candidate]);
+            else
+                runGit(repository, ["-C", arm.path, "read-tree", "-m", "-u", predecessor, candidate]);
+            effects.push({ kind: "target-checkout", path: arm.path, target: prepared.target.target, action: "followed" });
+        }
+        catch (error) {
+            lag.push({
+                kind: "target-checkout-retained",
+                path: arm.path,
+                target: prepared.target.target,
+                diagnostic: diagnostic(error),
+            });
+        }
+    }
+    return { effects, lag };
+}
+function recoveryLag(path, target, detail) {
+    return { kind: "target-checkout-retained", path, target, diagnostic: detail };
+}
+function recoverCheckout(input) {
+    const { repository, path, predecessor, candidate, predecessorTree, candidateTree } = input;
+    const changedPaths = gitPaths(repository, path, ["diff", "--name-only", "-z", predecessorTree, candidateTree]);
+    if (changedPaths.length === 0)
+        return "complete";
+    const workspaceTree = captureWorkspaceTree(repository, path).tree;
+    const candidateIndex = indexMatchesTreeOnPaths(repository, path, candidateTree, changedPaths);
+    const candidateWorkspace = workspaceMatchesTreeOnPaths(repository, path, candidateTree, workspaceTree, changedPaths);
+    if (candidateIndex && candidateWorkspace)
+        return "complete";
+    if (workspaceTree === candidateTree) {
+        runGit(repository, ["-C", path, "read-tree", gitObjectIdForSnapshot(candidate)]);
+        return "recovered";
+    }
+    const predecessorIndex = indexMatchesTreeOnPaths(repository, path, predecessorTree, changedPaths);
+    if (predecessorIndex && candidateWorkspace) {
+        runGit(repository, [
+            "-C",
+            path,
+            "read-tree",
+            "-i",
+            "-m",
+            gitObjectIdForSnapshot(predecessor),
+            gitObjectIdForSnapshot(candidate),
+        ]);
+        return "recovered";
+    }
+    const predecessorWorkspace = workspaceMatchesTreeOnPaths(repository, path, predecessorTree, workspaceTree, changedPaths);
+    if (!predecessorIndex || !predecessorWorkspace)
+        return "retained";
+    runGit(repository, [
+        "-C",
+        path,
+        "read-tree",
+        "-m",
+        "-u",
+        gitObjectIdForSnapshot(predecessor),
+        gitObjectIdForSnapshot(candidate),
+    ]);
+    return "recovered";
+}
+export function recoverTargetPlacement(repository, state) {
+    const target = state.coordinates.target;
+    const delivery = state.delivery;
+    if (state.terminal?.kind !== "claimed" || target === undefined || delivery === null)
+        return { effects: [], lag: [] };
+    if (readRef(repository, target) !== delivery.data.integration.snapshot)
+        return { effects: [], lag: [] };
+    const candidateTree = commitTree(repository, delivery.data.integration.snapshot);
+    const predecessorTree = commitTree(repository, delivery.data.integration.predecessor);
+    const worktrees = registeredWorktrees(repository)
+        .filter((worktree) => worktree.branch === target)
+        .sort((left, right) => left.path.localeCompare(right.path));
+    const effects = [];
+    const lag = [];
+    for (const worktree of worktrees) {
+        try {
+            const recovery = recoverCheckout({
+                repository,
+                path: worktree.path,
+                predecessor: delivery.data.integration.predecessor,
+                candidate: delivery.data.integration.snapshot,
+                predecessorTree,
+                candidateTree,
+            });
+            if (recovery === "retained") {
+                lag.push(recoveryLag(worktree.path, target, "target checkout entries are neither predecessor nor candidate"));
+                continue;
+            }
+            if (recovery === "recovered") {
+                effects.push({ kind: "target-checkout", path: worktree.path, target, action: "recovered" });
+            }
+        }
+        catch (error) {
+            lag.push(recoveryLag(worktree.path, target, diagnostic(error)));
+        }
+    }
+    return { effects, lag };
+}