@astrosheep/keiyaku 4.5.29 → 4.6.2

package/build/src/git/reconcile.js

@@ -1,17 +1,99 @@
+import { snapshotIdSchema, mintedSnapshotInputSchema } from "./identity.js";
+import { z } from "zod";
+import { targetCheckoutEffectSchema, targetCheckoutLagSchema } from "./target-placement.js";
+import { worktreeHookLagSchema } from "./hooks.js";
+import { unsealedBytesSchema } from "./terminal-seal.js";
 import { access, mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { acquireSqliteTransactionLock, } from "../coordination/sqlite-transaction-lock.js";
+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 } from "./process.js";
+import { runGit, GitPlumbingError } from "./process.js";
 import { contractLocator, contractPhysicalName, gitObjectIdForSnapshot } from "./identity.js";
 import { observeContractAt } from "./observe.js";
-import { acquireTargetPlacementFence, recoverTargetPlacement, } from "./target-placement.js";
+import { acquireTargetPlacementFence, recoverTargetPlacement } from "./target-placement.js";
 import { runCreateHooks } from "./hooks.js";
 import { followDependentManagedWorktree, retireConflictHandoff, worktreePath } from "./workspace.js";
 import { removeCollectableScratchWorktrees } from "./scratch.js";
 import { reconcileTerminalManagedWorktree, removeRef, updateRef } from "./terminal-reconcile.js";
+class WorktreeCustodyError extends Error {
+}
 const pathExists = (path) => access(path).then(() => true, () => false);
+export const reconcileEffectSchema = z.union([
+    z
+        .object({
+        kind: z.literal("worktree"),
+        path: z.string().refine((value) => value.trim() !== ""),
+        action: z.enum(["created", "removed", "unchanged"]),
+        before: z.unknown().optional(),
+        after: z.unknown().optional(),
+    })
+        .strict()
+        .transform(({ before: _before, after: _after, ...effect }) => effect),
+    z
+        .object({
+        kind: z.literal("worktree"),
+        path: z.string().refine((value) => value.trim() !== ""),
+        action: z.literal("followed"),
+        before: snapshotIdSchema,
+        after: snapshotIdSchema,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("recovery-snapshot"),
+        action: z.literal("created"),
+        snapshot: snapshotIdSchema,
+        retention: z.literal("ephemeral"),
+    })
+        .strict(),
+    targetCheckoutEffectSchema,
+    z
+        .object({
+        kind: z.literal("ref"),
+        name: z.string().refine((value) => value.trim() !== ""),
+        before: z.string().min(1).nullable(),
+        after: z.string().min(1).nullable(),
+        action: z.enum(["created", "updated", "removed", "unchanged"]),
+    })
+        .strict(),
+]);
+const reconcileFailureSchema = z
+    .object({
+    kind: z.literal("reconcile-failed"),
+    stage: z.enum(["observation", "effect"]),
+    diagnostic: z.string().refine((value) => value.trim() !== ""),
+})
+    .strict();
+export const gitReconcileLagSchema = z.union([
+    z
+        .object({
+        kind: z.literal("worktree-retained"),
+        path: z.string().refine((value) => value.trim() !== ""),
+        diagnostic: z
+            .string()
+            .refine((value) => value.trim() !== "")
+            .optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("worktree-follow-retained"),
+        path: z.string().refine((value) => value.trim() !== ""),
+        tender: mintedSnapshotInputSchema,
+        head: mintedSnapshotInputSchema,
+        reason: z.enum(["head-moved", "head-attached", "operation-in-progress", "unsupported-parent-shape"]),
+        paths: z
+            .array(z.string().refine((value) => value.trim() !== ""))
+            .readonly()
+            .optional(),
+    })
+        .strict(),
+    unsealedBytesSchema,
+    targetCheckoutLagSchema,
+    worktreeHookLagSchema,
+    reconcileFailureSchema,
+]);
 function deliveryRefFor(contract) {
     return `${DELIVERY_REF_NAMESPACE}/${contractPhysicalName(contract)}`;
 }
@@ -34,8 +116,36 @@ function diagnostic(error) {
 function complete(effects = [], lag = [], hookRuns = []) {
     return hookRuns.length === 0 ? { effects, lag } : { effects, lag, hookRuns };
 }
+/** Append owner observations and publish those same objects before the next await. */
+function reconcileAccumulation(onPhysical) {
+    const effects = [];
+    const lag = [];
+    return {
+        effects,
+        lag,
+        hookRuns: [],
+        recordEffect(...observed) {
+            effects.push(...observed);
+            if (observed.length > 0)
+                onPhysical?.({ effects: observed, lag: [] });
+        },
+        recordLag(...observed) {
+            lag.push(...observed);
+            if (observed.length > 0)
+                onPhysical?.({ effects: [], lag: observed });
+        },
+    };
+}
 function failed(stage, error, effects = [], lag = []) {
-    if (error instanceof AuthorityCorruptionError || error instanceof TypeError)
+    if (!(error instanceof WorktreeCustodyError ||
+        error instanceof GitPlumbingError ||
+        error instanceof SqliteTransactionLockError ||
+        (error instanceof Error &&
+            !(error instanceof AuthorityCorruptionError) &&
+            !(error instanceof TypeError) &&
+            "code" in error &&
+            typeof error.code === "string" &&
+            /^E[A-Z0-9]+$/u.test(error.code))))
         throw error;
     return { effects, lag: [...lag, { kind: "reconcile-failed", stage, diagnostic: diagnostic(error) }] };
 }
@@ -52,20 +162,24 @@ async function worktree(repository, topology, path, desired) {
         topology.paths.delete(path);
     }
     if (await pathExists(path))
-        throw new Error(`delivery worktree path is occupied: ${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)]);
     topology.paths.add(path);
     return { kind: "worktree", path, action: "created" };
 }
-async function removeCollectableScratch(repository, topology, effects, lag) {
+async function removeCollectableScratch(repository, topology, acc) {
     for (const removal of await removeCollectableScratchWorktrees(repository, topology.paths)) {
-        effects.push({ kind: "worktree", path: removal.path, action: removal.action });
+        acc.recordEffect({ kind: "worktree", path: removal.path, action: removal.action });
         if (removal.retained)
-            lag.push({ kind: "worktree-retained", path: removal.path });
+            acc.recordLag({
+                kind: "worktree-retained",
+                path: removal.path,
+                ...(removal.diagnostic === undefined ? {} : { diagnostic: removal.diagnostic }),
+            });
     }
 }
-async function reconcileTargetCheckouts(repository, state) {
+async function reconcileTargetCheckouts(repository, state, onPhysical) {
     if (state.terminal?.kind !== "claimed" || state.coordinates.target === undefined || state.delivery === null) {
         return complete();
     }
@@ -79,14 +193,16 @@ async function reconcileTargetCheckouts(repository, state) {
     let result;
     let exceptional;
     try {
-        const recovered = await recoverTargetPlacement(repository, state);
+        const recovered = await recoverTargetPlacement(repository, state, onPhysical);
         result = complete(recovered.effects, recovered.lag);
     }
     catch (error) {
-        if (error instanceof AuthorityCorruptionError || error instanceof TypeError)
-            exceptional = error;
-        else
+        try {
             result = failed("effect", error);
+        }
+        catch (unexpected) {
+            exceptional = { error: unexpected };
+        }
     }
     let releaseFailure;
     try {
@@ -96,21 +212,24 @@ async function reconcileTargetCheckouts(repository, state) {
         releaseFailure = error;
     }
     if (exceptional !== undefined)
-        throw exceptional;
+        throw exceptional.error;
     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 reconcileActiveManagedWorktree({ repository, hooks, retryHooks, place }, state, topology, { effects, lag, hookRuns }) {
-    if (place === undefined)
-        return complete(effects, [...lag, missingPlaceLag(repository)]);
+async function reconcileActiveManagedWorktree({ repository, hooks, retryHooks, place }, state, topology, acc) {
+    const { effects, lag, hookRuns } = acc;
+    if (place === undefined) {
+        acc.recordLag(missingPlaceLag(repository));
+        return complete(effects, lag);
+    }
     const path = worktreePath(repository, place);
     const desired = state.delivery?.data.tenderSnapshot ?? state.coordinates.start;
-    effects.push(await updateRef(repository, deliveryRefFor(state.id), desired));
+    acc.recordEffect(await updateRef(repository, deliveryRefFor(state.id), desired));
     const projection = await worktree(repository, topology, path, desired);
-    effects.push(projection);
+    acc.recordEffect(projection);
     const handoff = await retireConflictHandoff(repository, {
         contractId: state.id,
         place,
@@ -118,7 +237,7 @@ async function reconcileActiveManagedWorktree({ repository, hooks, retryHooks, p
         consume: state.delivery !== null,
     });
     if (state.delivery !== null && handoff.kind === "retained") {
-        lag.push({
+        acc.recordLag({
             kind: "reconcile-failed",
             stage: "effect",
             diagnostic: `conflict handoff retirement retained: ${handoff.reason}`,
@@ -128,14 +247,14 @@ async function reconcileActiveManagedWorktree({ repository, hooks, retryHooks, p
         const hookRun = await runCreateHooks(path, hooks);
         hookRuns.push(...hookRun.runs.map((name) => ({ phase: "create", name })));
         if (hookRun.lag !== null)
-            lag.push(hookRun.lag);
+            acc.recordLag(hookRun.lag);
     }
-    effects.push(await (state.delivery
+    acc.recordEffect(await (state.delivery
         ? await updateRef(repository, candidatePinRefFor(state.id), state.currentIntegration?.snapshot ?? state.delivery.data.integration.snapshot)
         : await removeRef(repository, candidatePinRefFor(state.id))));
     return complete(effects, lag, hookRuns);
 }
-async function terminalHandoffRetained(input, state, topology, lag) {
+async function terminalHandoffRetained(input, state, topology, acc) {
     if (input.place === undefined)
         return false;
     const path = worktreePath(input.repository, input.place);
@@ -148,7 +267,7 @@ async function terminalHandoffRetained(input, state, topology, lag) {
         consume: state.delivery !== null,
     });
     if (handoff.kind === "active") {
-        lag.push({
+        acc.recordLag({
             kind: "reconcile-failed",
             stage: "effect",
             diagnostic: "conflict handoff retirement retained: active",
@@ -157,7 +276,7 @@ async function terminalHandoffRetained(input, state, topology, lag) {
     }
     if (handoff.kind !== "retained")
         return false;
-    lag.push({
+    acc.recordLag({
         kind: "reconcile-failed",
         stage: "effect",
         diagnostic: `conflict handoff retirement retained: ${handoff.reason}`,
@@ -166,22 +285,24 @@ async function terminalHandoffRetained(input, state, topology, lag) {
 }
 async function reconcileWithTopology(input, state, topology) {
     const { repository } = input;
-    const effects = [];
-    const lag = [];
-    const hookRuns = [];
+    const acc = reconcileAccumulation(input.onPhysical);
+    const { effects, lag, hookRuns } = acc;
     try {
-        await removeCollectableScratch(repository, topology, effects, lag);
+        await removeCollectableScratch(repository, topology, acc);
         if (!state)
             return complete(effects, lag);
-        const targetCheckouts = await reconcileTargetCheckouts(repository, state);
-        effects.push(...targetCheckouts.effects);
-        lag.push(...targetCheckouts.lag);
+        const targetCheckouts = await reconcileTargetCheckouts(repository, state, input.onPhysical);
+        acc.recordEffect(...targetCheckouts.effects);
+        acc.recordLag(...targetCheckouts.lag);
         if (state.terminal) {
-            if (await terminalHandoffRetained(input, state, topology, lag))
+            if (await terminalHandoffRetained(input, state, topology, acc))
                 return complete(effects, lag, hookRuns);
-            return await reconcileTerminalManagedWorktree(input, state, topology, { effects, lag, hookRuns }, { ref: deliveryRefFor(state.id), pin: candidatePinRefFor(state.id) });
+            return await reconcileTerminalManagedWorktree(input, state, topology, acc, {
+                ref: deliveryRefFor(state.id),
+                pin: candidatePinRefFor(state.id),
+            });
         }
-        const result = await reconcileActiveManagedWorktree(input, state, topology, { effects, lag, hookRuns });
+        const result = await reconcileActiveManagedWorktree(input, state, topology, acc);
         return hookRuns.length === 0 ? result : { ...result, hookRuns };
     }
     catch (error) {
@@ -221,16 +342,24 @@ export async function reconcile(input) {
             state,
             result: await reconcileWithTopology(input, state, topology),
         };
+        input.onPhysical?.(observation.result);
     }
     catch (error) {
-        if (error instanceof AuthorityCorruptionError || error instanceof TypeError)
-            exceptional = error;
-        else
+        try {
             observation = { state: null, result: failed("observation", error) };
+        }
+        catch (unexpected) {
+            exceptional = { error: unexpected };
+        }
+    }
+    try {
+        observation = releaseFailure(held, observation);
+    }
+    catch (error) {
+        exceptional ??= { error };
     }
-    observation = releaseFailure(held, observation);
     if (exceptional !== undefined)
-        throw exceptional;
+        throw exceptional.error;
     if (observation === undefined)
         throw new Error("reconcile produced no observation");
     return observation;

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

@@ -1,17 +1,20 @@
+import { z } from "zod";
 import type { SnapshotId } from "../core/facts/types.js";
 import { type GitRepository } from "./process.js";
 export type MaterializedScratchCandidate = Readonly<{
     cwd: string;
     dispose: () => Promise<WorktreeLeak | null>;
 }>;
-export type WorktreeLeak = Readonly<{
-    path: string;
-    diagnostic: string;
-}>;
+export declare const worktreeLeakSchema: z.ZodObject<{
+    path: z.ZodString;
+    diagnostic: z.ZodString;
+}, z.core.$strict>;
+export type WorktreeLeak = z.infer<typeof worktreeLeakSchema>;
 type CollectableScratchRemoval = Readonly<{
     path: string;
     action: "removed" | "unchanged";
     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[]>;

package/build/src/git/scratch.js

@@ -1,5 +1,6 @@
+import { z } from "zod";
 import { randomBytes } from "node:crypto";
-import { access, realpath } from "node:fs/promises";
+import { access, realpath, unlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { tryAcquireSqliteTransactionLock, } from "../coordination/sqlite-transaction-lock.js";
@@ -8,6 +9,7 @@ import { runGit } from "./process.js";
 const SCRATCH_PREFIX = "keiyaku-v4-verify-";
 const SCRATCH_ROOT = await realpath(tmpdir());
 const SCRATCH_PATTERN = /^keiyaku-v4-verify-([0-9a-f]{24})$/;
+export const worktreeLeakSchema = z.object({ path: z.string(), diagnostic: z.string() }).strict();
 function scratchPath() {
     return join(SCRATCH_ROOT, `${SCRATCH_PREFIX}${randomBytes(12).toString("hex")}`);
 }
@@ -17,6 +19,12 @@ function ownershipLockPath(path) {
     const match = SCRATCH_PATTERN.exec(basename(path));
     return match === null ? null : join(SCRATCH_ROOT, `.${SCRATCH_PREFIX}${match[1]}.owner.sqlite`);
 }
+async function removeOwnershipLock(lockPath) {
+    await unlink(lockPath).catch((error) => {
+        if (error.code !== "ENOENT")
+            throw error;
+    });
+}
 async function collectableScratchWorktrees(paths) {
     const collectable = [];
     for (const path of paths) {
@@ -25,7 +33,7 @@ async function collectableScratchWorktrees(paths) {
             continue;
         const lock = await tryAcquireSqliteTransactionLock({ path: lockPath, mode: "exclusive" });
         if (lock !== null)
-            collectable.push({ path, release: () => lock.close() });
+            collectable.push({ path, lockPath, release: () => lock.close() });
     }
     return collectable;
 }
@@ -34,24 +42,34 @@ const pathExists = (path) => access(path).then(() => true, () => false);
 export async function removeCollectableScratchWorktrees(repository, paths) {
     const removals = [];
     for (const scratch of await collectableScratchWorktrees(paths)) {
+        let removed = false;
         try {
             if (!(await pathExists(scratch.path))) {
                 await runGit(repository, ["worktree", "remove", scratch.path]);
                 paths.delete(scratch.path);
+                removed = true;
                 removals.push({ path: scratch.path, action: "removed", retained: false });
                 continue;
             }
             try {
                 await runGit(repository, ["worktree", "remove", "--force", scratch.path]);
                 paths.delete(scratch.path);
+                removed = true;
                 removals.push({ path: scratch.path, action: "removed", retained: false });
             }
-            catch {
-                removals.push({ path: scratch.path, action: "unchanged", retained: true });
+            catch (error) {
+                removals.push({
+                    path: scratch.path,
+                    action: "unchanged",
+                    retained: true,
+                    diagnostic: error instanceof Error ? error.message : String(error),
+                });
             }
         }
         finally {
             scratch.release();
+            if (removed)
+                await removeOwnershipLock(scratch.lockPath);
         }
     }
     return removals;
@@ -73,6 +91,7 @@ export async function materializeScratchCandidate(repository, candidate) {
     }
     catch (error) {
         ownership.close();
+        await removeOwnershipLock(lockPath);
         throw error;
     }
     let disposed = false;
@@ -82,19 +101,22 @@ export async function materializeScratchCandidate(repository, candidate) {
             if (disposed)
                 return null;
             disposed = true;
+            let leak = null;
             try {
                 await runGit({ ...repository, signal: AbortSignal.timeout(5_000) }, ["worktree", "remove", "--force", cwd]);
-                return null;
             }
             catch (error) {
-                return {
+                leak = {
                     path: cwd,
                     diagnostic: error instanceof Error ? error.message : String(error),
                 };
             }
             finally {
                 ownership.close();
+                if (leak === null)
+                    await removeOwnershipLock(lockPath);
             }
+            return leak;
         },
     };
 }

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

@@ -1,28 +1,35 @@
+import { z } from "zod";
 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 "./process.js";
-export type CheckoutNotFollowableRefusal = Readonly<{
-    kind: "checkout-not-followable";
-    contractId: ContractId;
-    target: string;
-    path: string;
-    reason: "staged" | "dirty-tracked" | "unmerged" | "untracked";
-    paths: readonly string[];
-}>;
+export declare const checkoutNotFollowableRefusalSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"checkout-not-followable">;
+    contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+    target: z.ZodString;
+    path: z.ZodString;
+    reason: z.ZodLiteral<"untracked">;
+    paths: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+type CheckoutNotFollowableRefusal = z.infer<typeof checkoutNotFollowableRefusalSchema>;
 export type TargetPlacementRefusal = CheckoutNotFollowableRefusal;
-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 declare const targetCheckoutEffectSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"target-checkout">;
+    path: z.ZodString;
+    target: z.ZodString;
+    action: z.ZodEnum<{
+        followed: "followed";
+        recovered: "recovered";
+    }>;
+}, z.core.$strict>;
+type TargetCheckoutEffect = z.infer<typeof targetCheckoutEffectSchema>;
+export declare const targetCheckoutLagSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"target-checkout-retained">;
+    path: z.ZodString;
+    target: z.ZodString;
+    diagnostic: z.ZodString;
+}, z.core.$strict>;
+type TargetCheckoutLag = z.infer<typeof targetCheckoutLagSchema>;
 export type TargetPlacementPhysicalResult = Readonly<{
     effects: readonly TargetCheckoutEffect[];
     lag: readonly TargetCheckoutLag[];
@@ -74,31 +81,39 @@ export type TargetPlacementObservation = Readonly<{
 }>;
 /** Observe whether registered target checkouts can follow a predecessor-to-candidate movement. */
 export declare function observeTargetPlacement(repository: GitRepository, input: TargetPlacementObservationInput, changes?: TargetPlacementChanges): Promise<TargetPlacementObservation>;
-export type AuditTargetAnswer = Readonly<{
-    kind: "placeable";
-    ref: string;
-    head: SnapshotId;
-}> | Readonly<{
-    kind: "moved";
-    ref: string;
-    expected: SnapshotId;
-    observed: SnapshotId | null;
-}> | Readonly<{
-    kind: "refused";
-    refusal: TargetPlacementRefusal;
-}> | Readonly<{
-    kind: "failed";
-    diagnostic: string;
-}>;
+export declare const auditTargetAnswerSchema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"placeable">;
+    ref: z.ZodString;
+    head: z.ZodPipe<z.ZodString, z.ZodTransform<SnapshotId, string>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"moved">;
+    ref: z.ZodString;
+    expected: z.ZodPipe<z.ZodString, z.ZodTransform<SnapshotId, string>>;
+    observed: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<SnapshotId, string>>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"refused">;
+    refusal: z.ZodObject<{
+        kind: z.ZodLiteral<"checkout-not-followable">;
+        contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+        target: z.ZodString;
+        path: z.ZodString;
+        reason: z.ZodLiteral<"untracked">;
+        paths: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"failed">;
+    diagnostic: z.ZodString;
+}, z.core.$strict>]>;
+type AuditTargetAnswer = z.infer<typeof auditTargetAnswerSchema>;
 /** Adjudicate the complete post-Verification audit target answer without placing. */
 export declare function adjudicateAuditTarget(repository: GitRepository, input: TargetPlacementObservationInput): Promise<AuditTargetAnswer>;
 export declare function prepareTargetPlacement(repository: GitRepository, state: ContractState, target: RefOperation, changes?: TargetPlacementChanges): Promise<TargetPlacementPreparation>;
-export declare function followTargetPlacement(repository: GitRepository, prepared: PreparedTargetPlacement): Promise<TargetPlacementPhysicalResult>;
+export declare function followTargetPlacement(repository: GitRepository, prepared: PreparedTargetPlacement, onPhysical?: (report: TargetPlacementPhysicalResult) => void): Promise<TargetPlacementPhysicalResult>;
 /** Judge the target-checkout shape without mutating refs, worktrees, or indexes. */
 export declare function observeTargetCheckoutShape(repository: GitRepository, input: Readonly<{
     path: string;
     predecessor: SnapshotId;
     candidate: SnapshotId;
 }>): Promise<"complete" | "recoverable" | "retained">;
-export declare function recoverTargetPlacement(repository: GitRepository, state: ContractState): Promise<TargetPlacementPhysicalResult>;
+export declare function recoverTargetPlacement(repository: GitRepository, state: ContractState, onPhysical?: (report: TargetPlacementPhysicalResult) => void): Promise<TargetPlacementPhysicalResult>;
 export {};