@astrosheep/keiyaku 4.5.11 → 4.5.13

package/build/src/library/mutation.d.ts

@@ -1,13 +1,431 @@
-import type { ContractHead, ContractId, JournalEntry, SnapshotId } from "../core/facts/types.js";
+import { type ContractHead, type ContractId, type JournalEntry, type SnapshotId } from "../core/facts/types.js";
+import { type PrivateStateSeatCloseLag } from "../git/private-state-seat.js";
 import type { GitDecodeChannel } from "../git/read-observation.js";
 import type { ReconcileReport } from "../protocol/reconcile.js";
 import type { RepositoryScope } from "../protocol/operations.js";
 import type { IntentOutcome } from "../protocol/operations.js";
 import type { AcceptedObligations } from "../protocol/outcome.js";
-import { type SettlementReport } from "../settlement/settle.js";
+import type { SettlementReport } from "../settlement/settle.js";
 import type { TaskHolderAdmission } from "../settlement/holder.js";
 import type { WorktreeHooks } from "./configuration.js";
 import { type ReconcileCompletion } from "./reconcile.js";
+import { type AuditReport } from "../protocol/audit.js";
+import { type IntegrationConflictMaterialized } from "../protocol/deliver.js";
+import { type ReviewValue } from "../protocol/review.js";
+import { type ContinuationReport } from "./continuation.js";
+import { type DeliveryValue } from "./delivery.js";
+import type { KeiyakuRefused, KeiyakuRetry } from "./refusal.js";
+import { z } from "zod";
+export type MutationFinalitySurface = "verification" | "placement" | "continuation" | "reconciliation" | "settlement" | "cleanup";
+export type MutationFinality = Readonly<{
+    kind: "complete";
+}> | Readonly<{
+    kind: "accepted-pending";
+    pending: readonly Readonly<{
+        surface: MutationFinalitySurface;
+        required: boolean;
+    }>[];
+}> | Readonly<{
+    kind: "not-admitted";
+}>;
+type AcceptedFinalityInput = Readonly<{
+    kind: "accepted";
+    lags: MutationResult<unknown>["lags"];
+    settlementLags: MutationResult<unknown>["settlementLags"];
+    value?: unknown;
+    cleanup?: AcceptedObligations["cleanup"];
+    leak?: AcceptedObligations["leak"];
+    seatClose?: AcceptedObligations["seatClose"];
+    /** Transport/display convenience only; never finality authority. */
+    pending?: readonly MutationPendingSurface[];
+}>;
+export type MutationFinalityInput = AcceptedFinalityInput | IntegrationConflictMaterialized | KeiyakuRefused | KeiyakuRetry;
+export type MutationPendingSurface = Readonly<{
+    surface: MutationFinalitySurface;
+    required: boolean;
+}>;
+export declare function decodeMutationPendingSurface(value: unknown): MutationPendingSurface;
+export declare const mutationPendingSurfaceSchema: z.ZodType<Readonly<{
+    surface: MutationFinalitySurface;
+    required: boolean;
+}>, unknown, z.core.$ZodTypeInternals<Readonly<{
+    surface: MutationFinalitySurface;
+    required: boolean;
+}>, unknown>>;
+export type Review = ReviewValue & Readonly<{
+    continuation?: ContinuationReport;
+}>;
+export declare function decodeReview(value: unknown): Review;
+export declare const auditReportSchema: z.ZodType<Readonly<{
+    candidate: Readonly<{
+        kind: "blocked";
+        refusal: import("../protocol/operations.js").DeliveryPreparationRefusal;
+    }> | Readonly<{
+        kind: "ready";
+        workspace: Readonly<{
+            kind: "worktree";
+            path: string;
+        }>;
+        identity: import("../core/facts/types.js").DeliverData;
+        scope: Readonly<{
+            filesChanged: number;
+            insertions: number;
+            deletions: number;
+            paths?: readonly string[];
+        }>;
+        diff?: string;
+    }>;
+    verification: Readonly<{
+        kind: "not-run";
+    }> | Readonly<{
+        kind: "satisfied";
+        passed: number;
+        total: number;
+        summary?: string;
+    }> | Readonly<{
+        kind: "unsatisfied";
+        passed: number;
+        total: number;
+        summary?: string;
+    }> | Readonly<{
+        kind: "stopped";
+        stop: import("../protocol/operations.js").VerificationStop;
+    }>;
+    target: Readonly<{
+        kind: "not-observed";
+    }> | import("../git/target-placement.js").AuditTargetAnswer;
+    delivery?: Readonly<{
+        changeId: import("../core/facts/types.js").ChangeId;
+        relation: "identical" | "differs";
+    }>;
+}>, unknown, z.core.$ZodTypeInternals<Readonly<{
+    candidate: Readonly<{
+        kind: "blocked";
+        refusal: import("../protocol/operations.js").DeliveryPreparationRefusal;
+    }> | Readonly<{
+        kind: "ready";
+        workspace: Readonly<{
+            kind: "worktree";
+            path: string;
+        }>;
+        identity: import("../core/facts/types.js").DeliverData;
+        scope: Readonly<{
+            filesChanged: number;
+            insertions: number;
+            deletions: number;
+            paths?: readonly string[];
+        }>;
+        diff?: string;
+    }>;
+    verification: Readonly<{
+        kind: "not-run";
+    }> | Readonly<{
+        kind: "satisfied";
+        passed: number;
+        total: number;
+        summary?: string;
+    }> | Readonly<{
+        kind: "unsatisfied";
+        passed: number;
+        total: number;
+        summary?: string;
+    }> | Readonly<{
+        kind: "stopped";
+        stop: import("../protocol/operations.js").VerificationStop;
+    }>;
+    target: Readonly<{
+        kind: "not-observed";
+    }> | import("../git/target-placement.js").AuditTargetAnswer;
+    delivery?: Readonly<{
+        changeId: import("../core/facts/types.js").ChangeId;
+        relation: "identical" | "differs";
+    }>;
+}>, unknown>>;
+export declare const mutationResultSchema: <Value>(value: z.ZodType<Value>) => z.ZodType<MutationResult<Value>>;
+export declare const deliveryResultSchema: z.ZodUnion<readonly [z.ZodType<Readonly<{
+    kind: "accepted";
+    facts: readonly JournalEntry[];
+    head: ContractHead;
+    value: DeliveryValue;
+    lags: readonly (import("../git/reconcile.js").ReconcileLag | Readonly<{
+        kind: "contract-file-failed";
+        worktree: string;
+        path: string;
+        diagnostic: string;
+    }>)[];
+    settlementLags: readonly Readonly<{
+        kind: "settlement-failed";
+        surface: "task-holder" | "task";
+        contractId: ContractId;
+        taskId?: import("./contract.js").TaskId;
+        path?: string;
+        diagnostic: string;
+    }>[];
+    recoverySnapshot?: SnapshotId;
+    pending: readonly Readonly<{
+        surface: MutationFinalitySurface;
+        required: boolean;
+    }>[];
+} & Readonly<{
+    cleanup?: import("../protocol/intent.js").VerificationCleanupFailure;
+    leak?: import("../git/scratch.js").WorktreeLeak;
+    seatClose?: readonly PrivateStateSeatCloseLag[];
+}>>, unknown, z.core.$ZodTypeInternals<Readonly<{
+    kind: "accepted";
+    facts: readonly JournalEntry[];
+    head: ContractHead;
+    value: DeliveryValue;
+    lags: readonly (import("../git/reconcile.js").ReconcileLag | Readonly<{
+        kind: "contract-file-failed";
+        worktree: string;
+        path: string;
+        diagnostic: string;
+    }>)[];
+    settlementLags: readonly Readonly<{
+        kind: "settlement-failed";
+        surface: "task-holder" | "task";
+        contractId: ContractId;
+        taskId?: import("./contract.js").TaskId;
+        path?: string;
+        diagnostic: string;
+    }>[];
+    recoverySnapshot?: SnapshotId;
+    pending: readonly Readonly<{
+        surface: MutationFinalitySurface;
+        required: boolean;
+    }>[];
+} & Readonly<{
+    cleanup?: import("../protocol/intent.js").VerificationCleanupFailure;
+    leak?: import("../git/scratch.js").WorktreeLeak;
+    seatClose?: readonly PrivateStateSeatCloseLag[];
+}>>, unknown>>, z.ZodType<Readonly<{
+    kind: "integration-conflict-materialized";
+    targetHead: SnapshotId;
+    conflictPaths: readonly string[];
+    workspace: import("../protocol/deliver.js").AppointedWorkspace;
+}>, unknown, z.core.$ZodTypeInternals<Readonly<{
+    kind: "integration-conflict-materialized";
+    targetHead: SnapshotId;
+    conflictPaths: readonly string[];
+    workspace: import("../protocol/deliver.js").AppointedWorkspace;
+}>, unknown>>]>;
+export declare const reviewResultSchema: z.ZodType<Readonly<{
+    kind: "accepted";
+    facts: readonly JournalEntry[];
+    head: ContractHead;
+    value: Review;
+    lags: readonly (import("../git/reconcile.js").ReconcileLag | Readonly<{
+        kind: "contract-file-failed";
+        worktree: string;
+        path: string;
+        diagnostic: string;
+    }>)[];
+    settlementLags: readonly Readonly<{
+        kind: "settlement-failed";
+        surface: "task-holder" | "task";
+        contractId: ContractId;
+        taskId?: import("./contract.js").TaskId;
+        path?: string;
+        diagnostic: string;
+    }>[];
+    recoverySnapshot?: SnapshotId;
+    pending: readonly Readonly<{
+        surface: MutationFinalitySurface;
+        required: boolean;
+    }>[];
+} & Readonly<{
+    cleanup?: import("../protocol/intent.js").VerificationCleanupFailure;
+    leak?: import("../git/scratch.js").WorktreeLeak;
+    seatClose?: readonly PrivateStateSeatCloseLag[];
+}>>, unknown, z.core.$ZodTypeInternals<Readonly<{
+    kind: "accepted";
+    facts: readonly JournalEntry[];
+    head: ContractHead;
+    value: Review;
+    lags: readonly (import("../git/reconcile.js").ReconcileLag | Readonly<{
+        kind: "contract-file-failed";
+        worktree: string;
+        path: string;
+        diagnostic: string;
+    }>)[];
+    settlementLags: readonly Readonly<{
+        kind: "settlement-failed";
+        surface: "task-holder" | "task";
+        contractId: ContractId;
+        taskId?: import("./contract.js").TaskId;
+        path?: string;
+        diagnostic: string;
+    }>[];
+    recoverySnapshot?: SnapshotId;
+    pending: readonly Readonly<{
+        surface: MutationFinalitySurface;
+        required: boolean;
+    }>[];
+} & Readonly<{
+    cleanup?: import("../protocol/intent.js").VerificationCleanupFailure;
+    leak?: import("../git/scratch.js").WorktreeLeak;
+    seatClose?: readonly PrivateStateSeatCloseLag[];
+}>>, unknown>>;
+export declare const auditResultSchema: z.ZodType<Readonly<{
+    kind: "accepted";
+    facts: readonly JournalEntry[];
+    head: ContractHead;
+    value: Readonly<{
+        candidate: Readonly<{
+            kind: "blocked";
+            refusal: import("../protocol/operations.js").DeliveryPreparationRefusal;
+        }> | Readonly<{
+            kind: "ready";
+            workspace: Readonly<{
+                kind: "worktree";
+                path: string;
+            }>;
+            identity: import("../core/facts/types.js").DeliverData;
+            scope: Readonly<{
+                filesChanged: number;
+                insertions: number;
+                deletions: number;
+                paths?: readonly string[];
+            }>;
+            diff?: string;
+        }>;
+        verification: Readonly<{
+            kind: "not-run";
+        }> | Readonly<{
+            kind: "satisfied";
+            passed: number;
+            total: number;
+            summary?: string;
+        }> | Readonly<{
+            kind: "unsatisfied";
+            passed: number;
+            total: number;
+            summary?: string;
+        }> | Readonly<{
+            kind: "stopped";
+            stop: import("../protocol/operations.js").VerificationStop;
+        }>;
+        target: Readonly<{
+            kind: "not-observed";
+        }> | import("../git/target-placement.js").AuditTargetAnswer;
+        delivery?: Readonly<{
+            changeId: import("../core/facts/types.js").ChangeId;
+            relation: "identical" | "differs";
+        }>;
+    }>;
+    lags: readonly (import("../git/reconcile.js").ReconcileLag | Readonly<{
+        kind: "contract-file-failed";
+        worktree: string;
+        path: string;
+        diagnostic: string;
+    }>)[];
+    settlementLags: readonly Readonly<{
+        kind: "settlement-failed";
+        surface: "task-holder" | "task";
+        contractId: ContractId;
+        taskId?: import("./contract.js").TaskId;
+        path?: string;
+        diagnostic: string;
+    }>[];
+    recoverySnapshot?: SnapshotId;
+    pending: readonly Readonly<{
+        surface: MutationFinalitySurface;
+        required: boolean;
+    }>[];
+} & Readonly<{
+    cleanup?: import("../protocol/intent.js").VerificationCleanupFailure;
+    leak?: import("../git/scratch.js").WorktreeLeak;
+    seatClose?: readonly PrivateStateSeatCloseLag[];
+}>>, unknown, z.core.$ZodTypeInternals<Readonly<{
+    kind: "accepted";
+    facts: readonly JournalEntry[];
+    head: ContractHead;
+    value: Readonly<{
+        candidate: Readonly<{
+            kind: "blocked";
+            refusal: import("../protocol/operations.js").DeliveryPreparationRefusal;
+        }> | Readonly<{
+            kind: "ready";
+            workspace: Readonly<{
+                kind: "worktree";
+                path: string;
+            }>;
+            identity: import("../core/facts/types.js").DeliverData;
+            scope: Readonly<{
+                filesChanged: number;
+                insertions: number;
+                deletions: number;
+                paths?: readonly string[];
+            }>;
+            diff?: string;
+        }>;
+        verification: Readonly<{
+            kind: "not-run";
+        }> | Readonly<{
+            kind: "satisfied";
+            passed: number;
+            total: number;
+            summary?: string;
+        }> | Readonly<{
+            kind: "unsatisfied";
+            passed: number;
+            total: number;
+            summary?: string;
+        }> | Readonly<{
+            kind: "stopped";
+            stop: import("../protocol/operations.js").VerificationStop;
+        }>;
+        target: Readonly<{
+            kind: "not-observed";
+        }> | import("../git/target-placement.js").AuditTargetAnswer;
+        delivery?: Readonly<{
+            changeId: import("../core/facts/types.js").ChangeId;
+            relation: "identical" | "differs";
+        }>;
+    }>;
+    lags: readonly (import("../git/reconcile.js").ReconcileLag | Readonly<{
+        kind: "contract-file-failed";
+        worktree: string;
+        path: string;
+        diagnostic: string;
+    }>)[];
+    settlementLags: readonly Readonly<{
+        kind: "settlement-failed";
+        surface: "task-holder" | "task";
+        contractId: ContractId;
+        taskId?: import("./contract.js").TaskId;
+        path?: string;
+        diagnostic: string;
+    }>[];
+    recoverySnapshot?: SnapshotId;
+    pending: readonly Readonly<{
+        surface: MutationFinalitySurface;
+        required: boolean;
+    }>[];
+} & Readonly<{
+    cleanup?: import("../protocol/intent.js").VerificationCleanupFailure;
+    leak?: import("../git/scratch.js").WorktreeLeak;
+    seatClose?: readonly PrivateStateSeatCloseLag[];
+}>>, unknown>>;
+type ObligationPendingInput = Readonly<{
+    lags: MutationResult<unknown>["lags"];
+    settlementLags: MutationResult<unknown>["settlementLags"];
+    cleanup?: AcceptedObligations["cleanup"];
+    leak?: AcceptedObligations["leak"];
+    seatClose?: AcceptedObligations["seatClose"];
+}>;
+type CompletionPendingValue = Readonly<{
+    verification?: unknown | undefined;
+    placement?: unknown | undefined;
+    continuation?: ContinuationReport | undefined;
+}>;
+export declare function noValuePending(_value?: unknown): readonly MutationPendingSurface[];
+export declare function auditPending(value: AuditReport): readonly MutationPendingSurface[];
+export declare function completionPending(value: CompletionPendingValue): readonly MutationPendingSurface[];
+export declare function obligationPending(input: ObligationPendingInput): readonly MutationPendingSurface[];
+export declare function collectAcceptedPending(valuePending: readonly MutationPendingSurface[], obligations: ObligationPendingInput): readonly MutationPendingSurface[];
+/** Purely projects the leading mutation's finality without changing its details. */
+export declare function projectMutationFinality(input: MutationFinalityInput): MutationFinality;
 export type AcceptedIntent<Value> = Readonly<{
     kind: "accepted";
     facts: readonly JournalEntry[];
@@ -16,12 +434,14 @@ export type AcceptedIntent<Value> = Readonly<{
     physical?: ReconcileReport;
 } & AcceptedObligations>;
 export type MutationResult<Value> = Readonly<{
+    kind: "accepted";
     facts: readonly JournalEntry[];
     head: ContractHead;
     value: Value;
     lags: ReconcileCompletion["lag"];
     settlementLags: SettlementReport["lags"];
     recoverySnapshot?: SnapshotId;
+    pending: readonly MutationPendingSurface[];
 } & AcceptedObligations>;
 type Completion<Value, PublicValue> = Readonly<{
     scope: RepositoryScope;
@@ -29,9 +449,17 @@ type Completion<Value, PublicValue> = Readonly<{
     contractId: ContractId;
     accepted: AcceptedIntent<Value>;
     value: (result: Value) => PublicValue;
+    valuePending?: (value: PublicValue) => readonly MutationPendingSurface[];
     hooks: WorktreeHooks;
 }>;
-export declare function completionInput<Value, PublicValue>(scope: RepositoryScope, channel: GitDecodeChannel, contractId: ContractId, value: (result: Value) => PublicValue, hooks: WorktreeHooks): Omit<Completion<Value, PublicValue>, "accepted">;
+export declare function completionInput<Value, PublicValue>(input: Readonly<{
+    scope: RepositoryScope;
+    channel: GitDecodeChannel;
+    contractId: ContractId;
+    value: (result: Value) => PublicValue;
+    hooks: WorktreeHooks;
+    valuePending?: (value: PublicValue) => readonly MutationPendingSurface[];
+}>): Omit<Completion<Value, PublicValue>, "accepted">;
 export declare function completeMutation<Value, PublicValue>(input: Completion<Value, PublicValue>): Promise<MutationResult<PublicValue>>;
 export declare function completeHolderMutation<Value, PublicValue, Refusal>(input: Readonly<{
     completion: Omit<Completion<Value, PublicValue>, "accepted">;