@astrosheep/keiyaku 4.5.29 → 4.6.2

package/build/src/protocol/completion.d.ts

@@ -1,32 +1,265 @@
-import type { ActorId, SnapshotId } from "../core/facts/types.js";
+import { z } from "zod";
+import type { ActorId, ContractId, EntryUlid } from "../core/facts/types.js";
 import type { GitRepository } from "../git/process.js";
 import type { GitDecodeChannel } from "../git/read-observation.js";
-import { type CurrentVerifiedAttestation } from "./intent.js";
-import { type ContractCheckpoint, type ExecutionProgress, type ExecutionStop } from "./progress.js";
+import { type ContractCheckpoint, type ProtocolProgress, type ExecutionStop } from "./progress.js";
 import type { DocumentDerivation, PlacementStop, VerificationStop } from "./operations.js";
-export type CandidateCompletion = Readonly<{
-    integration: SnapshotId;
-    /** The reference this placement advanced and the head it advanced from, both observed at completion time. */
-    predecessor?: SnapshotId;
-    target?: string;
-    verification?: Readonly<{
-        mode: "ran" | "reused";
-        verdict: "satisfied" | "unsatisfied";
-    }>;
-}>;
-/** Candidate conclusions only. Invocation-owned receipts and cleanup live in progress. */
-export type CompletionEvidence = Readonly<{
-    completion?: CandidateCompletion;
-    verification?: VerificationStop;
-    verificationReuse?: CurrentVerifiedAttestation;
-    verificationSummary?: string;
-    placement?: PlacementStop;
-}>;
+declare const candidateCompletionSchema: z.ZodObject<{
+    integration: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").SnapshotId, string>>;
+    predecessor: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").SnapshotId, string>>>;
+    target: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodObject<{
+        deletions: z.ZodNumber;
+        filesChanged: z.ZodNumber;
+        insertions: z.ZodNumber;
+    }, z.core.$strict>>;
+    verification: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            reused: "reused";
+            ran: "ran";
+        }>;
+        verdict: z.ZodEnum<{
+            satisfied: "satisfied";
+            unsatisfied: "unsatisfied";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CandidateCompletion = z.infer<typeof candidateCompletionSchema>;
+export declare const completionEvidenceSchema: z.ZodObject<{
+    completion: z.ZodOptional<z.ZodObject<{
+        integration: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").SnapshotId, string>>;
+        predecessor: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").SnapshotId, string>>>;
+        target: z.ZodOptional<z.ZodString>;
+        scope: z.ZodOptional<z.ZodObject<{
+            deletions: z.ZodNumber;
+            filesChanged: z.ZodNumber;
+            insertions: z.ZodNumber;
+        }, z.core.$strict>>;
+        verification: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                reused: "reused";
+                ran: "ran";
+            }>;
+            verdict: z.ZodEnum<{
+                satisfied: "satisfied";
+                unsatisfied: "unsatisfied";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    verification: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        refusal: z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodEnum<{
+                terminal: "terminal";
+                "contract-missing": "contract-missing";
+            }>;
+            contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"verification-declaration-invalid">;
+            contractId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>>;
+        }, z.core.$strict>]>;
+    }, z.core.$strict>, z.ZodObject<{
+        retry: z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodEnum<{
+                exhausted: "exhausted";
+                collision: "collision";
+            }>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"publication-failed">;
+            diagnostic: z.ZodString;
+        }, z.core.$strict>]>;
+    }, z.core.$strict>, z.ZodUnion<readonly [z.ZodObject<{
+        stdout: z.ZodOptional<z.ZodString>;
+        stderr: z.ZodOptional<z.ZodString>;
+        truncated: z.ZodOptional<z.ZodLiteral<true>>;
+        failure: z.ZodEnum<{
+            cancelled: "cancelled";
+            "unknown-exit": "unknown-exit";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        stdout: z.ZodOptional<z.ZodString>;
+        stderr: z.ZodOptional<z.ZodString>;
+        truncated: z.ZodOptional<z.ZodLiteral<true>>;
+        failure: z.ZodEnum<{
+            "spawn-error": "spawn-error";
+            "candidate-unavailable": "candidate-unavailable";
+        }>;
+        diagnostic: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        stdout: z.ZodOptional<z.ZodString>;
+        stderr: z.ZodOptional<z.ZodString>;
+        truncated: z.ZodOptional<z.ZodLiteral<true>>;
+        failure: z.ZodLiteral<"environment-failure">;
+        diagnostic: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        stdout: z.ZodOptional<z.ZodString>;
+        stderr: z.ZodOptional<z.ZodString>;
+        truncated: z.ZodOptional<z.ZodLiteral<true>>;
+        failure: z.ZodLiteral<"environment-failure">;
+        name: z.ZodString;
+        detail: z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"exit">;
+            code: z.ZodNumber;
+            stdout: z.ZodString;
+            stderr: z.ZodString;
+            truncated: z.ZodBoolean;
+        }, z.core.$strict>, z.ZodObject<{
+            stdout: z.ZodOptional<z.ZodString>;
+            stderr: z.ZodOptional<z.ZodString>;
+            truncated: z.ZodOptional<z.ZodBoolean>;
+            kind: z.ZodLiteral<"timeout">;
+        }, z.core.$strict>, z.ZodObject<{
+            stdout: z.ZodOptional<z.ZodString>;
+            stderr: z.ZodOptional<z.ZodString>;
+            truncated: z.ZodOptional<z.ZodBoolean>;
+            kind: z.ZodLiteral<"unknown-exit">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"spawn-error">;
+            diagnostic: z.ZodString;
+        }, z.core.$strict>]>;
+    }, z.core.$strict>]>]>>;
+    verificationReuse: z.ZodOptional<z.ZodObject<{
+        entry: z.ZodPipe<z.ZodString, z.ZodTransform<EntryUlid, string>>;
+        verdict: z.ZodEnum<{
+            satisfied: "satisfied";
+            unsatisfied: "unsatisfied";
+        }>;
+        summary: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    verificationSubject: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            reused: "reused";
+            ran: "ran";
+        }>;
+        verdict: z.ZodEnum<{
+            satisfied: "satisfied";
+            unsatisfied: "unsatisfied";
+        }>;
+        snapshot: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").SnapshotId, string>>;
+    }, z.core.$strict>>;
+    verificationSummary: z.ZodOptional<z.ZodString>;
+    placement: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        refusal: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodEnum<{
+                terminal: "terminal";
+                "contract-missing": "contract-missing";
+                "delivery-missing": "delivery-missing";
+            }>;
+            contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"gates-unsatisfied">;
+            contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+            unmet: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                gate: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").Gate, string>>;
+                current: z.ZodUnion<readonly [z.ZodObject<{
+                    kind: z.ZodLiteral<"missing">;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"attested">;
+                    verdict: z.ZodEnum<{
+                        satisfied: "satisfied";
+                        unsatisfied: "unsatisfied";
+                    }>;
+                    at: z.ZodString;
+                    summary: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"stale">;
+                    priorVerdict: z.ZodEnum<{
+                        satisfied: "satisfied";
+                        unsatisfied: "unsatisfied";
+                    }>;
+                    reason: z.ZodOptional<z.ZodObject<{
+                        kind: z.ZodLiteral<"candidate-content-changed">;
+                        target: z.ZodOptional<z.ZodString>;
+                        previousChange: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").ChangeId, string>>;
+                        currentChange: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").ChangeId, string>>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>]>;
+            }, z.core.$strict>>>;
+            target: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"prerequisites-unsatisfied">;
+            contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+            unmet: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+                state: z.ZodEnum<{
+                    abandoned: "abandoned";
+                    missing: "missing";
+                    active: "active";
+                }>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>]>, 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.ZodUnion<readonly [z.ZodPipe<z.ZodObject<{
+            kind: z.ZodLiteral<"integration-failed">;
+            contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+            reason: z.ZodEnum<{
+                "not-based-on-target": "not-based-on-target";
+                "unrelated-histories": "unrelated-histories";
+                conflict: "conflict";
+            }>;
+            targetHead: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").SnapshotId, string>>;
+            conflictPaths: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        }, z.core.$strict>, z.ZodTransform<{
+            kind: "integration-failed";
+            contractId: ContractId;
+            reason: "not-based-on-target" | "unrelated-histories" | "conflict";
+            targetHead: import("../core/facts/types.js").SnapshotId;
+        } & {
+            conflictPaths?: readonly string[];
+        }, {
+            kind: "integration-failed";
+            contractId: ContractId;
+            reason: "not-based-on-target" | "unrelated-histories" | "conflict";
+            targetHead: import("../core/facts/types.js").SnapshotId;
+            conflictPaths?: readonly string[] | undefined;
+        }>>, z.ZodObject<{
+            kind: z.ZodLiteral<"integration-unsupported">;
+            contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+            requiredGit: z.ZodLiteral<"2.38">;
+        }, z.core.$strict>]>, z.ZodObject<{
+            kind: z.ZodLiteral<"target-missing">;
+            contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+        }, z.core.$strict>]>;
+    }, z.core.$strict>, z.ZodObject<{
+        retry: z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodEnum<{
+                exhausted: "exhausted";
+                collision: "collision";
+            }>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"publication-failed">;
+            diagnostic: z.ZodString;
+        }, z.core.$strict>]>;
+    }, z.core.$strict>, z.ZodObject<{
+        failure: z.ZodLiteral<"target-placement-failed">;
+        diagnostic: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        failure: z.ZodLiteral<"target-moved">;
+        contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+        target: z.ZodString;
+        integratedAt: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").SnapshotId, string>>;
+        observed: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").SnapshotId, string>>>;
+        attempts: z.ZodNumber;
+        observedTreeEqualsCandidate: z.ZodBoolean;
+    }, z.core.$strict>, z.ZodObject<{
+        failure: z.ZodLiteral<"target-moved">;
+        contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
+        target: z.ZodString;
+        expected: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").SnapshotId, string>>;
+        observed: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").SnapshotId, string>>>;
+        observedTreeEqualsCandidate: z.ZodBoolean;
+    }, z.core.$strict>]>>;
+}, z.core.$strict>;
+export type CompletionEvidence = z.infer<typeof completionEvidenceSchema>;
 export type CompletionInput = Readonly<{
     channel: GitDecodeChannel;
     repository: GitRepository;
     checkpoint: ContractCheckpoint;
-    progress: ExecutionProgress;
+    progress: ProtocolProgress;
     start: "verification" | "placement";
     deriveDocument(state: ContractCheckpoint["state"]): DocumentDerivation;
     actor?: ActorId;
@@ -46,3 +279,4 @@ export type CompletionResult = Readonly<{
 }>;
 /** Advance one contract. The trigger owns the leading act; this node owns no other contract. */
 export declare function completeCandidate(input: CompletionInput): Promise<CompletionResult>;
+export {};

package/build/src/protocol/completion.js

@@ -1,10 +1,41 @@
+import { z } from "zod";
+import { snapshotIdSchema, verdictSchema, verificationStopSchema, placementStopSchema } from "./operations.js";
+import { verificationReuseSchema } from "./intent.js";
+import { deliveryDiffScopeSchema, readDeliveryScope } from "../git/integration.js";
 import { currentVerifiedAttestation, verifyDelivery } from "./intent.js";
 import { admitPlacement, observeTargetPlacement } from "./placement.js";
 import { reintegrateOperation } from "./reintegrate.js";
-import { contractCheckpoint, executionStop, } from "./progress.js";
+import { contractCheckpoint, executionStop, isOperationalFailure, isOperationalStop, } from "./progress.js";
 import { placementStop, timestamp, unpackVerificationOutcome } from "./operations.js";
 import { VERIFIED } from "../verification/declaration.js";
 const MAX_REINTEGRATION_CYCLES = 3;
+const verdictProvenanceSchema = z.object({ mode: z.enum(["ran", "reused"]), verdict: verdictSchema }).strict();
+const candidateCompletionSchema = z
+    .object({
+    integration: snapshotIdSchema,
+    predecessor: snapshotIdSchema.optional(),
+    target: z
+        .string()
+        .refine((value) => value.trim() !== "")
+        .optional(),
+    scope: deliveryDiffScopeSchema.omit({ paths: true }).optional(),
+    verification: verdictProvenanceSchema.optional(),
+})
+    .strict();
+const verificationSubjectSchema = verdictProvenanceSchema.extend({ snapshot: snapshotIdSchema }).strict();
+export const completionEvidenceSchema = z
+    .object({
+    completion: candidateCompletionSchema.optional(),
+    verification: verificationStopSchema.optional(),
+    verificationReuse: verificationReuseSchema.optional(),
+    verificationSubject: verificationSubjectSchema.optional(),
+    verificationSummary: z
+        .string()
+        .refine((value) => value.trim() !== "")
+        .optional(),
+    placement: placementStopSchema.optional(),
+})
+    .strict();
 function reintegrationStop(result) {
     if (result.kind === "placement-failed")
         return { failure: "target-placement-failed", diagnostic: result.diagnostic };
@@ -21,14 +52,20 @@ async function verifyCurrentCandidate(input, cursor) {
         throw new Error("delivery completion requires an integration snapshot");
     cursor.evidence = {};
     cursor.ran = undefined;
+    input.progress.recordCandidate(state.id, cursor.evidence);
     const current = currentVerifiedAttestation(state);
     if (current !== undefined) {
-        cursor.evidence = { verificationReuse: current };
+        cursor.evidence = {
+            verificationReuse: current,
+            verificationSubject: { snapshot, mode: "reused", verdict: current.verdict },
+        };
+        input.progress.recordCandidate(state.id, cursor.evidence);
         return;
     }
     const declaration = input.deriveDocument(state).verification;
     if (declaration.kind === "refused") {
         cursor.evidence = { verification: { refusal: declaration.refusal } };
+        input.progress.recordCandidate(state.id, cursor.evidence);
         return;
     }
     const result = await verifyDelivery({
@@ -51,12 +88,20 @@ async function verifyCurrentCandidate(input, cursor) {
         input.progress.recordResidue(state.id, verified.admission);
         cursor.ran = verified.admission.facts.find((fact) => fact.kind === "attestation" && fact.data.gate === "verified")?.entry;
     }
+    const subject = verified.reuse !== undefined
+        ? { snapshot, mode: "reused", verdict: verified.reuse.verdict }
+        : verified.counts === undefined
+            ? undefined
+            : { snapshot, mode: "ran", verdict: verified.counts.verdict };
     cursor.evidence = {
+        ...(verified.reuse === undefined ? {} : { verificationReuse: verified.reuse }),
+        ...(subject === undefined ? {} : { verificationSubject: subject }),
         ...(verified.stop === undefined ? {} : { verification: verified.stop }),
         ...(verified.counts?.verdict !== "unsatisfied" || verified.counts.summary === undefined
             ? {}
             : { verificationSummary: verified.counts.summary }),
     };
+    input.progress.recordCandidate(state.id, cursor.evidence);
 }
 async function observeCandidateTarget(input, cursor) {
     const target = cursor.checkpoint.state.coordinates.target;
@@ -75,16 +120,25 @@ async function observeCandidateTarget(input, cursor) {
         return observed.kind === "refused" ? { refusal: observed.refusal } : undefined;
     }
     catch (error) {
-        return { failure: "target-placement-failed", diagnostic: error instanceof Error ? error.message : String(error) };
+        if (!isOperationalFailure(error))
+            throw error;
+        return { failure: "target-placement-failed", diagnostic: error.message };
     }
 }
-function completedResult(cursor) {
+async function completedResult(input, cursor) {
     const state = cursor.checkpoint.state;
     const integration = state.currentIntegration?.snapshot;
     if (integration === undefined)
         throw new Error("accepted placement requires its integration snapshot");
     const target = state.coordinates.target;
     const predecessor = state.currentIntegration?.predecessor;
+    // Movement and the completion base are known before this optional observation; a failed scope
+    // read must never erase an already-claimed candidate.
+    cursor.completion = {
+        integration,
+        ...(predecessor === undefined || target === undefined ? {} : { predecessor, target }),
+    };
+    input.progress.recordCompletion(state.id, cursor.completion);
     // Never attach a superseded run's verdict to the final integration.
     const current = currentVerifiedAttestation(state);
     const verification = current === undefined
@@ -93,17 +147,26 @@ function completedResult(cursor) {
             mode: cursor.ran === current.entry ? "ran" : "reused",
             verdict: current.verdict,
         };
-    const { verificationSummary: _oldSummary, verificationReuse: _oldReuse, ...evidence } = cursor.evidence;
+    cursor.completion = { ...cursor.completion, ...(verification === undefined ? {} : { verification }) };
+    input.progress.recordCompletion(state.id, cursor.completion);
+    const scope = predecessor === undefined ? undefined : await readDeliveryScope(input.repository, predecessor, integration, false);
+    const { verificationSummary: _oldSummary, verificationReuse: _oldReuse, verificationSubject: _oldSubject, ...evidence } = cursor.evidence;
+    const completion = {
+        integration,
+        ...(predecessor === undefined || target === undefined ? {} : { predecessor, target }),
+        ...(scope === undefined
+            ? {}
+            : { scope: { filesChanged: scope.filesChanged, insertions: scope.insertions, deletions: scope.deletions } }),
+        ...(verification === undefined ? {} : { verification }),
+    };
+    cursor.completion = completion;
+    input.progress.recordCompletion(state.id, completion);
     return {
         kind: "completed",
         checkpoint: cursor.checkpoint,
         evidence: {
             ...evidence,
-            completion: {
-                integration,
-                ...(predecessor === undefined || target === undefined ? {} : { predecessor, target }),
-                ...(verification === undefined ? {} : { verification }),
-            },
+            completion,
             ...(current === undefined || verification?.mode !== "reused" ? {} : { verificationReuse: current }),
             ...(current?.verdict !== "unsatisfied" || current.summary === undefined
                 ? {}
@@ -152,6 +215,14 @@ async function placeCurrentCandidate(input, cursor) {
     if (result.kind === "accepted") {
         cursor.checkpoint = contractCheckpoint(result);
         input.progress.recordResidue(result.state.id, result);
+        const acceptedIntegration = result.state.currentIntegration?.snapshot;
+        if (acceptedIntegration !== undefined) {
+            const acceptedPredecessor = result.state.currentIntegration?.predecessor;
+            input.progress.recordCompletion(result.state.id, {
+                integration: acceptedIntegration,
+                ...(acceptedPredecessor === undefined ? {} : { predecessor: acceptedPredecessor }),
+            });
+        }
     }
     return result;
 }
@@ -184,7 +255,7 @@ async function advanceCandidate(input, cursor) {
     let placement = await placeCurrentCandidate(input, cursor);
     for (let cycles = 0;; cycles += 1) {
         if (placement.kind === "accepted")
-            return completedResult(cursor);
+            return await completedResult(input, cursor);
         if (placement.kind !== "target-moved" || target === undefined || placement.observedTreeEqualsCandidate) {
             const stop = placementStop(placement);
             if (stop === undefined)
@@ -229,6 +300,8 @@ export async function completeCandidate(input) {
         return await advanceCandidate(input, cursor);
     }
     catch (error) {
+        if (!isOperationalStop(error, input.signal))
+            throw error;
         const contractId = input.checkpoint.state.id;
         const stop = executionStop(contractId, cursor.stage, error, input.signal);
         input.progress.recordStop(stop);
@@ -237,7 +310,22 @@ export async function completeCandidate(input) {
             cursor.checkpoint = admitted;
         // Only this invocation's confirmed claim can complete the node after a trailing failure.
         if (admitted?.state.terminal?.kind === "claimed" && input.progress.hasFact(admitted.state.terminal)) {
-            return completedResult(cursor);
+            if (cursor.completion === undefined) {
+                const integration = admitted.state.currentIntegration;
+                if (integration === null)
+                    throw error;
+                const target = admitted.state.coordinates.target;
+                cursor.completion = {
+                    integration: integration.snapshot,
+                    ...(target === undefined ? {} : { target, predecessor: integration.predecessor }),
+                };
+                input.progress.recordCompletion(contractId, cursor.completion);
+            }
+            return {
+                kind: "completed",
+                checkpoint: cursor.checkpoint,
+                evidence: { ...cursor.evidence, completion: cursor.completion },
+            };
         }
         return stoppedResult(cursor, stop);
     }

package/build/src/protocol/deliver.d.ts

@@ -1,32 +1,41 @@
-import { type ConflictRecovery } from "../git/workspace.js";
-import type { ActorId, ContractId, ContractState, DeliverData, EntryUlid, SnapshotId } from "../core/facts/types.js";
+import { z } from "zod";
+import { worktreeWorkspaceSchema } from "../git/workspace.js";
+import type { ActorId, ContractId, ContractState, DeliverData } from "../core/facts/types.js";
 import { type CurrentVerifiedAttestation } from "./intent.js";
 import type { LeadingOutcome } from "./outcome.js";
 import type { CompletionEvidence } from "./completion.js";
 import { type ManagedWorktreeAppointment } from "../workspace-place.js";
-import type { DeliveryPreparationRefusal, DocumentDerivation, IntentRefusal, MutationOperationInput } from "./operations.js";
+import type { DeliveryPreparationRefusal, DocumentDerivation, MutationOperationInput } from "./operations.js";
 type DeliveryIdentity = DeliverData;
 export type VerificationReuse = CurrentVerifiedAttestation;
-export type DeliverLeading = Readonly<{
-    kind: "already-admitted";
-    fact: EntryUlid;
-}>;
-export type DeliverValue = DeliveryIdentity & CompletionEvidence & Readonly<{
-    leading?: DeliverLeading;
-}>;
-export type AppointedWorkspace = Readonly<{
-    kind: "worktree";
-    path: string;
-}>;
-export type IntegrationConflictMaterialized = Readonly<{
-    kind: "integration-conflict-materialized";
-    targetHead: SnapshotId;
-    conflictPaths: readonly string[];
-    workspace: AppointedWorkspace;
-    handoffBase: SnapshotId;
-    recovery: ConflictRecovery;
+export declare const deliverLeadingSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "admitted-now": "admitted-now";
+        "already-admitted": "already-admitted";
+    }>;
+    fact: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").EntryUlid, string>>;
+}, z.core.$strict>;
+type DeliverLeading = z.infer<typeof deliverLeadingSchema>;
+type DeliverValue = DeliveryIdentity & CompletionEvidence & Readonly<{
+    leading: DeliverLeading;
 }>;
-export { decodeMaterializedConflict } from "./result-codec.js";
+export type AppointedWorkspace = z.infer<typeof worktreeWorkspaceSchema>;
+export declare const materializedConflictSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"integration-conflict-materialized">;
+    targetHead: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").SnapshotId, string>>;
+    conflictPaths: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    workspace: z.ZodObject<{
+        kind: z.ZodLiteral<"worktree">;
+        path: z.ZodString;
+    }, z.core.$strict>;
+    handoffBase: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").SnapshotId, string>>;
+    recovery: z.ZodObject<{
+        materialize: z.ZodLiteral<"deliver --materialize-conflict --include-dirty">;
+        deliver: z.ZodLiteral<"deliver --include-dirty">;
+        staging: z.ZodLiteral<"not-required">;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type IntegrationConflictMaterialized = z.infer<typeof materializedConflictSchema>;
 type DeliverOperationInput = MutationOperationInput & Readonly<{
     deriveDocument: (state: ContractState) => DocumentDerivation;
     message?: string;
@@ -36,6 +45,7 @@ type DeliverOperationInput = MutationOperationInput & Readonly<{
     overwrite?: boolean;
     signal?: AbortSignal;
 }>;
+type DeliverOperationRefusal = import("../core/verbs/deliver.js").DeliverRefusal | DeliveryPreparationRefusal | import("./operations.js").DeliverConflictRefusal | import("../verification/declaration.js").VerificationDeclarationRefusal;
 export declare function prepareDelivery(repository: import("../git/process.js").GitRepository, stage: Readonly<{
     contractId: ContractId;
     coordinates: ContractState["coordinates"];
@@ -56,4 +66,5 @@ export declare function prepareDelivery(repository: import("../git/process.js").
     kind: "refused";
     refusal: DeliveryPreparationRefusal;
 }>;
-export declare function admitDeliveryOperation(input: DeliverOperationInput): Promise<LeadingOutcome<DeliverValue, IntentRefusal> | IntegrationConflictMaterialized>;
+export declare function admitDeliveryOperation(input: DeliverOperationInput): Promise<LeadingOutcome<DeliverValue, DeliverOperationRefusal> | IntegrationConflictMaterialized>;
+export {};