@astrosheep/keiyaku 4.0.0 → 4.0.1

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

@@ -1,9 +1,11 @@
-import { type DeliveryPreparationRefusal, type ReviewPreparationRefusal } from "../git/delivery.js";
+import { type IntegrationPreparationRefusal } from "../git/integration.js";
+import { type DirtyWorkspaceRefusal, type WorkspaceDirtyDelta } from "../git/tender.js";
 import { type ReconcileResult } from "../git/reconcile.js";
 import type { WorktreeHooks } from "../git/hooks.js";
 import { NoGitWorldError, type GitRepository } from "../git/repository.js";
-import type { WorktreeLeak } from "../git/verification.js";
-import type { ActorId, AmendData, ArcData, AttestationData, ChangeId, ContractId, ContractState, ContractTerms, DocumentKey, SnapshotId } from "../core/facts/types.js";
+import { type GitDecodeChannel, type GitTreeSelection } from "../git/read-observation.js";
+import type { WorktreeLeak } from "../git/scratch.js";
+import type { ActorId, AmendData, ArcData, AttestationData, ContractId, ContractState, ContractTerms, DeliverData, DocumentKey, SnapshotId } from "../core/facts/types.js";
 import { type AbandonRefusal } from "../core/verbs/abandon.js";
 import { type AmendRefusal } from "../core/verbs/amend.js";
 import { type ArcRefusal } from "../core/verbs/arc.js";
@@ -11,7 +13,8 @@ import { type DeliverRefusal } from "../core/verbs/deliver.js";
 import type { PlacementRefusal } from "../core/verbs/placement.js";
 import { type AttestationRefusal } from "../core/verbs/attestation.js";
 import type { VerificationDeclarationPreparation, VerificationDeclarationRefusal } from "../verification/declaration.js";
-import { type VerificationRuntimeStop } from "./intent.js";
+import { type VerificationRuntimeStop, type VerificationCleanupFailure } from "./intent.js";
+import type { TargetPlacementRefusal } from "../git/target-placement.js";
 import { type AuditReport as AuditReadReport } from "./read/audit.js";
 import { type ContractDocumentProjection } from "./read/documents.js";
 import { type ContractBoard, type ContractDisposition, type ContractGateCurrent, type ContractGateReport, type ContractObservation, type ContractPhase, type ContractRow } from "./read/status.js";
@@ -22,6 +25,14 @@ import type { ProtocolTerminal } from "./run.js";
 import type { CompanionDecorator } from "./run.js";
 export type { FactKind, TimelineEntry } from "./read/audit.js";
 export type { ContractDocumentProjection } from "./read/documents.js";
+type DeliveryPreparationRefusal = Readonly<{
+    kind: "target-missing" | "worktree-missing";
+    contractId: ContractId;
+}> | DirtyWorkspaceRefusal | IntegrationPreparationRefusal | TargetPlacementRefusal;
+type ReviewPreparationRefusal = Readonly<{
+    kind: "target-missing" | "worktree-missing";
+    contractId: ContractId;
+}> | DirtyWorkspaceRefusal | IntegrationPreparationRefusal;
 type ReviewRefusal = AttestationRefusal | ReviewPreparationRefusal;
 export type IntentRefusal = AbandonRefusal | AmendRefusal | ArcRefusal | BindRefusal | DeliverRefusal | DeliveryPreparationRefusal | PlacementRefusal | ReviewRefusal | TargetInputRefusal | VerificationDeclarationRefusal;
 export type { TargetInputRefusal } from "./bind.js";
@@ -32,8 +43,12 @@ type OperationInput = Readonly<{
     contractId: ContractId;
     actor?: ActorId;
 }>;
+type MutationOperationInput = OperationInput & Readonly<{
+    channel: GitDecodeChannel;
+}>;
 export type AuditReport = AuditReadReport & Readonly<{
     attempt?: VerificationStop;
+    cleanup?: VerificationCleanupFailure;
     leak?: WorktreeLeak;
 }>;
 export type DocumentDerivation = Readonly<{
@@ -49,7 +64,16 @@ export type StepStop<R> = Readonly<{
     refusal?: never;
 }>;
 export type VerificationStop = StepStop<AttestationRefusal> | VerificationRuntimeStop;
-export type PlacementStop = StepStop<PlacementRefusal>;
+export type PlacementStop = StepStop<PlacementRefusal | TargetPlacementRefusal> | Readonly<{
+    failure: "target-moved";
+    contractId: ContractId;
+    target: string;
+    expected: SnapshotId;
+    observed: SnapshotId | null;
+}> | Readonly<{
+    failure: "target-placement-failed";
+    diagnostic: string;
+}>;
 type ScopeOperationInput = Readonly<{
     coordinate: string;
 }>;
@@ -61,61 +85,93 @@ export declare function currentBranchOperation(input: Readonly<{
 }>): string | null;
 export declare function contractsOperation(input: Readonly<{
     scope: RepositoryScope;
-}>): ContractBoard;
-export declare function contractObservationOperation(input: OperationInput): ContractObservation;
+    channel: GitDecodeChannel;
+}>): Promise<ContractBoard>;
+export declare function contractObservationOperation(input: MutationOperationInput): Promise<ContractObservation>;
 export type { ContractBoard, ContractDisposition, ContractGateCurrent, ContractGateReport, ContractObservation, ContractPhase, ContractRow };
-export declare function documentsOperation(input: Readonly<{
-    scope: RepositoryScope;
-}>): readonly ContractDocumentProjection[];
-export declare function stateOperation(input: OperationInput): ContractState;
-export declare function readStateOperation(input: OperationInput): ContractState | null;
-type DeliveryIdentity = Readonly<{
-    snapshotId: SnapshotId;
-    changeId: ChangeId;
-    expectedPredecessor: SnapshotId;
-}>;
-export declare function deliveryOperation(input: OperationInput): DeliveryIdentity | null;
+export declare function documentsOperationAt(scope: RepositoryScope, channel: GitDecodeChannel): Promise<readonly ContractDocumentProjection[]>;
+export declare function stateOperation(input: MutationOperationInput): Promise<ContractState>;
+type DeliveryIdentity = DeliverData;
+export declare function deliveryOperation(input: MutationOperationInput): Promise<DeliveryIdentity | null>;
 type DeliveryDiffOperationInput = Readonly<{
     scope: RepositoryScope;
-    expectedPredecessor: SnapshotId;
-    snapshotId: SnapshotId;
+    integrationPredecessor: SnapshotId;
+    integrationSnapshot: SnapshotId;
 }>;
 export declare function deliveryDiffOperation(input: DeliveryDiffOperationInput): Promise<string | null>;
-type AmendOperationInput = OperationInput & Readonly<{
-    amendment?: Readonly<{
-        source: ContractTerms;
+type AmendOperationInput = MutationOperationInput & Readonly<{
+    source?: ContractTerms;
+    deriveAmendment?: (source: ContractTerms) => Readonly<{
         terms: AmendData;
         verification: VerificationDeclarationPreparation;
     }>;
 }>;
-export declare function amendOperation(input: AmendOperationInput): IntentOutcome<void, AmendRefusal | VerificationDeclarationRefusal>;
+type Amendment = Readonly<{
+    source: ContractTerms;
+}> & ReturnType<NonNullable<AmendOperationInput["deriveAmendment"]>>;
+export declare function amendOperation(input: AmendOperationInput): Promise<IntentOutcome<Amendment, AmendRefusal | VerificationDeclarationRefusal>>;
 export type DeliverValue = DeliveryIdentity & Readonly<{
     verification?: VerificationStop;
     placement?: PlacementStop;
+    cleanup?: VerificationCleanupFailure;
     leak?: WorktreeLeak;
 }>;
-type DeliverOperationInput = OperationInput & Readonly<{
-    derivation?: DocumentDerivation;
+type DeliverOperationInput = MutationOperationInput & Readonly<{
+    deriveDocument?: (state: ContractState) => DocumentDerivation;
     message?: string;
+    requireBranchesToBeUpToDate: boolean;
+    includeDirty: boolean;
+    signal?: AbortSignal;
 }>;
+export declare function prepareDelivery(repository: GitRepository, stage: Readonly<{
+    contractId: ContractId;
+    coordinates: ContractState["coordinates"];
+}>, input: Readonly<{
+    title: string;
+    message?: string;
+    requireBranchesToBeUpToDate?: boolean;
+    includeDirty?: boolean;
+}>): {
+    kind: "prepared";
+    data: DeliverData;
+} | {
+    kind: "refused";
+    refusal: DeliveryPreparationRefusal;
+};
+export declare function prepareReview(repository: GitRepository, stage: Readonly<{
+    contractId: ContractId;
+    coordinates: ContractState["coordinates"];
+}>): {
+    kind: "prepared";
+    data: Readonly<{
+        changeId: DeliverData["integration"]["changeId"];
+        workspace?: WorkspaceDirtyDelta;
+    }>;
+} | {
+    kind: "refused";
+    refusal: ReviewPreparationRefusal;
+};
 export declare function deliverOperation(input: DeliverOperationInput): Promise<IntentOutcome<DeliverValue>>;
-export declare function abandonOperation(input: OperationInput & Readonly<{
+export declare function abandonOperation(input: MutationOperationInput & Readonly<{
     note?: string;
     decorateOffer?: CompanionDecorator;
-}>): IntentOutcome<void, AbandonRefusal>;
-export declare function arcOperation(input: OperationInput & Readonly<{
+    observationSelection?: GitTreeSelection;
+}>): Promise<IntentOutcome<void, AbandonRefusal>>;
+export declare function arcOperation(input: MutationOperationInput & Readonly<{
     chapter: Omit<ArcData, "seq">;
-}>): IntentOutcome<void, ArcRefusal>;
-type ReviewOperationInput = OperationInput & Readonly<{
+}>): Promise<IntentOutcome<void, ArcRefusal>>;
+type ReviewOperationInput = MutationOperationInput & Readonly<{
     verdict: AttestationData["verdict"];
     summary?: string;
 }>;
 export type ReviewValue = Readonly<{
     placement?: PlacementStop;
+    workspace?: WorkspaceDirtyDelta;
 }>;
-export declare function reviewOperation(input: ReviewOperationInput): IntentOutcome<ReviewValue, ReviewRefusal>;
-export declare function auditOperation(input: OperationInput & Readonly<{
-    derivation?: DocumentDerivation;
+export declare function reviewOperation(input: ReviewOperationInput): Promise<IntentOutcome<ReviewValue, ReviewRefusal>>;
+export declare function auditOperation(input: MutationOperationInput & Readonly<{
+    deriveDocument?: (state: ContractState) => DocumentDerivation;
+    signal?: AbortSignal;
 }>): Promise<IntentOutcome<AuditReport>>;
 export type ReconcileReport = ReconcileResult;
 export type ReconcileObservation = Readonly<{
@@ -125,8 +181,9 @@ export type ReconcileObservation = Readonly<{
 type ReconcileOptions = Readonly<{
     hooks: WorktreeHooks;
     retryHooks: boolean;
+    retainTerminalWorktree?: boolean;
 }>;
-export declare function reconcileOperation(input: OperationInput & ReconcileOptions): Promise<ReconcileObservation>;
+export declare function reconcileOperation(input: MutationOperationInput & ReconcileOptions): Promise<ReconcileObservation>;
 type RepoReconcileItem = Readonly<{
     contractId: ContractId;
     state: ContractState | null;
@@ -137,4 +194,5 @@ export type RepoReconcileReport = Readonly<{
 }>;
 export declare function reconcileAllOperation(input: Readonly<{
     scope: RepositoryScope;
+    channel: GitDecodeChannel;
 }> & ReconcileOptions): Promise<RepoReconcileReport>;