@astrosheep/keiyaku 4.0.0 → 4.0.2

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

@@ -1,52 +1,89 @@
-import { type GitDecisionObservation } from "../git/observe.js";
+import type { GitDecisionObservation } from "../git/observe.js";
+import type { GitDecodeChannel, GitTreeSelection } from "../git/read-observation.js";
 import type { GitRepository } from "../git/repository.js";
-import type { WorktreeLeak } from "../git/verification.js";
-import type { AttemptContext, DecideInput, OfferDecision } from "../core/decide.js";
-import type { ActorId, ContractId, ContractState } from "../core/facts/types.js";
-import { type PlacementRefusal } from "../core/verbs/placement.js";
+import type { GitRefAssertion } from "../git/repository.js";
+import { type WorktreeLeak } from "../git/scratch.js";
+import type { HookFailure } from "../git/hooks.js";
+import type { DecideInput, OfferDecision } from "../core/decide.js";
+import type { ActorId, ContractId, ContractState, EntryUlid, SnapshotId } from "../core/facts/types.js";
 import { type AttestationRefusal } from "../core/verbs/attestation.js";
-import { type ProduceVerificationInput, type VerificationOutcome } from "../verification/producer.js";
 import { type VerificationDefinition } from "../verification/declaration.js";
 import { type CompanionDecorator, type ProtocolResult } from "./run.js";
-export declare function mintAttempts(input: Readonly<{
-    entryCount: number;
-}>): readonly AttemptContext[];
-type IntentAdmissionOptions = Readonly<{
+type IntentAdmissionOptions<Input, Refusal, Seed> = Readonly<{
     observedContracts?: readonly ContractId[];
-    observe?: (repository: GitRepository, contracts: readonly ContractId[]) => GitDecisionObservation;
+    observe?: (repository: GitRepository, channel: GitDecodeChannel, contracts: readonly ContractId[]) => Promise<GitDecisionObservation>;
     decorateOffer?: CompanionDecorator;
+    observationSelection?: GitTreeSelection;
+    prepareInput?: (observation: GitDecisionObservation, input: Seed) => Readonly<{
+        kind: "prepared";
+        input: Input;
+        assertions?: readonly GitRefAssertion[];
+    }> | Readonly<{
+        kind: "refused";
+        refusal: Refusal;
+    }> | Promise<Readonly<{
+        kind: "prepared";
+        input: Input;
+        assertions?: readonly GitRefAssertion[];
+    }> | Readonly<{
+        kind: "refused";
+        refusal: Refusal;
+    }>>;
 }>;
 /** Observe, decide, and atomically admit one intent with bounded Git retries. */
 export declare function admitIntent<Input extends Readonly<{
     contractId: ContractId;
-}>, Refusal>(repository: GitRepository, input: Input, decide: (input: DecideInput<Input>) => OfferDecision<Refusal>, options?: IntentAdmissionOptions): ProtocolResult<Refusal>;
-/** Run the sole placement adjudicator; a gates-unsatisfied refusal is normal pending state. */
-export declare function admitPlacement(repository: GitRepository, input: Readonly<{
+}>, Refusal, Seed extends Readonly<{
     contractId: ContractId;
-    actor?: ActorId;
-    at: string;
-}>): ProtocolResult<PlacementRefusal>;
+}> = Input>(channel: GitDecodeChannel, repository: GitRepository, input: Seed, decide: (input: DecideInput<Input>) => OfferDecision<Refusal>, options?: IntentAdmissionOptions<Input, Refusal, Seed>): Promise<ProtocolResult<Refusal>>;
 type VerifyDeliveryInput = Readonly<{
+    channel: GitDecodeChannel;
     repository: GitRepository;
     contractId: ContractId;
     actor?: ActorId;
     at: string;
     state: ContractState;
+    snapshot?: SnapshotId;
     environment: NodeJS.ProcessEnv;
-    produce: (input: ProduceVerificationInput) => Promise<VerificationOutcome>;
+    signal?: AbortSignal;
     verification?: VerificationDefinition;
 }>;
 export type VerificationRuntimeStop = Readonly<{
-    failure: "timeout" | "unknown-exit";
+    failure: "unknown-exit" | "cancelled";
 }> | Readonly<{
     failure: "candidate-unavailable" | "spawn-error";
     diagnostic: string;
+}> | Readonly<{
+    failure: "environment-failure";
+    diagnostic: string;
+}> | Readonly<{
+    failure: "environment-failure";
+    command: number;
+    detail: HookFailure;
+}>;
+export type VerificationCleanupFailure = Readonly<{
+    phase: "destroy";
+    command: number;
+    detail: HookFailure;
 }>;
 export type VerificationStep = ProtocolResult<AttestationRefusal> | VerificationRuntimeStop;
 export type VerificationResult = Readonly<{
     step: VerificationStep;
+    counts?: Readonly<{
+        passed: number;
+        total: number;
+        verdict: "satisfied" | "unsatisfied";
+        summary?: string;
+    }>;
+    cleanup?: VerificationCleanupFailure;
     leak?: WorktreeLeak;
 }>;
-/** Run Verification for an observed delivery, then tender its fact. */
+export type CurrentVerifiedAttestation = Readonly<{
+    entry: EntryUlid;
+    verdict: "satisfied" | "unsatisfied";
+}>;
+/** Read the latest current verified attestation through the generic currentness judge. */
+export declare function currentVerifiedAttestation(state: ContractState): CurrentVerifiedAttestation | undefined;
+/** Run Verification against an explicit or admitted integration snapshot. */
 export declare function verifyDelivery(input: VerifyDeliveryInput): Promise<VerificationResult | null>;
 export {};

package/build/src/protocol/intent.js

@@ -1,63 +1,26 @@
-import { randomBytes } from "node:crypto";
-import { observeGitForAdmission } from "../git/observe.js";
-import { materializeVerificationCandidate } from "../git/verification.js";
+import { materializeScratchCandidate } from "../git/scratch.js";
+import { projectSettings } from "../settings.js";
 import { dependencyKeySet } from "../core/subject.js";
-import { entryUlid } from "../core/facts/types.js";
-import { decidePlacement } from "../core/verbs/placement.js";
+import { latestCurrentAttestations } from "../core/facts/gate.js";
 import { decideAttestation } from "../core/verbs/attestation.js";
+import { executeVerification } from "../verification/execution.js";
 import { VERIFIED } from "../verification/declaration.js";
 import { runProtocol } from "./run.js";
-const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
-const VERIFICATION_TIMEOUT_MS = 5 * 60 * 1_000;
-function nextEntryUlid() {
-    let value = "";
-    let time = BigInt(Date.now());
-    for (let index = 0; index < 10; index += 1) {
-        value = ALPHABET[Number(time & 31n)] + value;
-        time >>= 5n;
-    }
-    let random = BigInt(`0x${randomBytes(10).toString("hex")}`);
-    for (let index = 0; index < 16; index += 1) {
-        value += ALPHABET[Number(random & 31n)];
-        random >>= 5n;
-    }
-    return entryUlid(value);
-}
-const MAX_SEMANTIC_ATTEMPTS = 3;
-export function mintAttempts(input) {
-    return Array.from({ length: MAX_SEMANTIC_ATTEMPTS }, () => ({
-        entryUlids: Array.from({ length: input.entryCount }, nextEntryUlid),
-    }));
-}
+import { mintAttempts } from "./attempt.js";
 /** Observe, decide, and atomically admit one intent with bounded Git retries. */
-export function admitIntent(repository, input, decide, options = {}) {
+export function admitIntent(channel, repository, input, decide, options = {}) {
     const contracts = options.observedContracts ?? [input.contractId];
     return runProtocol({
         input,
+        channel,
         repository,
         contracts,
         attempts: mintAttempts({ entryCount: 2 }),
         decide,
         ...(options.observe === undefined ? {} : { observe: options.observe }),
         ...(options.decorateOffer === undefined ? {} : { decorateOffer: options.decorateOffer }),
-    });
-}
-/** Run the sole placement adjudicator; a gates-unsatisfied refusal is normal pending state. */
-export function admitPlacement(repository, input) {
-    return runProtocol({
-        input,
-        repository,
-        contracts: [input.contractId],
-        attempts: mintAttempts({ entryCount: 2 }),
-        observe: observeGitForAdmission,
-        extendAttempt: (attempt, observedContractCount) => ({
-            ...attempt,
-            entryUlids: [
-                ...attempt.entryUlids,
-                ...Array.from({ length: Math.max(0, observedContractCount - attempt.entryUlids.length) }, nextEntryUlid),
-            ],
-        }),
-        decide: decidePlacement,
+        ...(options.observationSelection === undefined ? {} : { observationSelection: options.observationSelection }),
+        ...(options.prepareInput === undefined ? {} : { prepareInput: options.prepareInput }),
     });
 }
 function runtimeStop(outcome) {
@@ -81,49 +44,62 @@ function verificationInput(outcome, input, subject) {
         },
     };
 }
-/** Run Verification for an observed delivery, then tender its fact. */
+/** Read the latest current verified attestation through the generic currentness judge. */
+export function currentVerifiedAttestation(state) {
+    const current = latestCurrentAttestations(state, new Set([VERIFIED])).get(VERIFIED);
+    return current === undefined ? undefined : { entry: current.entry, verdict: current.data.verdict };
+}
+/** Run Verification against an explicit or admitted integration snapshot. */
 export async function verifyDelivery(input) {
-    const state = input.state;
-    if (state.delivery === null
-        || input.verification === undefined)
+    const snapshot = input.snapshot ?? input.state.delivery?.data.integration.snapshot;
+    if (snapshot === undefined || input.verification === undefined)
         return null;
     const subject = dependencyKeySet([
-        { kind: "snapshot", value: state.delivery.data.candidate },
+        { kind: "snapshot", value: snapshot },
         { kind: "segment", value: input.verification.segment },
     ]);
-    let prepared;
-    try {
-        prepared = materializeVerificationCandidate(input.repository, state.delivery.data.candidate);
+    const execution = await executeVerification({
+        repository: input.repository,
+        candidate: snapshot,
+        declarations: input.verification.declarations,
+        environment: input.environment,
+        materializeScratchCandidate,
+        projectSettings,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    let step;
+    if (execution.outcome.kind === "terminal") {
+        step = await admitIntent(input.channel, input.repository, verificationInput(execution.outcome, input, subject), decideAttestation);
     }
-    catch (error) {
-        return {
-            step: {
-                failure: "candidate-unavailable",
-                diagnostic: error instanceof Error ? error.message : String(error),
-            },
-        };
+    else if (execution.outcome.kind === "candidate-unavailable") {
+        step = { failure: "candidate-unavailable", diagnostic: execution.outcome.diagnostic };
     }
-    let step;
-    let leak = null;
-    try {
-        const outcome = await input.produce({
-            declarations: input.verification.declarations,
-            cwd: prepared.cwd,
-            timeoutMs: VERIFICATION_TIMEOUT_MS,
-            env: input.environment,
-        });
-        if (outcome.kind === "terminal") {
-            step = admitIntent(input.repository, verificationInput(outcome, input, subject), decideAttestation);
-        }
-        else {
-            step = runtimeStop(outcome);
-        }
+    else if (execution.outcome.kind === "environment-failure") {
+        step = "diagnostic" in execution.outcome
+            ? { failure: "environment-failure", diagnostic: execution.outcome.diagnostic }
+            : { failure: "environment-failure", command: execution.outcome.command, detail: execution.outcome.detail };
+    }
+    else if (execution.outcome.kind === "unknown-exit"
+        || execution.outcome.kind === "cancelled"
+        || execution.outcome.kind === "spawn-error") {
+        step = runtimeStop(execution.outcome);
     }
-    finally {
-        leak = prepared.dispose();
+    else {
+        throw new Error("Verification execution returned an invalid outcome");
     }
     return {
         step,
-        ...(leak === null ? {} : { leak }),
+        ...(execution.outcome.kind === "terminal"
+            ? {
+                counts: {
+                    passed: execution.outcome.passed,
+                    total: execution.outcome.total,
+                    verdict: execution.outcome.verdict,
+                    ...(execution.outcome.summary === undefined ? {} : { summary: execution.outcome.summary }),
+                },
+            }
+            : {}),
+        ...(execution.cleanup === undefined ? {} : { cleanup: execution.cleanup }),
+        ...(execution.leak === undefined ? {} : { leak: execution.leak }),
     };
 }

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

@@ -1,9 +1,11 @@
-import { type DeliveryPreparationRefusal, type ReviewPreparationRefusal } from "../git/delivery.js";
+import { type DeliveryDiffScope, 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, ChangeId, 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,17 +13,27 @@ 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 AuditReport as AuditReadReport } from "./read/audit.js";
+import { type CurrentVerifiedAttestation, type VerificationRuntimeStop, type VerificationCleanupFailure } from "./intent.js";
+import { type AuditTargetAnswer, type TargetPlacementRefusal } from "../git/target-placement.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";
+import { type ManagedWorktreeAppointment } from "../workspace-place.js";
 export { bindOperation } from "./bind.js";
+export { reconcileObservationFailure } from "../git/reconcile.js";
 import type { BindRefusal, TargetInputRefusal } from "./bind.js";
 import { type IntentOutcome as ProtocolIntentOutcome } from "./outcome.js";
 import type { ProtocolTerminal } from "./run.js";
 import type { CompanionDecorator } from "./run.js";
-export type { FactKind, TimelineEntry } from "./read/audit.js";
+export type { FactKind } from "../core/facts/types.js";
 export type { ContractDocumentProjection } from "./read/documents.js";
+export type DeliveryPreparationRefusal = Readonly<{
+    kind: "target-missing" | "worktree-missing";
+    contractId: ContractId;
+}> | DirtyWorkspaceRefusal | IntegrationPreparationRefusal | TargetPlacementRefusal;
+type ReviewPreparationRefusal = Readonly<{
+    kind: "worktree-missing";
+    contractId: ContractId;
+}> | DirtyWorkspaceRefusal;
 type ReviewRefusal = AttestationRefusal | ReviewPreparationRefusal;
 export type IntentRefusal = AbandonRefusal | AmendRefusal | ArcRefusal | BindRefusal | DeliverRefusal | DeliveryPreparationRefusal | PlacementRefusal | ReviewRefusal | TargetInputRefusal | VerificationDeclarationRefusal;
 export type { TargetInputRefusal } from "./bind.js";
@@ -32,10 +44,50 @@ type OperationInput = Readonly<{
     contractId: ContractId;
     actor?: ActorId;
 }>;
-export type AuditReport = AuditReadReport & Readonly<{
-    attempt?: VerificationStop;
-    leak?: WorktreeLeak;
+type MutationOperationInput = OperationInput & Readonly<{
+    channel: GitDecodeChannel;
+}>;
+export type AuditWorkspace = Readonly<{
+    kind: "worktree" | "here";
+    path: string;
+}>;
+export type DiffScope = DeliveryDiffScope;
+export type AuditReport = Readonly<{
+    candidate: Readonly<{
+        kind: "blocked";
+        refusal: DeliveryPreparationRefusal;
+    }> | Readonly<{
+        kind: "ready";
+        workspace: AuditWorkspace;
+        identity: DeliveryIdentity;
+        scope: DiffScope;
+        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: VerificationStop;
+    }>;
+    target: Readonly<{
+        kind: "not-observed";
+    }> | AuditTargetAnswer;
+    delivery?: Readonly<{
+        changeId: ChangeId;
+        relation: "identical" | "differs";
+    }>;
 }>;
+export type VerificationReuse = CurrentVerifiedAttestation;
 export type DocumentDerivation = Readonly<{
     document: DocumentKey;
     title: string;
@@ -49,74 +101,123 @@ export type StepStop<R> = Readonly<{
     refusal?: never;
 }>;
 export type VerificationStop = StepStop<AttestationRefusal> | VerificationRuntimeStop;
-export type PlacementStop = StepStop<PlacementRefusal>;
+export type PlacementStop = StepStop<PlacementRefusal | TargetPlacementRefusal | IntegrationPreparationRefusal> | 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;
 }>;
 export type RepositoryScope = GitRepository;
 export { NoGitWorldError };
-export declare function scopeOperation(input: ScopeOperationInput): RepositoryScope;
+export declare function scopeOperation(input: ScopeOperationInput): Promise<RepositoryScope>;
 export declare function currentBranchOperation(input: Readonly<{
     scope: RepositoryScope;
-}>): string | null;
+}>): Promise<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;
+    verificationReuse?: VerificationReuse;
     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"];
+    appointment?: Extract<ManagedWorktreeAppointment, {
+        kind: "appointed";
+    }>;
+}>, input: Readonly<{
+    title: string;
+    message?: string;
+    requireBranchesToBeUpToDate?: boolean;
+    includeDirty?: boolean;
+}>): Promise<{
+    kind: "prepared";
+    data: DeliverData;
+} | {
+    kind: "refused";
+    refusal: DeliveryPreparationRefusal;
+}>;
+export declare function prepareReview(repository: GitRepository, stage: Readonly<{
+    contractId: ContractId;
+    coordinates: ContractState["coordinates"];
+}>): Promise<{
+    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;
-}>): Promise<IntentOutcome<AuditReport>>;
+export declare function reviewOperation(input: ReviewOperationInput): Promise<IntentOutcome<ReviewValue, ReviewRefusal>>;
+type AuditOperationInput = MutationOperationInput & Readonly<{
+    deriveDocument?: (state: ContractState) => DocumentDerivation;
+    requireBranchesToBeUpToDate?: boolean;
+    includeDirty?: boolean;
+    showDiff?: boolean;
+    signal?: AbortSignal;
+}>;
+export declare function auditOperation(input: AuditOperationInput): Promise<IntentOutcome<AuditReport>>;
 export type ReconcileReport = ReconcileResult;
 export type ReconcileObservation = Readonly<{
     state: ContractState | null;
@@ -125,8 +226,11 @@ export type ReconcileObservation = Readonly<{
 type ReconcileOptions = Readonly<{
     hooks: WorktreeHooks;
     retryHooks: boolean;
+    retainTerminalWorktree?: boolean;
+    place?: string;
+    places?: ReadonlyMap<ContractId, string>;
 }>;
-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;
@@ -135,6 +239,11 @@ type RepoReconcileItem = Readonly<{
 export type RepoReconcileReport = Readonly<{
     contracts: readonly RepoReconcileItem[];
 }>;
+export declare function worldContractStates(input: Readonly<{
+    scope: RepositoryScope;
+    channel: GitDecodeChannel;
+}>): Promise<readonly ContractState[]>;
 export declare function reconcileAllOperation(input: Readonly<{
     scope: RepositoryScope;
+    channel: GitDecodeChannel;
 }> & ReconcileOptions): Promise<RepoReconcileReport>;