@astrosheep/keiyaku 4.5.29 → 4.6.2

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

@@ -1,3 +1,5 @@
+import { contractIdSchema, snapshotIdSchema } from "./identity.js";
+import { z } from "zod";
 import { StringDecoder } from "node:string_decoder";
 import { lstat } from "node:fs/promises";
 import { resolve } from "node:path";
@@ -6,6 +8,32 @@ import { gitObjectId, gitObjectIdForSnapshot, gitRefLocator, mintSnapshotId } fr
 import { commonGitDirectory, decodeGitNameOnly, readRef, registeredWorktrees } from "./repository.js";
 import { consumeGitStdout, GitPlumbingError, runGit } from "./process.js";
 import { captureWorkspaceTree } from "./workspace.js";
+export const checkoutNotFollowableRefusalSchema = z
+    .object({
+    kind: z.literal("checkout-not-followable"),
+    contractId: contractIdSchema,
+    target: z.string().refine((value) => value.trim() !== ""),
+    path: z.string().refine((value) => value.trim() !== ""),
+    reason: z.literal("untracked"),
+    paths: z.array(z.string().refine((value) => value.trim() !== "")).readonly(),
+})
+    .strict();
+export const targetCheckoutEffectSchema = z
+    .object({
+    kind: z.literal("target-checkout"),
+    path: z.string().refine((value) => value.trim() !== ""),
+    target: z.string().refine((value) => value.trim() !== ""),
+    action: z.enum(["followed", "recovered"]),
+})
+    .strict();
+export const targetCheckoutLagSchema = z
+    .object({
+    kind: z.literal("target-checkout-retained"),
+    path: z.string().refine((value) => value.trim() !== ""),
+    target: z.string().refine((value) => value.trim() !== ""),
+    diagnostic: z.string().refine((value) => value.trim() !== ""),
+})
+    .strict();
 export async function observeTargetHead(repository, target) {
     const value = await readRef(repository, target);
     return value === null ? null : mintSnapshotId(value);
@@ -67,37 +95,6 @@ export async function prepareTargetPlacementChanges(repository, target) {
     writes.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
     return { predecessor: target.expectedOid, candidate: target.newOid, paths, writes };
 }
-async function dryRunRefusal(input, scopes) {
-    const { repository, contractId, target, path, predecessor, changes } = input;
-    const pathspecs = changes.paths.map(literalPath);
-    if (pathspecs.length === 0)
-        return null;
-    const unmerged = await gitPaths(repository, path, [
-        "diff",
-        "--name-only",
-        "--diff-filter=U",
-        "-z",
-        "--",
-        ...pathspecs,
-    ]);
-    if (unmerged.length > 0)
-        return checkoutRefusal(contractId, target, path, "unmerged", unmerged);
-    const staged = await gitPaths(repository, path, [
-        "diff",
-        "--cached",
-        "--name-only",
-        "-z",
-        predecessor,
-        "--",
-        ...pathspecs,
-    ]);
-    if (staged.length > 0)
-        return checkoutRefusal(contractId, target, path, "staged", staged);
-    const dirty = await gitPaths(repository, path, ["diff-files", "--name-only", "-z", "--", ...pathspecs]);
-    if (dirty.length > 0)
-        return checkoutRefusal(contractId, target, path, "dirty-tracked", dirty);
-    return await untrackedRefusalWithinScopes(input, scopes, false);
-}
 async function physicalScope(candidatePath, metadata) {
     const components = candidatePath.split("/");
     for (let index = 0; index < components.length; index += 1) {
@@ -135,20 +132,12 @@ async function destructionScopes(worktree, writes) {
     }
     return [...scopes.values()].sort((left, right) => left.path.localeCompare(right.path));
 }
-function untrackedArgs(ignored) {
-    return [
-        "ls-files",
-        "--others",
-        ...(ignored ? ["--ignored"] : []),
-        "--exclude-standard",
-        "--directory",
-        "--no-empty",
-        "-z",
-    ];
+function untrackedArgs() {
+    return ["ls-files", "--others", "--ignored", "--exclude-standard", "--directory", "--no-empty", "-z"];
 }
-async function untrackedRefusalWithinScopes(input, scopes, ignored) {
+async function untrackedRefusalWithinScopes(input, scopes) {
     const { repository, contractId, target, path } = input;
-    const args = untrackedArgs(ignored);
+    const args = untrackedArgs();
     const leaves = scopes.filter((scope) => scope.kind === "leaf");
     if (leaves.length > 0) {
         const collisions = await gitPaths(repository, path, [
@@ -208,27 +197,25 @@ async function workspaceMatchesTreeOnPaths(repository, path, tree, workspaceTree
         ...paths.map(literalPath),
     ])).length === 0);
 }
+/**
+ * A checkout that git cannot carry is judged by the physical follow, which records its own lag.
+ * The one collision read-tree cannot report is a candidate write over an ignored worktree entry:
+ * git carries that by silently destroying the entry, so it is refused here instead.
+ */
 async function ordinaryPrecheck(repository, contractId, target, path, changes) {
     const predecessor = gitObjectIdForSnapshot(target.expectedOid);
     const candidate = gitObjectIdForSnapshot(target.newOid);
     const observation = { repository, contractId, target, path, predecessor, candidate, changes };
-    let dryRunError;
     try {
         await runGit(repository, ["-C", path, "read-tree", "--dry-run", "-m", "-u", predecessor, candidate]);
     }
     catch (error) {
         if (!(error instanceof GitPlumbingError) || repository.signal?.aborted === true)
             throw error;
-        dryRunError = error;
+        return null;
     }
     const scopes = await destructionScopes(path, changes.writes);
-    if (dryRunError !== undefined) {
-        const refusal = await dryRunRefusal(observation, scopes);
-        if (refusal !== null)
-            return refusal;
-        throw dryRunError;
-    }
-    return await untrackedRefusalWithinScopes(observation, scopes, true);
+    return await untrackedRefusalWithinScopes(observation, scopes);
 }
 export async function acquireTargetPlacementFence(repository, target) {
     const locator = gitRefLocator(target);
@@ -261,6 +248,25 @@ export async function observeTargetPlacement(repository, input, changes) {
     }
     return { kind: "ready", arms };
 }
+export const auditTargetAnswerSchema = z.union([
+    z
+        .object({
+        kind: z.literal("placeable"),
+        ref: z.string().refine((value) => value.trim() !== ""),
+        head: snapshotIdSchema,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("moved"),
+        ref: z.string().refine((value) => value.trim() !== ""),
+        expected: snapshotIdSchema,
+        observed: snapshotIdSchema.nullable(),
+    })
+        .strict(),
+    z.object({ kind: z.literal("refused"), refusal: checkoutNotFollowableRefusalSchema }).strict(),
+    z.object({ kind: z.literal("failed"), diagnostic: z.string().refine((value) => value.trim() !== "") }).strict(),
+]);
 /** Adjudicate the complete post-Verification audit target answer without placing. */
 export async function adjudicateAuditTarget(repository, input) {
     const ref = input.coordinates.target;
@@ -297,17 +303,20 @@ export async function prepareTargetPlacement(repository, state, target, changes)
         ? observation
         : { kind: "prepared", placement: { target, arms: observation.arms } };
 }
-export async function followTargetPlacement(repository, prepared) {
+export async function followTargetPlacement(repository, prepared, onPhysical) {
     const effects = [];
     const lag = [];
     const predecessor = gitObjectIdForSnapshot(prepared.target.expectedOid);
     const candidate = gitObjectIdForSnapshot(prepared.target.newOid);
     for (const arm of prepared.arms) {
+        const beforeEffects = effects.length, beforeLag = lag.length;
         try {
             await 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) {
+            if (!(error instanceof GitPlumbingError))
+                throw error;
             lag.push({
                 kind: "target-checkout-retained",
                 path: arm.path,
@@ -315,6 +324,7 @@ export async function followTargetPlacement(repository, prepared) {
                 diagnostic: diagnostic(error),
             });
         }
+        onPhysical?.({ effects: effects.slice(beforeEffects), lag: lag.slice(beforeLag) });
     }
     return { effects, lag };
 }
@@ -377,7 +387,7 @@ async function recoverCheckout(input) {
     ]);
     return "recovered";
 }
-export async function recoverTargetPlacement(repository, state) {
+export async function recoverTargetPlacement(repository, state, onPhysical) {
     const target = state.coordinates.target;
     const delivery = state.delivery;
     if (state.terminal?.kind !== "claimed" || target === undefined || delivery === null)
@@ -393,6 +403,7 @@ export async function recoverTargetPlacement(repository, state) {
     const effects = [];
     const lag = [];
     for (const worktree of worktrees) {
+        const beforeEffects = effects.length, beforeLag = lag.length;
         try {
             const recovery = await recoverCheckout({
                 repository,
@@ -404,6 +415,7 @@ export async function recoverTargetPlacement(repository, state) {
             });
             if (recovery === "retained") {
                 lag.push(recoveryLag(worktree.path, target, "target checkout entries are neither predecessor nor candidate"));
+                onPhysical?.({ effects: [], lag: lag.slice(beforeLag) });
                 continue;
             }
             if (recovery === "recovered") {
@@ -411,8 +423,11 @@ export async function recoverTargetPlacement(repository, state) {
             }
         }
         catch (error) {
+            if (!(error instanceof GitPlumbingError))
+                throw error;
             lag.push(recoveryLag(worktree.path, target, diagnostic(error)));
         }
+        onPhysical?.({ effects: effects.slice(beforeEffects), lag: lag.slice(beforeLag) });
     }
     return { effects, lag };
 }

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

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import type { Preparation } from "../core/decide.js";
 import type { ActorId, ContractCoordinates, ContractId, SnapshotId } from "../core/facts/types.js";
 import { type GitObjectId } from "./identity.js";
@@ -12,34 +13,42 @@ export type TenderCaptureCoordinates = Readonly<{
     /** Opt-in real-index UU refusal. Omit or false when authorized capture must read current worktree bytes. */
     rejectUnmerged?: boolean;
 }>;
-export type WorktreeMissingRefusal = Readonly<{
-    kind: "worktree-missing";
-    contractId: ContractId;
-}>;
-export type TenderCaptureRefusal = WorktreeMissingRefusal | Readonly<{
-    kind: "unmerged-paths";
-    contractId: ContractId;
-    paths: readonly string[];
-}>;
-export type WorkspaceDirtyDelta = Readonly<{
-    staged: readonly string[];
-    unstaged: readonly string[];
-    untracked: readonly string[];
-    shortStat: Readonly<{
-        filesChanged: number;
-        insertions: number;
-        deletions: number;
-    }>;
-}>;
-export type DirtyWorkspaceRefusal = Readonly<{
-    kind: "dirty-workspace";
-    contractId: ContractId;
-    staged: readonly string[];
-    unstaged: readonly string[];
-    untracked: readonly string[];
-    submodules: readonly string[];
-    shortStat: WorkspaceDirtyDelta["shortStat"];
-}>;
+export declare const worktreeMissingRefusalSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"worktree-missing">;
+    contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+}, z.core.$strict>;
+type WorktreeMissingRefusal = z.infer<typeof worktreeMissingRefusalSchema>;
+export declare const unmergedPathsRefusalSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"unmerged-paths">;
+    contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+    paths: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type TenderCaptureRefusal = WorktreeMissingRefusal | z.infer<typeof unmergedPathsRefusalSchema>;
+export declare const workspaceDirtyDeltaSchema: z.ZodObject<{
+    staged: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    unstaged: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    untracked: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    shortStat: z.ZodObject<{
+        filesChanged: z.ZodNumber;
+        insertions: z.ZodNumber;
+        deletions: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+type WorkspaceDirtyDelta = z.infer<typeof workspaceDirtyDeltaSchema>;
+export declare const dirtyWorkspaceRefusalSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"dirty-workspace">;
+    contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+    staged: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    unstaged: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    untracked: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    submodules: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    shortStat: z.ZodObject<{
+        filesChanged: z.ZodNumber;
+        insertions: z.ZodNumber;
+        deletions: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type DirtyWorkspaceRefusal = z.infer<typeof dirtyWorkspaceRefusalSchema>;
 export type TenderCapture = Readonly<{
     tree: GitObjectId;
     head: SnapshotId;

package/build/src/git/tender.js

@@ -1,8 +1,47 @@
+import { contractIdSchema } from "./identity.js";
+import { z } from "zod";
 import { access } from "node:fs/promises";
 import { gitObjectIdForSnapshot, mintSnapshotId } from "./identity.js";
 import { decodeGitNumstat, registeredWorktreePaths } from "./repository.js";
 import { GitPlumbingError, runGit, runGitWithEnvironment } from "./process.js";
 import { captureWorkspaceTree, unmergedWorkspacePaths, workspaceMergeHead, worktreePath } from "./workspace.js";
+export const worktreeMissingRefusalSchema = z
+    .object({ kind: z.literal("worktree-missing"), contractId: contractIdSchema })
+    .strict();
+export const unmergedPathsRefusalSchema = z
+    .object({
+    kind: z.literal("unmerged-paths"),
+    contractId: contractIdSchema,
+    paths: z.array(z.string().refine((value) => value.trim() !== "")).readonly(),
+})
+    .strict();
+export const workspaceDirtyDeltaSchema = z
+    .object({
+    staged: z.array(z.string()).readonly(),
+    unstaged: z.array(z.string()).readonly(),
+    untracked: z.array(z.string()).readonly(),
+    shortStat: z
+        .object({ filesChanged: z.number().int(), insertions: z.number().int(), deletions: z.number().int() })
+        .strict(),
+})
+    .strict();
+export const dirtyWorkspaceRefusalSchema = z
+    .object({
+    kind: z.literal("dirty-workspace"),
+    contractId: contractIdSchema,
+    staged: z.array(z.string().refine((value) => value.trim() !== "")).readonly(),
+    unstaged: z.array(z.string().refine((value) => value.trim() !== "")).readonly(),
+    untracked: z.array(z.string().refine((value) => value.trim() !== "")).readonly(),
+    submodules: z.array(z.string().refine((value) => value.trim() !== "")).readonly(),
+    shortStat: z
+        .object({
+        filesChanged: z.number().int().nonnegative(),
+        insertions: z.number().int().nonnegative(),
+        deletions: z.number().int().nonnegative(),
+    })
+        .strict(),
+})
+    .strict();
 async function workspaceExists(repository, path) {
     const exists = await access(path).then(() => true, () => false);
     return exists && (await registeredWorktreePaths(repository)).includes(path);

package/build/src/git/terminal-reconcile.js

@@ -25,7 +25,9 @@ async function removeTerminalWorktree(repository, topology, path) {
     try {
         await runGit(repository, ["worktree", "remove", ...(present ? ["--force"] : []), path]);
     }
-    catch {
+    catch (error) {
+        if (!(error instanceof GitPlumbingError))
+            throw error;
         return { effect: { kind: "worktree", path, action: "unchanged" }, retained: true };
     }
     topology.paths.delete(path);
@@ -112,10 +114,10 @@ function fromPrimaryWorktree(repository) {
 function complete(effects = [], lag = [], hookRuns = []) {
     return hookRuns.length === 0 ? { effects, lag } : { effects, lag, hookRuns };
 }
-function retainTerminalWorktree(path, retainedLag, { effects, lag, hookRuns }) {
-    effects.push({ kind: "worktree", path, action: "unchanged" });
-    lag.push(retainedLag);
-    return complete(effects, lag, hookRuns);
+function retainTerminalWorktree(path, retainedLag, acc) {
+    acc.recordEffect({ kind: "worktree", path, action: "unchanged" });
+    acc.recordLag(retainedLag);
+    return complete(acc.effects, acc.lag, acc.hookRuns);
 }
 async function terminalSealExpectations(channel, state) {
     const snapshots = terminalSealSnapshots(state);
@@ -144,11 +146,7 @@ async function removeSealedTerminalWorktree({ repository, topology, path, state,
                 snapshot,
                 retention: "ephemeral",
             };
-            const existing = acc.effects.findIndex((item) => item.kind === "recovery-snapshot");
-            if (existing < 0)
-                acc.effects.push(effect);
-            else
-                acc.effects[existing] = effect;
+            acc.recordEffect(effect);
             return { snapshot, workspace };
         };
         const before = await observeTerminalWorkspace(repository, path, expected);
@@ -186,7 +184,7 @@ async function removeSealedTerminalWorktree({ repository, topology, path, state,
     if (removal.retained)
         return retainTerminalWorktree(path, { kind: "worktree-retained", path }, acc);
     if (removal.effect !== undefined)
-        acc.effects.push(removal.effect);
+        acc.recordEffect(removal.effect);
     return null;
 }
 async function targetCustodyForClaimedIntegration(repository, state, integration) {
@@ -204,19 +202,19 @@ function sealedTree(expected, snapshot) {
         throw new Error(`terminal seal tree was not resolved: ${snapshot}`);
     return tree;
 }
-async function releaseTerminalCustody({ repository, state, resolveSeal, ref, pin, acc: { effects }, }) {
+async function releaseTerminalCustody({ repository, state, resolveSeal, ref, pin, acc, }) {
     const [deliveryRef, candidatePin] = await Promise.all([readRef(repository, ref), readRef(repository, pin)]);
     if (deliveryRef === null && candidatePin === null)
         return;
     if (state.delivery === null) {
         const custodian = await snapshotCustodian(repository, state.coordinates.start);
         if (deliveryRef !== null) {
-            effects.push(custodian === null
+            acc.recordEffect(custodian === null
                 ? retainedRefEffect(ref, deliveryRef)
                 : await removeRefWithCustody(repository, ref, custodian.ref, custodian.oid));
         }
         if (candidatePin !== null)
-            effects.push(await removeRef(repository, pin));
+            acc.recordEffect(await removeRef(repository, pin));
         return;
     }
     const tender = state.delivery.data.tenderSnapshot;
@@ -224,29 +222,29 @@ async function releaseTerminalCustody({ repository, state, resolveSeal, ref, pin
     const target = await targetCustodyForClaimedIntegration(repository, state, integration);
     if (deliveryRef !== null && target !== null) {
         if (tender === integration) {
-            effects.push(await removeRefWithCustody(repository, ref, target.ref, target.oid));
+            acc.recordEffect(await removeRefWithCustody(repository, ref, target.ref, target.oid));
         }
         else {
             const expected = await resolveSeal();
             if (sealedTree(expected, tender) === sealedTree(expected, integration)) {
-                effects.push(await removeRefWithCustody(repository, ref, target.ref, target.oid));
+                acc.recordEffect(await removeRefWithCustody(repository, ref, target.ref, target.oid));
             }
             else {
-                effects.push(retainedRefEffect(ref, deliveryRef));
+                acc.recordEffect(retainedRefEffect(ref, deliveryRef));
             }
         }
     }
     else if (deliveryRef !== null) {
-        effects.push(retainedRefEffect(ref, deliveryRef));
+        acc.recordEffect(retainedRefEffect(ref, deliveryRef));
     }
     if (candidatePin !== null) {
         if (target !== null || (tender === integration && deliveryRef !== null)) {
-            effects.push(target !== null
+            acc.recordEffect(target !== null
                 ? await removeRefWithCustody(repository, pin, target.ref, target.oid)
                 : await removeRefWithCustody(repository, pin, ref, tender));
         }
         else {
-            effects.push(retainedRefEffect(pin, candidatePin));
+            acc.recordEffect(retainedRefEffect(pin, candidatePin));
         }
     }
 }
@@ -261,13 +259,13 @@ export async function reconcileTerminalManagedWorktree({ repository, channel, ho
         return complete(acc.effects, acc.lag, acc.hookRuns);
     }
     const expected = await resolveSeal();
-    acc.effects.push(await updateRef(primary, ref, state.delivery?.data.tenderSnapshot ?? state.coordinates.start));
+    acc.recordEffect(await updateRef(primary, ref, state.delivery?.data.tenderSnapshot ?? state.coordinates.start));
     if (state.delivery !== null) {
-        acc.effects.push(await updateRef(primary, pin, state.currentIntegration?.snapshot ?? state.delivery.data.integration.snapshot));
+        acc.recordEffect(await updateRef(primary, pin, state.currentIntegration?.snapshot ?? state.delivery.data.integration.snapshot));
     }
     if (retainTerminalWorktree === true) {
         if (topology.paths.has(path) && (await pathExists(path))) {
-            acc.effects.push({ kind: "worktree", path, action: "unchanged" });
+            acc.recordEffect({ kind: "worktree", path, action: "unchanged" });
         }
         return complete(acc.effects, acc.lag);
     }

package/build/src/git/terminal-seal.d.ts

@@ -1,14 +1,16 @@
+import { z } from "zod";
 import type { ContractState, SnapshotId } from "../core/facts/types.js";
 import { type GitObjectId } from "./identity.js";
 import type { GitOid } from "./repository.js";
 import { type GitRepository } from "./process.js";
 import { captureWorkspaceTree } from "./workspace.js";
-export type UnsealedBytes = Readonly<{
-    kind: "unsealed-bytes";
-    path: string;
-    paths: readonly string[];
-    head?: SnapshotId;
-}>;
+export declare const unsealedBytesSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"unsealed-bytes">;
+    path: z.ZodString;
+    paths: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    head: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<SnapshotId, string>>>;
+}, z.core.$strict>;
+type UnsealedBytes = z.infer<typeof unsealedBytesSchema>;
 export type TerminalSealExpectations = Readonly<{
     heads: readonly SnapshotId[];
     trees: readonly GitObjectId[];

package/build/src/git/terminal-seal.js

@@ -1,6 +1,16 @@
+import { mintedSnapshotInputSchema } from "./identity.js";
+import { z } from "zod";
 import { gitObjectId, gitObjectIdForSnapshot, mintSnapshotId } from "./identity.js";
 import { runGit } from "./process.js";
 import { captureWorkspaceTree } from "./workspace.js";
+export const unsealedBytesSchema = z
+    .object({
+    kind: z.literal("unsealed-bytes"),
+    path: z.string().refine((value) => value.trim() !== ""),
+    paths: z.array(z.string().refine((value) => value.trim() !== "")).readonly(),
+    head: mintedSnapshotInputSchema.optional(),
+})
+    .strict();
 export function terminalSealSnapshots(state) {
     return [
         ...new Set([

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

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import type { ContractId, SnapshotId } from "../core/facts/types.js";
 import { type GitObjectId } from "./identity.js";
 import { type GitRepository } from "./process.js";
@@ -47,11 +48,12 @@ export type WorkspaceChangeCounts = Readonly<{
     untracked: number;
     submodules: number;
 }>;
-export type ConflictRecovery = Readonly<{
-    materialize: "deliver --materialize-conflict --include-dirty";
-    deliver: "deliver --include-dirty";
-    staging: "not-required";
-}>;
+export declare const conflictRecoverySchema: z.ZodObject<{
+    materialize: z.ZodLiteral<"deliver --materialize-conflict --include-dirty">;
+    deliver: z.ZodLiteral<"deliver --include-dirty">;
+    staging: z.ZodLiteral<"not-required">;
+}, z.core.$strict>;
+type ConflictRecovery = z.infer<typeof conflictRecoverySchema>;
 export declare const conflictRecovery: ConflictRecovery;
 export type ContractWorkspaceMerge = Readonly<{
     head: SnapshotId;
@@ -73,16 +75,27 @@ export type ContractWorkspaceObservation = Readonly<{
     kind: "failed";
     diagnostic: string;
 }>;
-export type ContractTargetLag = Readonly<{
-    kind: "counted";
-    behind: number;
-    subject?: ContractWorkspaceLocation;
-}> | Readonly<{
-    kind: "unknown";
-    subject?: ContractWorkspaceLocation;
-}> | Readonly<{
-    kind: "none";
-}>;
+export declare const worktreeWorkspaceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"worktree">;
+    path: z.ZodString;
+}, z.core.$strict>;
+export declare const contractTargetLagSchema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"none">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"unknown">;
+    subject: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"worktree">;
+        path: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"counted">;
+    behind: z.ZodNumber;
+    subject: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"worktree">;
+        path: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>]>;
+export type ContractTargetLag = z.infer<typeof contractTargetLagSchema>;
 export declare function observeWorkspace(repository: GitRepository, location: ContractWorkspaceLocation, workspace: string): Promise<ContractWorkspaceObservation>;
 export declare function observeTargetLag(repository: GitRepository, workspace: string, head: SnapshotId | null | undefined): Promise<ContractTargetLag>;
 /** Capture tracked and untracked workspace bytes without changing its real index. */
@@ -114,3 +127,4 @@ export declare function retireConflictHandoff(repository: GitRepository, input:
     workspace: string;
     consume: boolean;
 }>): Promise<HandoffRetirement>;
+export {};

package/build/src/git/workspace.js

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import { access, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
@@ -193,11 +194,32 @@ export async function workspaceMergeStatePresent(repository, workspace) {
 export async function unmergedWorkspacePaths(repository, workspace) {
     return (await workspaceStatus(repository, workspace)).unmergedPaths;
 }
+export const conflictRecoverySchema = z
+    .object({
+    materialize: z.literal("deliver --materialize-conflict --include-dirty"),
+    deliver: z.literal("deliver --include-dirty"),
+    staging: z.literal("not-required"),
+})
+    .strict();
 export const conflictRecovery = Object.freeze({
     materialize: "deliver --materialize-conflict --include-dirty",
     deliver: "deliver --include-dirty",
     staging: "not-required",
 });
+export const worktreeWorkspaceSchema = z
+    .object({ kind: z.literal("worktree"), path: z.string().refine((value) => value.trim() !== "") })
+    .strict();
+export const contractTargetLagSchema = z.union([
+    z.object({ kind: z.literal("none") }).strict(),
+    z.object({ kind: z.literal("unknown"), subject: worktreeWorkspaceSchema.optional() }).strict(),
+    z
+        .object({
+        kind: z.literal("counted"),
+        behind: z.number().int().nonnegative(),
+        subject: worktreeWorkspaceSchema.optional(),
+    })
+        .strict(),
+]);
 function countsOf(changes) {
     return {
         staged: changes.staged.length,
@@ -215,7 +237,9 @@ export async function observeWorkspace(repository, location, workspace) {
         const merge = head === undefined ? null : { head, unmergedPaths: status.unmergedPaths };
         return { kind: dirty ? "dirty" : "clean", location, counts, merge };
     }
-    catch {
+    catch (error) {
+        if (!(error instanceof GitPlumbingError))
+            throw error;
         return { kind: "unavailable", location };
     }
 }
@@ -233,7 +257,9 @@ export async function observeTargetLag(repository, workspace, head) {
             return { kind: "unknown", subject };
         return { kind: "counted", behind: Number(text), subject };
     }
-    catch {
+    catch (error) {
+        if (!(error instanceof GitPlumbingError))
+            throw error;
         return { kind: "unknown", subject };
     }
 }