@astrosheep/keiyaku 4.5.11 → 4.5.13

package/build/src/protocol/result-codec.js

@@ -0,0 +1,442 @@
+import { changeId, contractId, entryUlid, snapshotId } from "../core/facts/types.js";
+import { decodeDeliverData } from "../core/facts/codec.js";
+import { decodeAbandonRefusal } from "../core/verbs/abandon.js";
+import { decodeAmendRefusal } from "../core/verbs/amend.js";
+import { decodeArcRefusal } from "../core/verbs/arc.js";
+import { decodeAttestationRefusal } from "../core/verbs/attestation.js";
+import { decodeBindRefusal } from "../core/verbs/bind.js";
+import { decodeDeliverRefusal } from "../core/verbs/deliver.js";
+import { decodePlacementRefusal } from "../core/verbs/placement.js";
+import { decodeAuditTargetAnswer, decodeCheckoutNotFollowableRefusal, decodeDirtyWorkspaceRefusal, decodeHookFailure, decodeIntegrationPreparationRefusal, decodePublicationFailed, decodeUnmergedPathsRefusal, decodeWorktreeLeak, decodeWorktreeMissingRefusal, decodeWorktreeWorkspace, decodeWorkspaceDirtyDelta, } from "../git/result-codec.js";
+import { decodeVerificationDeclarationRefusal } from "../verification/declaration.js";
+import { decodeForkSourceMovedRefusal, decodeTargetInputRefusal } from "./bind.js";
+function fail() {
+    throw new Error("malformed protocol result");
+}
+function record(value, required, optional = []) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        fail();
+    const object = value;
+    const allowed = new Set([...required, ...optional]);
+    for (const key of Object.keys(object))
+        if (!allowed.has(key))
+            fail();
+    for (const key of required)
+        if (!(key in object))
+            fail();
+    return object;
+}
+function nonblank(value) {
+    if (typeof value !== "string" || value.trim() === "")
+        fail();
+    return value;
+}
+function integer(value) {
+    if (typeof value !== "number" || !Number.isInteger(value))
+        fail();
+    return value;
+}
+function boolean(value) {
+    if (typeof value !== "boolean")
+        fail();
+    return value;
+}
+function strings(value) {
+    if (!Array.isArray(value))
+        fail();
+    return value.map(nonblank);
+}
+function decodeContractId(value) {
+    try {
+        return contractId(nonblank(value));
+    }
+    catch {
+        fail();
+    }
+}
+function decodeSnapshotId(value) {
+    try {
+        return snapshotId(nonblank(value));
+    }
+    catch {
+        fail();
+    }
+}
+function first(value, decoders) {
+    for (const decode of decoders) {
+        try {
+            return decode(value);
+        }
+        catch {
+            continue;
+        }
+    }
+    fail();
+}
+export function decodeProtocolTerminal(value) {
+    const object = record(value, ["kind"], ["diagnostic"]);
+    if (object.kind === "exhausted" || object.kind === "collision") {
+        if ("diagnostic" in object)
+            fail();
+        return { kind: object.kind };
+    }
+    return decodePublicationFailed(value);
+}
+export function decodeMergeStatePresentRefusal(value) {
+    const object = record(value, ["kind", "contractId", "workspace"]);
+    if (object.kind !== "merge-state-present")
+        fail();
+    return {
+        kind: "merge-state-present",
+        contractId: decodeContractId(object.contractId),
+        workspace: decodeWorktreeWorkspace(object.workspace),
+    };
+}
+export function decodeDeliverConflictRefusal(value) {
+    const object = record(value, ["kind", "contractId", "reason", "targetHead", "conflictPaths", "recovery"]);
+    if (object.kind !== "integration-failed" || object.reason !== "conflict")
+        fail();
+    const recovery = record(object.recovery, ["materialize", "continue"]);
+    if (recovery.materialize !== "deliver --materialize-conflict --include-dirty")
+        fail();
+    if (recovery.continue !== "deliver --include-dirty")
+        fail();
+    return {
+        kind: "integration-failed",
+        contractId: decodeContractId(object.contractId),
+        reason: "conflict",
+        targetHead: decodeSnapshotId(object.targetHead),
+        conflictPaths: strings(object.conflictPaths),
+        recovery: {
+            materialize: "deliver --materialize-conflict --include-dirty",
+            continue: "deliver --include-dirty",
+        },
+    };
+}
+function decodeTargetMissingRefusal(value) {
+    const object = record(value, ["kind", "contractId"]);
+    if (object.kind !== "target-missing")
+        fail();
+    return { kind: "target-missing", contractId: decodeContractId(object.contractId) };
+}
+export function decodeDeliveryPreparationRefusal(value) {
+    return first(value, [
+        decodeTargetMissingRefusal,
+        decodeWorktreeMissingRefusal,
+        decodeDirtyWorkspaceRefusal,
+        decodeUnmergedPathsRefusal,
+        decodeIntegrationPreparationRefusal,
+        decodeMergeStatePresentRefusal,
+        decodeCheckoutNotFollowableRefusal,
+    ]);
+}
+export function decodeIntentRefusal(value) {
+    return first(value, [
+        decodeAbandonRefusal,
+        decodeAmendRefusal,
+        decodeArcRefusal,
+        decodeBindRefusal,
+        decodeForkSourceMovedRefusal,
+        decodeDeliverRefusal,
+        decodeDeliveryPreparationRefusal,
+        decodeDeliverConflictRefusal,
+        decodePlacementRefusal,
+        decodeAttestationRefusal,
+        decodeTargetInputRefusal,
+        decodeVerificationDeclarationRefusal,
+    ]);
+}
+export function decodeVerificationRuntimeStop(value) {
+    const object = record(value, ["failure"], ["diagnostic", "command", "detail"]);
+    if (object.failure === "unknown-exit" || object.failure === "cancelled") {
+        if ("diagnostic" in object || "command" in object || "detail" in object)
+            fail();
+        return { failure: object.failure };
+    }
+    if (object.failure === "candidate-unavailable" || object.failure === "spawn-error") {
+        if ("command" in object || "detail" in object)
+            fail();
+        return { failure: object.failure, diagnostic: nonblank(object.diagnostic) };
+    }
+    if (object.failure !== "environment-failure")
+        fail();
+    if ("command" in object || "detail" in object) {
+        if ("diagnostic" in object)
+            fail();
+        return {
+            failure: "environment-failure",
+            command: integer(object.command),
+            detail: decodeHookFailure(object.detail),
+        };
+    }
+    return { failure: "environment-failure", diagnostic: nonblank(object.diagnostic) };
+}
+function decodeVerificationStepRefusal(value) {
+    const object = record(value, ["refusal"]);
+    return {
+        refusal: first(object.refusal, [decodeAttestationRefusal, decodeVerificationDeclarationRefusal]),
+    };
+}
+function decodeVerificationStepRetry(value) {
+    const object = record(value, ["retry"]);
+    return { retry: decodeProtocolTerminal(object.retry) };
+}
+export function decodeVerificationStop(value) {
+    return first(value, [decodeVerificationStepRefusal, decodeVerificationStepRetry, decodeVerificationRuntimeStop]);
+}
+export function decodeVerificationReuse(value) {
+    const object = record(value, ["entry", "verdict"], ["summary"]);
+    if (object.verdict !== "satisfied" && object.verdict !== "unsatisfied")
+        fail();
+    let entry;
+    try {
+        entry = entryUlid(nonblank(object.entry));
+    }
+    catch {
+        fail();
+    }
+    return {
+        entry,
+        verdict: object.verdict,
+        ...(object.summary === undefined ? {} : { summary: typeof object.summary === "string" ? object.summary : fail() }),
+    };
+}
+function decodePlacementStepRefusal(value) {
+    return first(value, [
+        decodePlacementRefusal,
+        decodeCheckoutNotFollowableRefusal,
+        decodeIntegrationPreparationRefusal,
+        decodeTargetMissingRefusal,
+    ]);
+}
+function decodePlacementRefusalStop(value) {
+    const object = record(value, ["refusal"]);
+    return { refusal: decodePlacementStepRefusal(object.refusal) };
+}
+function decodePlacementRetryStop(value) {
+    const object = record(value, ["retry"]);
+    return { retry: decodeProtocolTerminal(object.retry) };
+}
+function decodeTargetPlacementFailedStop(value) {
+    const object = record(value, ["failure", "diagnostic"]);
+    if (object.failure !== "target-placement-failed")
+        fail();
+    return { failure: "target-placement-failed", diagnostic: nonblank(object.diagnostic) };
+}
+function decodeTargetMovedWithAttemptsStop(value) {
+    const object = record(value, [
+        "failure",
+        "contractId",
+        "target",
+        "integratedAt",
+        "observed",
+        "attempts",
+        "observedTreeEqualsCandidate",
+    ]);
+    if (object.failure !== "target-moved")
+        fail();
+    return {
+        failure: "target-moved",
+        contractId: decodeContractId(object.contractId),
+        target: nonblank(object.target),
+        integratedAt: decodeSnapshotId(object.integratedAt),
+        observed: object.observed === null ? null : decodeSnapshotId(object.observed),
+        attempts: integer(object.attempts),
+        observedTreeEqualsCandidate: boolean(object.observedTreeEqualsCandidate),
+    };
+}
+function decodeTargetMovedExpectedStop(value) {
+    const object = record(value, [
+        "failure",
+        "contractId",
+        "target",
+        "expected",
+        "observed",
+        "observedTreeEqualsCandidate",
+    ]);
+    if (object.failure !== "target-moved")
+        fail();
+    return {
+        failure: "target-moved",
+        contractId: decodeContractId(object.contractId),
+        target: nonblank(object.target),
+        expected: decodeSnapshotId(object.expected),
+        observed: object.observed === null ? null : decodeSnapshotId(object.observed),
+        observedTreeEqualsCandidate: boolean(object.observedTreeEqualsCandidate),
+    };
+}
+export function decodePlacementStop(value) {
+    return first(value, [
+        decodePlacementRefusalStop,
+        decodePlacementRetryStop,
+        decodeTargetPlacementFailedStop,
+        decodeTargetMovedWithAttemptsStop,
+        decodeTargetMovedExpectedStop,
+    ]);
+}
+export function decodeVerificationCleanupFailure(value) {
+    const object = record(value, ["phase", "command", "detail"]);
+    if (object.phase !== "destroy")
+        fail();
+    return { phase: "destroy", command: integer(object.command), detail: decodeHookFailure(object.detail) };
+}
+export function decodeCandidateCompletion(value) {
+    const object = record(value, ["integration"], ["verification"]);
+    const completion = {
+        integration: decodeSnapshotId(object.integration),
+        ...(object.verification === undefined
+            ? {}
+            : {
+                verification: (() => {
+                    const verification = record(object.verification, ["mode", "verdict"]);
+                    if (verification.mode !== "ran" && verification.mode !== "reused")
+                        fail();
+                    if (verification.verdict !== "satisfied" && verification.verdict !== "unsatisfied")
+                        fail();
+                    return { mode: verification.mode, verdict: verification.verdict };
+                })(),
+            }),
+    };
+    return completion;
+}
+export function decodeCompletionEvidence(value) {
+    const object = record(value, [], ["completion", "verification", "verificationReuse", "verificationSummary", "placement", "cleanup", "leak"]);
+    return {
+        ...(object.completion === undefined ? {} : { completion: decodeCandidateCompletion(object.completion) }),
+        ...(object.verification === undefined ? {} : { verification: decodeVerificationStop(object.verification) }),
+        ...(object.verificationReuse === undefined
+            ? {}
+            : { verificationReuse: decodeVerificationReuse(object.verificationReuse) }),
+        ...(object.verificationSummary === undefined ? {} : { verificationSummary: nonblank(object.verificationSummary) }),
+        ...(object.placement === undefined ? {} : { placement: decodePlacementStop(object.placement) }),
+        ...(object.cleanup === undefined ? {} : { cleanup: decodeVerificationCleanupFailure(object.cleanup) }),
+        ...(object.leak === undefined ? {} : { leak: decodeWorktreeLeak(object.leak) }),
+    };
+}
+export function decodeMaterializedConflict(value) {
+    const object = record(value, ["kind", "targetHead", "conflictPaths", "workspace"]);
+    if (object.kind !== "integration-conflict-materialized")
+        fail();
+    return {
+        kind: "integration-conflict-materialized",
+        targetHead: decodeSnapshotId(object.targetHead),
+        conflictPaths: strings(object.conflictPaths),
+        workspace: decodeWorktreeWorkspace(object.workspace),
+    };
+}
+function decodeAuditReadyCandidate(value) {
+    const object = record(value, ["kind", "workspace", "identity", "scope"], ["diff"]);
+    if (object.kind !== "ready")
+        fail();
+    const scope = record(object.scope, ["filesChanged", "insertions", "deletions"], ["paths"]);
+    return {
+        kind: "ready",
+        workspace: decodeWorktreeWorkspace(object.workspace),
+        identity: decodeDeliverData(object.identity),
+        scope: {
+            filesChanged: integer(scope.filesChanged),
+            insertions: integer(scope.insertions),
+            deletions: integer(scope.deletions),
+            ...(scope.paths === undefined
+                ? {}
+                : {
+                    paths: Array.isArray(scope.paths)
+                        ? scope.paths.map((path) => (typeof path === "string" ? path : fail()))
+                        : fail(),
+                }),
+        },
+        ...(object.diff === undefined ? {} : { diff: typeof object.diff === "string" ? object.diff : fail() }),
+    };
+}
+function decodeAuditBlockedCandidate(value) {
+    const object = record(value, ["kind", "refusal"]);
+    if (object.kind !== "blocked")
+        fail();
+    return { kind: "blocked", refusal: decodeDeliveryPreparationRefusal(object.refusal) };
+}
+function decodeAuditVerification(value) {
+    return first(value, [
+        (input) => {
+            const object = record(input, ["kind"]);
+            if (object.kind !== "not-run")
+                fail();
+            return { kind: "not-run" };
+        },
+        (input) => {
+            const object = record(input, ["kind", "stop"]);
+            if (object.kind !== "stopped")
+                fail();
+            return { kind: "stopped", stop: decodeVerificationStop(object.stop) };
+        },
+        (input) => {
+            const object = record(input, ["kind", "passed", "total"], ["summary"]);
+            if (object.kind !== "satisfied" && object.kind !== "unsatisfied")
+                fail();
+            return {
+                kind: object.kind,
+                passed: typeof object.passed === "number" ? object.passed : fail(),
+                total: typeof object.total === "number" ? object.total : fail(),
+                ...(object.summary === undefined
+                    ? {}
+                    : { summary: typeof object.summary === "string" ? object.summary : fail() }),
+            };
+        },
+    ]);
+}
+function decodeNotObservedAuditTarget(value) {
+    const object = record(value, ["kind"]);
+    if (object.kind !== "not-observed")
+        fail();
+    return { kind: "not-observed" };
+}
+function decodeAuditTarget(value) {
+    return first(value, [decodeNotObservedAuditTarget, decodeAuditTargetAnswer]);
+}
+export function decodeAuditReport(value) {
+    const object = record(value, ["candidate", "verification", "target"], ["delivery"]);
+    return {
+        candidate: first(object.candidate, [decodeAuditBlockedCandidate, decodeAuditReadyCandidate]),
+        verification: decodeAuditVerification(object.verification),
+        target: decodeAuditTarget(object.target),
+        ...(object.delivery === undefined
+            ? {}
+            : {
+                delivery: (() => {
+                    const delivery = record(object.delivery, ["changeId", "relation"]);
+                    if (delivery.relation !== "identical" && delivery.relation !== "differs")
+                        fail();
+                    try {
+                        return { changeId: changeId(nonblank(delivery.changeId)), relation: delivery.relation };
+                    }
+                    catch {
+                        fail();
+                    }
+                })(),
+            }),
+    };
+}
+export function decodeReviewValue(value) {
+    const object = record(value, [], [
+        "completion",
+        "verification",
+        "verificationReuse",
+        "verificationSummary",
+        "placement",
+        "cleanup",
+        "leak",
+        "workspace",
+    ]);
+    const evidence = decodeCompletionEvidence({
+        ...(object.completion === undefined ? {} : { completion: object.completion }),
+        ...(object.verification === undefined ? {} : { verification: object.verification }),
+        ...(object.verificationReuse === undefined ? {} : { verificationReuse: object.verificationReuse }),
+        ...(object.verificationSummary === undefined ? {} : { verificationSummary: object.verificationSummary }),
+        ...(object.placement === undefined ? {} : { placement: object.placement }),
+        ...(object.cleanup === undefined ? {} : { cleanup: object.cleanup }),
+        ...(object.leak === undefined ? {} : { leak: object.leak }),
+    });
+    return {
+        ...evidence,
+        ...(object.workspace === undefined ? {} : { workspace: decodeWorkspaceDirtyDelta(object.workspace) }),
+    };
+}

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

@@ -16,6 +16,7 @@ type ReviewOperationInput = MutationOperationInput & Readonly<{
 export type ReviewValue = CompletionEvidence & Readonly<{
     workspace?: WorkspaceDirtyDelta;
 }>;
+export { decodeReviewValue } from "./result-codec.js";
 export declare function prepareReview(repository: RepositoryScope, stage: Readonly<{
     contractId: import("../core/facts/types.js").ContractId;
     coordinates: ContractState["coordinates"];
@@ -30,4 +31,3 @@ export declare function prepareReview(repository: RepositoryScope, stage: Readon
     refusal: ReviewPreparationRefusal;
 }>;
 export declare function reviewOperation(input: ReviewOperationInput): Promise<IntentOutcome<ReviewValue, ReviewRefusal>>;
-export {};

package/build/src/protocol/review.js

@@ -1,7 +1,7 @@
 import { worktreeChangeId } from "../git/integration.js";
 import { captureTender, dirtyTenderDelta, dirtyTenderRefusal, } from "../git/tender.js";
 import { observeContractsForAdmissionAt } from "../git/observe.js";
-import { withPrivateStatePublicationSeat } from "../git/private-state-seat.js";
+import { matchingPrivateRootObservation, privateStateSeatAttempt, sameSpeculativeWorktreeInput, } from "./run.js";
 import { dependencyKeySet } from "../core/subject.js";
 import { contractState } from "../core/facts/observation.js";
 import { gate } from "../core/facts/types.js";
@@ -10,8 +10,9 @@ import { admitDecidedOffer, mintAttempts } from "./attempt.js";
 import { admitted } from "./outcome.js";
 import { completeCandidate } from "./completion.js";
 import { appointmentFor, readPlaceRegister } from "../workspace-place.js";
-import { timestamp } from "./operations.js";
+import { attemptDecisionWithSeatClose, timestamp } from "./operations.js";
 const REVIEWED = gate("reviewed");
+export { decodeReviewValue } from "./result-codec.js";
 async function captureReviewableWorktree(repository, stage) {
     const appointed = stage.coordinates.workspace === "worktree"
         ? appointmentFor(await readPlaceRegister(repository), stage.contractId)
@@ -53,49 +54,66 @@ function reviewValue(value, completion = {}) {
         ...completion,
     };
 }
-async function reviewAttempt(input, attempt) {
-    return await withPrivateStatePublicationSeat(input.scope, async (seat) => await reviewAttemptInPrivateStateSeat(input, attempt, seat));
+function preparedReviewCapture(input, state, prepared) {
+    return {
+        kind: "prepared",
+        data: {
+            gate: REVIEWED,
+            subject: dependencyKeySet([
+                { kind: "document", value: state.terms.document.key },
+                { kind: "change", value: prepared.data.changeId },
+            ]),
+            verdict: input.verdict,
+            ...(input.summary === undefined ? {} : { summary: input.summary }),
+        },
+    };
 }
-async function reviewAttemptInPrivateStateSeat(input, attempt, seat) {
-    const decisionObservation = await observeContractsForAdmissionAt(input.scope, input.channel, [input.contractId]);
-    const state = contractState(decisionObservation.decision, input.contractId);
-    let preparation;
-    let workspace;
-    let tender;
-    if (state !== null) {
-        const prepared = await captureReviewableWorktree(input.scope, {
-            contractId: state.id,
-            coordinates: state.coordinates,
-        });
-        preparation =
-            prepared.kind === "refused"
-                ? { kind: "refused", refusal: prepared.refusal }
-                : {
-                    kind: "prepared",
-                    data: {
-                        gate: REVIEWED,
-                        subject: dependencyKeySet([
-                            { kind: "document", value: state.terms.document.key },
-                            { kind: "change", value: prepared.data.changeId },
-                        ]),
-                        verdict: input.verdict,
-                        ...(input.summary === undefined ? {} : { summary: input.summary }),
-                    },
-                };
-        if (prepared.kind === "prepared") {
-            workspace = prepared.data.workspace;
-            tender = prepared.data.tender;
-        }
+function reviewWorktreeInput(prepared) {
+    return {
+        tree: prepared.data.tender.tree,
+        head: prepared.data.tender.head,
+        ...(prepared.data.tender.mergeHead === undefined ? {} : { mergeHead: prepared.data.tender.mergeHead }),
+        dirty: prepared.data.tender.dirty,
+        changeId: prepared.data.changeId,
+    };
+}
+async function recaptureReviewWorktree(input, state) {
+    const prepared = await captureReviewableWorktree(input.scope, {
+        contractId: state.id,
+        coordinates: state.coordinates,
+    });
+    return prepared.kind === "prepared" ? reviewWorktreeInput(prepared) : undefined;
+}
+async function speculateReview(input) {
+    const observation = await observeContractsForAdmissionAt(input.scope, input.channel, [input.contractId]);
+    const state = contractState(observation.decision, input.contractId);
+    if (state === null)
+        return { observation };
+    const prepared = await captureReviewableWorktree(input.scope, {
+        contractId: state.id,
+        coordinates: state.coordinates,
+    });
+    if (prepared.kind === "refused") {
+        return { observation, preparation: { kind: "refused", refusal: prepared.refusal } };
     }
+    return {
+        observation,
+        preparation: preparedReviewCapture(input, state, prepared),
+        ...(prepared.data.workspace === undefined ? {} : { workspace: prepared.data.workspace }),
+        tender: prepared.data.tender,
+        worktree: reviewWorktreeInput(prepared),
+    };
+}
+async function decideAndAdmitReview(input, attempt, seat, observation, speculated) {
     const decision = decideAttestation({
         input: {
             contractId: input.contractId,
             ...(input.actor === undefined ? {} : { actor: input.actor }),
             at: timestamp(),
-            ...(preparation === undefined ? {} : { preparation }),
+            ...(speculated.preparation === undefined ? {} : { preparation: speculated.preparation }),
         },
         attempt,
-        observation: decisionObservation.decision,
+        observation: observation.decision,
     });
     if (decision.kind === "refused")
         return { kind: "refused", refusal: decision.refusal };
@@ -103,20 +121,37 @@ async function reviewAttemptInPrivateStateSeat(input, attempt, seat) {
         channel: input.channel,
         repository: input.scope,
         seat,
-        decisionObservation,
+        decisionObservation: observation,
         attempt,
         offer: decision.offer,
         primaryContract: input.contractId,
     });
-    if (admission.kind === "accepted")
-        return {
-            ...admission,
-            value: {
-                ...(workspace === undefined ? {} : { workspace }),
-                ...(tender === undefined ? {} : { tender }),
-            },
-        };
-    return admission;
+    if (admission.kind !== "accepted")
+        return admission;
+    return {
+        ...admission,
+        value: {
+            ...(speculated.workspace === undefined ? {} : { workspace: speculated.workspace }),
+            ...(speculated.tender === undefined ? {} : { tender: speculated.tender }),
+        },
+    };
+}
+async function reviewAttemptInPrivateStateSeat(input, attempt, seat, speculated) {
+    const observation = await matchingPrivateRootObservation(input.scope, input.channel, input.contractId, speculated.observation, async (fresh) => {
+        if (speculated.worktree === undefined)
+            return true;
+        const state = contractState(fresh.decision, input.contractId);
+        if (state === null)
+            return false;
+        return sameSpeculativeWorktreeInput(speculated.worktree, await recaptureReviewWorktree(input, state));
+    });
+    return "kind" in observation
+        ? observation
+        : await decideAndAdmitReview(input, attempt, seat, observation, speculated);
+}
+async function reviewAttempt(input, attempt) {
+    const speculated = await speculateReview(input);
+    return await privateStateSeatAttempt(input.scope, async (seat) => await reviewAttemptInPrivateStateSeat(input, attempt, seat, speculated), attemptDecisionWithSeatClose);
 }
 export async function reviewOperation(input) {
     const git = input.scope;

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

@@ -1,11 +1,17 @@
 import { type GitDecisionObservation } from "../git/observe.js";
+import { type PrivateStatePublicationSeat, type PrivateStateSeatOutcome } from "../git/private-state-seat.js";
 import type { GitDecodeChannel, GitTreeSelection } from "../git/read-observation.js";
 import type { GitRepository } from "../git/process.js";
-import type { GitRefAssertion } from "../git/repository.js";
+import { type GitOid, type GitRefAssertion } from "../git/repository.js";
 import type { AttemptContext, DecideInput, OfferDecision } from "../core/decide.js";
 import type { Offer, TreeUpdate } from "../core/facts/offer.js";
-import { type ContractId } from "../core/facts/types.js";
+import { type ChangeId, type ContractId, type SnapshotId } from "../core/facts/types.js";
 import { type AcceptedAdmission, type AttemptTerminal } from "./attempt.js";
+import type { GitObjectId } from "../git/identity.js";
+export declare const STALE_PRIVATE_STATE_PREPARATION: {
+    readonly kind: "publication-failed";
+    readonly diagnostic: "stale private-state preparation";
+};
 export type ProtocolTerminal = Readonly<{
     kind: "exhausted";
 }> | AttemptTerminal;
@@ -68,6 +74,20 @@ export type PreparedProtocolAttempt<Refusal> = Readonly<{
     offer: Offer;
     assertions: readonly GitRefAssertion[];
 }>;
+export declare function privateRootCommit(observation: GitDecisionObservation): GitOid | null;
+export declare function samePrivateRootObservation(prepared: GitDecisionObservation, fresh: GitDecisionObservation): boolean;
+export type SpeculativeWorktreeInput = Readonly<{
+    tree: GitObjectId;
+    head: SnapshotId;
+    mergeHead?: SnapshotId;
+    dirty: boolean;
+    changeId: ChangeId;
+}>;
+export declare function sameSpeculativeWorktreeInput(prepared: SpeculativeWorktreeInput | undefined, fresh: SpeculativeWorktreeInput | undefined): boolean;
+export declare function privateStateAssertionsMatch(repository: GitRepository, assertions: readonly GitRefAssertion[]): Promise<boolean>;
+export declare function publicationFailedFromSeatError(error: unknown): AttemptTerminal;
+export declare function matchingPrivateRootObservation(repository: GitRepository, channel: GitDecodeChannel, contractId: ContractId, prepared: GitDecisionObservation, revalidate?: (fresh: GitDecisionObservation) => boolean | Promise<boolean>): Promise<GitDecisionObservation | typeof STALE_PRIVATE_STATE_PREPARATION>;
+export declare function privateStateSeatAttempt<T>(repository: GitRepository, action: (seat: PrivateStatePublicationSeat) => Promise<T>, wrap: (outcome: PrivateStateSeatOutcome<T>) => T): Promise<T | AttemptTerminal>;
 /** Form one decided offer without admitting or reinterpreting it. */
 export declare function prepareProtocolAttempt<Input extends Readonly<{
     contractId: ContractId;