@astrosheep/keiyaku 4.5.29 → 4.6.2

package/build/src/protocol/progress.js

@@ -1,18 +1,95 @@
-import { encodeEntry } from "../core/facts/codec.js";
+import { contractIdSchema, snapshotIdSchema } from "../git/identity.js";
+import { z } from "zod";
+import { worktreeLeakSchema } from "../git/scratch.js";
+import { privateStateSeatCloseLagSchema } from "../git/private-state-seat.js";
+import { verificationCleanupFailureSchema } from "./intent.js";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { GitPlumbingError } from "../git/process.js";
 import { SqliteTransactionLockError } from "../coordination/sqlite-transaction-lock.js";
-import { observeExecution } from "./execution-observation.js";
+import { GitPrivateStateSeatContentionError } from "../git/private-state-seat.js";
 export function contractCheckpoint(input) {
     return { state: input.state, journal: input.journal };
 }
+export const executionCleanupSchema = z.union([
+    z
+        .object({
+        kind: z.literal("decode-channel-retirement"),
+        contractId: contractIdSchema,
+        diagnostic: z.string().min(1),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("verification-cleanup"),
+        contractId: contractIdSchema,
+        snapshot: snapshotIdSchema.optional(),
+        failure: verificationCleanupFailureSchema,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("worktree-leak"),
+        contractId: contractIdSchema,
+        snapshot: snapshotIdSchema.optional(),
+        leak: worktreeLeakSchema,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("private-state-seat-close"),
+        contractId: contractIdSchema,
+        failure: privateStateSeatCloseLagSchema,
+    })
+        .strict(),
+]);
+export const executionStageSchema = z.enum([
+    "admission",
+    "verification",
+    "placement",
+    "reintegration",
+    "continuation",
+    "reconciliation",
+]);
+export const executionStopSchema = z
+    .object({
+    kind: z.literal("execution-stopped"),
+    contractId: contractIdSchema,
+    stage: executionStageSchema,
+    reason: z.enum(["cancelled", "failed"]),
+    diagnostic: z.string().refine((value) => value.trim() !== ""),
+})
+    .strict();
+/** Only owner-declared operational classes and native system I/O failures are operational. */
+export function isOperationalFailure(error) {
+    if (!(error instanceof Error) ||
+        error instanceof AuthorityCorruptionError ||
+        error instanceof TypeError ||
+        error instanceof RangeError ||
+        error instanceof ReferenceError ||
+        error instanceof SyntaxError)
+        return false;
+    return (error instanceof GitPlumbingError ||
+        error instanceof SqliteTransactionLockError ||
+        error instanceof GitPrivateStateSeatContentionError ||
+        ("code" in error && typeof error.code === "string" && /^E[A-Z0-9]+$/u.test(error.code)));
+}
+/** Cancellation is witnessed by this exact signal reason, not by a signal merely being aborted. */
+export function isOperationalStop(error, signal) {
+    if (signal?.aborted === true && error === signal.reason)
+        return true;
+    if (error instanceof AuthorityCorruptionError ||
+        error instanceof TypeError ||
+        error instanceof RangeError ||
+        error instanceof ReferenceError ||
+        error instanceof SyntaxError)
+        return false;
+    return isOperationalFailure(error);
+}
 /** Classify operational failures only; programming errors and corrupt authority still throw. */
 export function executionStop(contractId, stage, error, signal) {
-    if (error instanceof AuthorityCorruptionError || error instanceof TypeError)
-        throw error;
     const cancelled = signal?.aborted === true &&
         (error === signal.reason || error instanceof GitPlumbingError || error instanceof SqliteTransactionLockError);
-    if (!cancelled && !(error instanceof GitPlumbingError) && !(error instanceof SqliteTransactionLockError))
+    if (!cancelled && !isOperationalFailure(error))
         throw error;
     return {
         kind: "execution-stopped",
@@ -22,130 +99,3 @@ export function executionStop(contractId, stage, error, signal) {
         diagnostic: error instanceof Error ? error.message : String(error),
     };
 }
-/** Invocation-local receipts and ephemeral observations; no scheduling or authority reads. */
-export class ExecutionProgress {
-    observer;
-    constructor(observer) {
-        this.observer = observer;
-    }
-    observe(event) {
-        observeExecution(this.observer, event);
-    }
-    entries = new Map();
-    admittedFacts = [];
-    admittedHeads = new Map();
-    admittedCheckpoints = new Map();
-    affectedContracts = new Set();
-    effects = [];
-    lags = [];
-    cleanupIssues = [];
-    executionStops = [];
-    reportedResidue = new WeakSet();
-    /** A confirmed publication is retained even if folding or later physical work throws. */
-    recordPublication(contractId, head, facts) {
-        const incoming = new Map();
-        for (const fact of facts) {
-            const key = `${fact.contract}\0${fact.entry}`;
-            const bytes = encodeEntry(fact);
-            const previous = incoming.get(key)?.bytes ?? this.entries.get(key);
-            if (previous !== undefined && previous !== bytes)
-                throw new AuthorityCorruptionError("conflicting invocation receipt");
-            incoming.set(key, { fact, bytes });
-        }
-        let fresh = false;
-        for (const [key, { fact, bytes }] of incoming) {
-            if (this.entries.has(key))
-                continue;
-            this.entries.set(key, bytes);
-            this.admittedFacts.push(fact);
-            this.observe({ kind: "admitted", contractId, fact });
-            this.affectedContracts.add(fact.contract);
-            fresh = true;
-        }
-        if (fresh || !this.admittedHeads.has(contractId))
-            this.admittedHeads.set(contractId, head);
-    }
-    recordAdmission(step) {
-        if (step.state.head === null)
-            throw new Error("admission requires a journal head");
-        this.recordPublication(step.state.id, step.state.head, step.facts);
-        if (this.admittedHeads.get(step.state.id) === step.state.head) {
-            this.admittedCheckpoints.set(step.state.id, contractCheckpoint(step));
-        }
-        this.recordResidue(step.state.id, step);
-    }
-    hasFact(fact) {
-        return this.entries.get(`${fact.contract}\0${fact.entry}`) === encodeEntry(fact);
-    }
-    head(contractId) {
-        return this.admittedHeads.get(contractId);
-    }
-    recordResidue(contractId, residue) {
-        if (residue.physical !== undefined)
-            this.recordPhysical(contractId, residue.physical);
-        for (const failure of residue.seatClose ?? []) {
-            if (this.reportedResidue.has(failure))
-                continue;
-            this.reportedResidue.add(failure);
-            this.cleanupIssues.push({ kind: "private-state-seat-close", contractId, failure });
-        }
-    }
-    recordPhysical(contractId, physical) {
-        if (physical.effects.length > 0 || physical.lag.length > 0)
-            this.affectedContracts.add(contractId);
-        for (const effect of physical.effects) {
-            if (this.reportedResidue.has(effect))
-                continue;
-            this.reportedResidue.add(effect);
-            this.effects.push(effect);
-        }
-        for (const lag of physical.lag) {
-            if (this.reportedResidue.has(lag))
-                continue;
-            this.reportedResidue.add(lag);
-            this.lags.push(lag);
-        }
-    }
-    recordVerification(contractId, snapshot, result) {
-        if (result.cleanup !== undefined)
-            this.cleanupIssues.push({
-                kind: "verification-cleanup",
-                contractId,
-                ...(snapshot === undefined ? {} : { snapshot }),
-                failure: result.cleanup,
-            });
-        if (result.leak !== undefined)
-            this.cleanupIssues.push({
-                kind: "worktree-leak",
-                contractId,
-                ...(snapshot === undefined ? {} : { snapshot }),
-                leak: result.leak,
-            });
-    }
-    recordStop(stop) {
-        if (!this.executionStops.includes(stop))
-            this.executionStops.push(stop);
-    }
-    checkpoint(contractId) {
-        return this.admittedCheckpoints.get(contractId);
-    }
-    snapshot() {
-        return {
-            facts: Object.freeze([...this.admittedFacts]),
-            checkpoints: new Map(this.admittedCheckpoints),
-            heads: new Map(this.admittedHeads),
-            affected: Object.freeze([...this.affectedContracts]),
-            physical: { effects: Object.freeze([...this.effects]), lag: Object.freeze([...this.lags]) },
-            cleanup: Object.freeze([...this.cleanupIssues]),
-            stops: Object.freeze([...this.executionStops]),
-        };
-    }
-    /** One final assembly; a dependent's checkpoint can never replace the addressed head. */
-    accepted(contractId, value) {
-        const head = this.head(contractId);
-        if (head === undefined)
-            throw new Error("missing leading admission receipt");
-        const snapshot = this.snapshot();
-        return { kind: "accepted", head, facts: snapshot.facts, value, physical: snapshot.physical };
-    }
-}

package/build/src/protocol/read/status.d.ts

@@ -4,7 +4,7 @@ import type { GitDecodeChannel, GitReadObservation } from "../../git/read-observ
 import { type GateCurrent } from "../../core/facts/gate.js";
 import { type ContractId, type ContractState, type DeliverData, type JournalEntry, type SnapshotId } from "../../core/facts/types.js";
 import { type BoundedList } from "../../bounded-list.js";
-export type ContractPhase = "waiting" | "bound" | "tendered" | "claimed" | "abandoned";
+export type ContractPhase = "bound" | "delivered" | "claimed" | "abandoned";
 export type ContractDisposition = "active" | "terminal";
 export type ContractGateCurrent = GateCurrent;
 export type ContractGateReport = Readonly<{
@@ -36,7 +36,7 @@ export type ContractTargetLag = GitContractTargetLag | Readonly<{
     }>;
 }>;
 export type { ContractWorkspaceObservation };
-export type AfterEndpointObservation = Readonly<{
+type AfterEndpointObservation = Readonly<{
     kind: "claimed";
 }> | Readonly<{
     kind: "active";
@@ -67,6 +67,7 @@ export type ContractRow = Readonly<{
     target: string | null;
     targetLag: ContractTargetLag;
     delivery: DeliverData | null;
+    abandonNote?: string;
     targetObservation: Readonly<{
         head: SnapshotId | null;
         drift: boolean;
@@ -97,7 +98,7 @@ export type ContractObservation = Readonly<{
     kind: "present";
     row: ContractRow;
 }>;
-export declare function phaseAtFor(state: Pick<ContractState, "terminal" | "delivery" | "bound">, bindAt: string): string;
+export declare function phaseAtFor(state: Pick<ContractState, "terminal" | "delivery">, bindAt: string): string;
 export declare function lastJournalAtFor(entries: readonly Pick<JournalEntry, "at">[]): string;
 /** Build the Contract board from one immutable git observation. */
 export declare function readContractBoard(observation: GitReadObservation, include?: ContractId): Promise<ContractBoard>;

package/build/src/protocol/read/status.js

@@ -25,10 +25,8 @@ function phaseFor(state) {
     if (state.terminal?.kind === "abandoned")
         return "abandoned";
     if (state.delivery !== null)
-        return "tendered";
-    if (state.bound !== null)
-        return "bound";
-    return "waiting";
+        return "delivered";
+    return "bound";
 }
 function verificationFor(state, document) {
     if (document === undefined)
@@ -49,7 +47,7 @@ function verificationFor(state, document) {
     return state.delivery === null ? undefined : { kind: "unrecorded" };
 }
 export function phaseAtFor(state, bindAt) {
-    return state.terminal?.at ?? state.delivery?.at ?? state.bound?.at ?? bindAt;
+    return state.terminal?.at ?? state.delivery?.at ?? bindAt;
 }
 export function lastJournalAtFor(entries) {
     const last = entries.at(-1);
@@ -129,6 +127,9 @@ async function rowFor(input) {
         delivery: state.delivery === null || state.currentIntegration === null
             ? null
             : { ...state.delivery.data, integration: state.currentIntegration },
+        ...(state.terminal?.kind === "abandoned" && state.terminal.data.note !== undefined
+            ? { abandonNote: state.terminal.data.note }
+            : {}),
         targetObservation,
         ...(verification === undefined ? {} : { verification }),
         gates: {

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

@@ -3,10 +3,9 @@ import type { ContractId, ContractState } from "../core/facts/types.js";
 import type { WorktreeHooks } from "../git/hooks.js";
 import type { GitDecodeChannel } from "../git/read-observation.js";
 import type { MutationOperationInput, RepositoryScope } from "./operations.js";
-export type ReconcileReport = ReconcileResult;
 type ReconcileObservation = Readonly<{
     state: ContractState | null;
-    report: ReconcileReport;
+    report: ReconcileResult;
 }>;
 type ReconcileOptions = Readonly<{
     hooks: WorktreeHooks;
@@ -14,12 +13,13 @@ type ReconcileOptions = Readonly<{
     retainTerminalWorktree?: boolean;
     place?: string;
     places?: ReadonlyMap<ContractId, string>;
+    onPhysical?: (report: ReconcileResult) => void;
 }>;
 export declare function reconcileOperation(input: MutationOperationInput & ReconcileOptions): Promise<ReconcileObservation>;
 type RepoReconcileItem = Readonly<{
     contractId: ContractId;
     state: ContractState | null;
-    report: ReconcileReport;
+    report: ReconcileResult;
 }>;
 type RepoReconcileReport = Readonly<{
     contracts: readonly RepoReconcileItem[];

package/build/src/protocol/reconcile.js

@@ -10,6 +10,10 @@ export async function reconcileOperation(input) {
             contractId: input.contractId,
             hooks: input.hooks,
             retryHooks: input.retryHooks,
+            onPhysical: (report) => {
+                input.progress?.recordPhysical(input.contractId, report);
+                input.onPhysical?.(report);
+            },
             ...(input.retainTerminalWorktree === undefined ? {} : { retainTerminalWorktree: input.retainTerminalWorktree }),
             ...(input.place === undefined ? {} : { place: input.place }),
         });

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

@@ -1,4 +1,4 @@
-import type { ExecutionProgress } from "./progress.js";
+import type { ProtocolProgress } from "./progress.js";
 import type { ActorId, ContractId, ReintegratedData } from "../core/facts/types.js";
 import { type ReintegrateRefusal } from "../core/verbs/reintegrate.js";
 import { type IntegrationPreparationRefusal } from "../git/integration.js";
@@ -27,7 +27,7 @@ type ReintegrationInput = Readonly<{
     contractId: ContractId;
     target: string;
     actor?: ActorId;
-    progress?: ExecutionProgress;
+    progress?: ProtocolProgress;
 }>;
 export declare function reintegrateOperation(input: ReintegrationInput): Promise<ReintegrationResult>;
 export {};

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

@@ -1,26 +1,43 @@
-import { type WorkspaceDirtyDelta } from "../git/tender.js";
+import { z } from "zod";
+import { type ActiveContractRefusal } from "../core/facts/observation.js";
 import type { AttestationData, ContractState, DeliverData } from "../core/facts/types.js";
-import { type AttestationRefusal } from "../core/verbs/attestation.js";
 import type { LeadingOutcome } from "./outcome.js";
-import type { CompletionEvidence } from "./completion.js";
 import type { MutationOperationInput, RepositoryScope } from "./operations.js";
 type ReviewPreparationRefusal = Readonly<{
     kind: "worktree-missing";
     contractId: import("../core/facts/types.js").ContractId;
 }> | import("../git/tender.js").DirtyWorkspaceRefusal;
-type ReviewRefusal = AttestationRefusal | ReviewPreparationRefusal;
+type ReviewRefusal = ActiveContractRefusal | ReviewPreparationRefusal;
 type ReviewOperationInput = MutationOperationInput & Readonly<{
     verdict: AttestationData["verdict"];
     summary?: string;
 }>;
-export type ReviewWorkspaceEvidence = WorkspaceDirtyDelta & Readonly<{
-    unmergedPaths: readonly string[];
-}>;
-export type ReviewAdmissionValue = Readonly<{
-    workspace?: ReviewWorkspaceEvidence;
-}>;
-export type ReviewValue = CompletionEvidence & ReviewAdmissionValue;
-export { decodeReviewValue } from "./result-codec.js";
+declare const reviewWorkspaceEvidenceSchema: z.ZodObject<{
+    staged: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    unstaged: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    untracked: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    shortStat: z.ZodObject<{
+        filesChanged: z.ZodNumber;
+        insertions: z.ZodNumber;
+        deletions: z.ZodNumber;
+    }, z.core.$strict>;
+    unmergedPaths: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+type ReviewWorkspaceEvidence = z.infer<typeof reviewWorkspaceEvidenceSchema>;
+export declare const reviewAdmissionValueSchema: z.ZodObject<{
+    workspace: z.ZodOptional<z.ZodObject<{
+        staged: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+        unstaged: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+        untracked: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+        shortStat: z.ZodObject<{
+            filesChanged: z.ZodNumber;
+            insertions: z.ZodNumber;
+            deletions: z.ZodNumber;
+        }, z.core.$strict>;
+        unmergedPaths: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ReviewAdmissionValue = z.infer<typeof reviewAdmissionValueSchema>;
 export declare function prepareReview(repository: RepositoryScope, stage: Readonly<{
     contractId: import("../core/facts/types.js").ContractId;
     coordinates: ContractState["coordinates"];
@@ -35,3 +52,4 @@ export declare function prepareReview(repository: RepositoryScope, stage: Readon
     refusal: ReviewPreparationRefusal;
 }>;
 export declare function admitReviewOperation(input: ReviewOperationInput): Promise<LeadingOutcome<ReviewAdmissionValue, ReviewRefusal>>;
+export {};

package/build/src/protocol/review.js

@@ -1,8 +1,10 @@
+import { z } from "zod";
+import { workspaceDirtyDeltaSchema } from "../git/tender.js";
 import { worktreeChangeId } from "../git/integration.js";
-import { captureTender, dirtyTenderDelta, dirtyTenderRefusal, } from "../git/tender.js";
+import { captureTender, dirtyTenderDelta, dirtyTenderRefusal } from "../git/tender.js";
 import { observeContractsForAdmissionAt } from "../git/observe.js";
 import { unmergedWorkspacePaths, worktreePath } from "../git/workspace.js";
-import { contractStateWitness, privateStateSeatAttempt, sameWorktreeWitness, STALE_PRIVATE_STATE_PREPARATION, } from "./run.js";
+import { contractStateWitness, privateStateSeatAttempt, runBoundedAttempts, sameWorktreeWitness, STALE_PRIVATE_STATE_PREPARATION, } from "./run.js";
 import { dependencyKeySet } from "../core/subject.js";
 import { contractState } from "../core/facts/observation.js";
 import { gate } from "../core/facts/types.js";
@@ -11,7 +13,10 @@ import { admitDecidedOffer, mintAttempts } from "./attempt.js";
 import { appointmentFor, readPlaceRegister } from "../workspace-place.js";
 import { attemptDecisionWithSeatClose, timestamp } from "./operations.js";
 const REVIEWED = gate("reviewed");
-export { decodeReviewValue } from "./result-codec.js";
+const reviewWorkspaceEvidenceSchema = workspaceDirtyDeltaSchema
+    .extend({ unmergedPaths: z.array(z.string().refine((value) => value.trim() !== "")).readonly() })
+    .strict();
+export const reviewAdmissionValueSchema = z.object({ workspace: reviewWorkspaceEvidenceSchema.optional() }).strict();
 async function captureReviewableWorktree(repository, stage) {
     const appointed = stage.coordinates.workspace === "worktree"
         ? appointmentFor(await readPlaceRegister(repository), stage.contractId)
@@ -178,25 +183,11 @@ async function reviewAttempt(input, attempt) {
     }, attemptDecisionWithSeatClose);
 }
 export async function admitReviewOperation(input) {
-    const attempts = mintAttempts({ entryCount: 1 });
-    let review = null;
-    for (let index = 0; index < attempts.length; index += 1) {
-        const result = await reviewAttempt(input, attempts[index]);
-        if (result.kind === "accepted" || result.kind === "refused") {
-            review = result;
-            break;
-        }
-        if (result.kind === "publication-failed")
-            return { kind: "retry", reason: result };
-        if (result.kind === "stale" || result.kind === "redecide")
-            continue;
-        if (result.kind === "collision" && index + 1 === attempts.length)
-            return { kind: "retry", reason: result };
-    }
-    if (review === null)
-        return { kind: "retry", reason: { kind: "exhausted" } };
-    if (review.kind !== "accepted")
-        return review;
-    input.progress?.recordResidue(input.contractId, review);
-    return review;
+    const result = await runBoundedAttempts(mintAttempts({ entryCount: 1 }), (attempt) => reviewAttempt(input, attempt));
+    if (result.kind === "refused")
+        return result;
+    if (result.kind !== "accepted")
+        return { kind: "retry", reason: result };
+    input.progress?.recordResidue(input.contractId, result);
+    return result;
 }

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

@@ -1,4 +1,5 @@
-import type { ExecutionProgress } from "./progress.js";
+import { z } from "zod";
+import type { ProtocolProgress } from "./progress.js";
 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";
@@ -12,13 +13,41 @@ import { type AcceptedAdmission, type AttemptTerminal } from "./attempt.js";
 export declare const STALE_PRIVATE_STATE_PREPARATION: {
     readonly kind: "stale";
 };
-export type ProtocolTerminal = Readonly<{
-    kind: "exhausted";
-}> | AttemptTerminal;
+export declare const protocolTerminalSchema: 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>]>;
+export type ProtocolTerminal = z.infer<typeof protocolTerminalSchema>;
 export type ProtocolResult<Refusal> = AcceptedAdmission | Readonly<{
     kind: "refused";
     refusal: Refusal;
 }> | ProtocolTerminal;
+type BoundedAttemptResult<Accepted extends Readonly<{
+    kind: "accepted";
+}>, Refusal> = Accepted | Readonly<{
+    kind: "refused";
+    refusal: Refusal;
+}> | Readonly<{
+    kind: "stale";
+}> | Readonly<{
+    kind: "redecide";
+}> | AttemptTerminal;
+/**
+ * Classify one bounded sequence of fresh semantic attempts. The callback owns every verb-specific
+ * observation, preparation, decision, and publication; this function only decides whether its
+ * result is terminal or whether the next fresh context may be tried.
+ */
+export declare function runBoundedAttempts<Accepted extends Readonly<{
+    kind: "accepted";
+}>, Refusal>(attempts: readonly AttemptContext[], attempt: (context: AttemptContext, index: number) => Promise<BoundedAttemptResult<Accepted, Refusal>>): Promise<Accepted | Readonly<{
+    kind: "refused";
+    refusal: Refusal;
+}> | ProtocolTerminal>;
 export type CompanionDecorator = (input: Readonly<{
     repository: GitRepository;
     observation: GitDecisionObservation;
@@ -61,7 +90,7 @@ type ProtocolAdmission<Input extends Readonly<{
 }>, Refusal> = Readonly<{
     channel: GitDecodeChannel;
     repository: GitRepository;
-    progress?: ExecutionProgress;
+    progress?: ProtocolProgress;
     contracts: readonly ContractId[];
     attempts: readonly AttemptContext[];
     decide: (input: DecideInput<Input>) => OfferDecision<Refusal>;

package/build/src/protocol/run.js

@@ -1,3 +1,5 @@
+import { z } from "zod";
+import { publicationFailedSchema } from "../git/admission.js";
 import { extendAdmissionPathsAt, observeContractsForAdmissionAt } from "../git/observe.js";
 import { appendPrivateStateSeatClose, isPrivateStateSeatContention, mergePrivateStateSeatClose, withPrivateStatePublicationSeat, } from "../git/private-state-seat.js";
 import { GIT_REF, readRefs } from "../git/repository.js";
@@ -5,6 +7,25 @@ import { admitDecidedOffer } from "./attempt.js";
 export const STALE_PRIVATE_STATE_PREPARATION = {
     kind: "stale",
 };
+export const protocolTerminalSchema = z.union([
+    z.object({ kind: z.enum(["exhausted", "collision"]) }).strict(),
+    publicationFailedSchema,
+]);
+/**
+ * Classify one bounded sequence of fresh semantic attempts. The callback owns every verb-specific
+ * observation, preparation, decision, and publication; this function only decides whether its
+ * result is terminal or whether the next fresh context may be tried.
+ */
+export async function runBoundedAttempts(attempts, attempt) {
+    for (let index = 0; index < attempts.length; index += 1) {
+        const result = await attempt(attempts[index], index);
+        if (result.kind === "accepted" || result.kind === "refused" || result.kind === "publication-failed")
+            return result;
+        if (result.kind === "collision" && index + 1 === attempts.length)
+            return result;
+    }
+    return { kind: "exhausted" };
+}
 export function contractStateWitness(state) {
     return { head: state.head };
 }
@@ -158,16 +179,7 @@ async function prepareDirectProtocolAttempt(input, baseAttempt) {
 }
 /** Run bounded, verb-neutral attempts and return one real admission on acceptance. */
 export async function runProtocol(input) {
-    const attempts = input.attempts;
-    for (let index = 0; index < attempts.length; index += 1) {
-        const attempt = attempts[index];
-        const result = input.preparation === undefined
-            ? await runDirectProtocolAttempt(input, attempt)
-            : await runSplitProtocolAttempt(input, attempt);
-        if (result.kind === "refused" || result.kind === "accepted" || result.kind === "publication-failed")
-            return result;
-        if (result.kind === "collision" && index + 1 === attempts.length)
-            return result;
-    }
-    return { kind: "exhausted" };
+    return await runBoundedAttempts(input.attempts, (attempt) => input.preparation === undefined
+        ? runDirectProtocolAttempt(input, attempt)
+        : runSplitProtocolAttempt(input, attempt));
 }

package/build/src/settings.d.ts

@@ -46,16 +46,6 @@ export declare class SettingsError extends Error {
     readonly kind = "settings";
     constructor(message: string);
 }
-export type Gate = string;
-export type GatesFromInput = Readonly<{
-    settings: Settings;
-    names?: readonly string[];
-}>;
-export type RequireBranchesToBeUpToDateFromInput = Readonly<{
-    settings: Settings;
-}>;
 export declare function settings(input?: SettingsInput): Promise<Settings>;
 /** Read only the project scope owned by a materialized candidate snapshot. */
 export declare function projectSettings(root: string): Promise<Settings>;
-export declare function gatesFrom(input: GatesFromInput): readonly Gate[];
-export declare function requireBranchesToBeUpToDateFrom(input: RequireBranchesToBeUpToDateFromInput): boolean;