@astrosheep/keiyaku 4.5.19 → 4.5.21

package/build/src/protocol/review.js

@@ -2,7 +2,7 @@ import { worktreeChangeId } from "../git/integration.js";
 import { captureTender, dirtyTenderDelta, dirtyTenderRefusal, } from "../git/tender.js";
 import { observeContractsForAdmissionAt } from "../git/observe.js";
 import { unmergedWorkspacePaths, worktreePath } from "../git/workspace.js";
-import { matchingPrivateRootObservation, privateStateSeatAttempt, sameSpeculativeWorktreeInput, } from "./run.js";
+import { contractStateWitness, privateStateSeatAttempt, 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";
@@ -58,14 +58,14 @@ export async function prepareReview(repository, stage) {
         },
     };
 }
-function preparedReviewCapture(input, state, prepared) {
+function preparedReviewCapture(input, state, changeId) {
     return {
         kind: "prepared",
         data: {
             gate: REVIEWED,
             subject: dependencyKeySet([
                 { kind: "document", value: state.terms.document.key },
-                { kind: "change", value: prepared.data.changeId },
+                { kind: "change", value: changeId },
             ]),
             verdict: input.verdict,
             ...(input.summary === undefined ? {} : { summary: input.summary }),
@@ -88,32 +88,56 @@ async function recaptureReviewWorktree(input, state) {
     });
     return prepared.kind === "prepared" ? reviewWorktreeInput(prepared) : undefined;
 }
-async function speculateReview(input) {
+/** Capture the reviewable worktree from one non-authoritative private-state read. */
+async function prepareExternalReview(input) {
     const observation = await observeContractsForAdmissionAt(input.scope, input.channel, [input.contractId]);
     const state = contractState(observation.decision, input.contractId);
     if (state === null)
-        return { observation };
+        return { kind: "unavailable" };
     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 {
+        kind: "artifacts",
+        witness: contractStateWitness(state),
+        artifacts: prepared.kind === "refused"
+            ? { kind: "refused", refusal: prepared.refusal }
+            : {
+                kind: "captured",
+                ...(prepared.data.workspace === undefined ? {} : { workspace: prepared.data.workspace }),
+                worktree: reviewWorktreeInput(prepared),
+            },
+    };
+}
+/** Assemble the in-custody attestation input from the fresh Contract and validated artifacts. */
+async function assembleReviewAttempt(input, observation, external) {
+    const state = contractState(observation.decision, input.contractId);
+    if (external.kind === "unavailable")
+        return state === null ? { kind: "assembled" } : { kind: "stale" };
+    if (state === null)
+        return { kind: "stale" };
+    if (external.witness.head !== state.head)
+        return { kind: "stale" };
+    if (external.artifacts.kind === "refused") {
+        return { kind: "assembled", preparation: { kind: "refused", refusal: external.artifacts.refusal } };
+    }
+    if (!sameWorktreeWitness(external.artifacts.worktree, await recaptureReviewWorktree(input, state))) {
+        return { kind: "stale" };
     }
     return {
-        observation,
-        preparation: preparedReviewCapture(input, state, prepared),
-        ...(prepared.data.workspace === undefined ? {} : { workspace: prepared.data.workspace }),
-        worktree: reviewWorktreeInput(prepared),
+        kind: "assembled",
+        preparation: preparedReviewCapture(input, state, external.artifacts.worktree.changeId),
+        ...(external.artifacts.workspace === undefined ? {} : { workspace: external.artifacts.workspace }),
     };
 }
-async function decideAndAdmitReview(input, attempt, seat, observation, speculated) {
+async function decideAndAdmitReview(input, attempt, seat, observation, assembled) {
     const decision = decideAttestation({
         input: {
             contractId: input.contractId,
             ...(input.actor === undefined ? {} : { actor: input.actor }),
             at: timestamp(),
-            ...(speculated.preparation === undefined ? {} : { preparation: speculated.preparation }),
+            ...(assembled.preparation === undefined ? {} : { preparation: assembled.preparation }),
         },
         attempt,
         observation: observation.decision,
@@ -128,33 +152,30 @@ async function decideAndAdmitReview(input, attempt, seat, observation, speculate
         attempt,
         offer: decision.offer,
         primaryContract: input.contractId,
-        ...(input.progress === undefined ? {} : input.progress === undefined ? {} : { progress: input.progress }),
+        ...(input.progress === undefined ? {} : { progress: input.progress }),
     });
     if (admission.kind !== "accepted")
         return admission;
     return {
         ...admission,
         value: {
-            ...(speculated.workspace === undefined ? {} : { workspace: speculated.workspace }),
+            ...(assembled.workspace === undefined ? {} : { workspace: assembled.workspace }),
         },
     };
 }
-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);
-}
+/**
+ * One review attempt: the repeatable worktree capture happens outside custody, then a single
+ * in-custody observation, witness validation, subject assembly, decision, and publication.
+ */
 async function reviewAttempt(input, attempt) {
-    const speculated = await speculateReview(input);
-    return await privateStateSeatAttempt(input.scope, async (seat) => await reviewAttemptInPrivateStateSeat(input, attempt, seat, speculated), attemptDecisionWithSeatClose);
+    const external = await prepareExternalReview(input);
+    return await privateStateSeatAttempt(input.scope, async (seat) => {
+        const observation = await observeContractsForAdmissionAt(input.scope, input.channel, [input.contractId]);
+        const assembled = await assembleReviewAttempt(input, observation, external);
+        if (assembled.kind === "stale")
+            return STALE_PRIVATE_STATE_PREPARATION;
+        return await decideAndAdmitReview(input, attempt, seat, observation, assembled);
+    }, attemptDecisionWithSeatClose);
 }
 export async function admitReviewOperation(input) {
     const attempts = mintAttempts({ entryCount: 1 });
@@ -167,6 +188,8 @@ export async function admitReviewOperation(input) {
         }
         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 };
     }

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

@@ -3,15 +3,14 @@ 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 GitOid, type GitRefAssertion } from "../git/repository.js";
+import { 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 ChangeId, type ContractId, type SnapshotId } from "../core/facts/types.js";
-import { type AcceptedAdmission, type AttemptTerminal } from "./attempt.js";
+import type { ChangeId, ContractHead, ContractId, SnapshotId } from "../core/facts/types.js";
 import type { GitObjectId } from "../git/identity.js";
+import { type AcceptedAdmission, type AttemptTerminal } from "./attempt.js";
 export declare const STALE_PRIVATE_STATE_PREPARATION: {
-    readonly kind: "publication-failed";
-    readonly diagnostic: "stale private-state preparation";
+    readonly kind: "stale";
 };
 export type ProtocolTerminal = Readonly<{
     kind: "exhausted";
@@ -26,11 +25,40 @@ export type CompanionDecorator = (input: Readonly<{
     contractId: ContractId;
     offer: Offer;
 }>) => readonly TreeUpdate[] | Promise<readonly TreeUpdate[]>;
-export type RunProtocolInput<Input extends Readonly<{
-    contractId: ContractId;
-}>, Refusal, Seed extends Readonly<{
+/**
+ * Seat-external preparation: immutable artifacts plus the currentness witnesses they carry.
+ * It never observes private state as authority and never forms an offer.
+ */
+export type ExternalProtocolPreparation<Prepared, Refusal> = Readonly<{
+    kind: "prepared";
+    prepared: Prepared;
+    assertions?: readonly GitRefAssertion[];
+}> | Readonly<{
+    kind: "refused";
+    refusal: Refusal;
+}>;
+/**
+ * In-custody assembly of one decision input from the fresh observation and an external artifact.
+ * `stale` means only that the outside preparation is spent: discard it and restart the cycle.
+ */
+export type InCustodyProtocolPreparation<Input, Refusal> = Readonly<{
+    kind: "prepared";
+    input: Input;
+    assertions?: readonly GitRefAssertion[];
+}> | Readonly<{
+    kind: "stale";
+}> | Readonly<{
+    kind: "refused";
+    refusal: Refusal;
+}>;
+/** The one split-preparation mechanism: repeatable work outside custody, assembly inside it. */
+export type ProtocolPreparation<Input, Refusal, Seed, Prepared> = Readonly<{
+    external: (seed: Seed) => ExternalProtocolPreparation<Prepared, Refusal> | Promise<ExternalProtocolPreparation<Prepared, Refusal>>;
+    assemble: (observation: GitDecisionObservation, seed: Seed, prepared: Prepared) => InCustodyProtocolPreparation<Input, Refusal> | Promise<InCustodyProtocolPreparation<Input, Refusal>>;
+}>;
+type ProtocolAdmission<Input extends Readonly<{
     contractId: ContractId;
-}> = Input> = Readonly<{
+}>, Refusal> = Readonly<{
     channel: GitDecodeChannel;
     repository: GitRepository;
     progress?: ExecutionProgress;
@@ -45,28 +73,31 @@ export type RunProtocolInput<Input extends Readonly<{
     decorateOffer?: CompanionDecorator;
     validateAdmission?: (observation: GitDecisionObservation) => Refusal | undefined | Promise<Refusal | undefined>;
     observationSelection?: GitTreeSelection;
-}> & (Readonly<{
-    input: Input;
-    prepareInput?: never;
-}> | Readonly<{
+}>;
+/** An intent whose invocation is already its decision input. */
+export type DirectRunProtocolInput<Seed extends Readonly<{
+    contractId: ContractId;
+}>, Refusal> = ProtocolAdmission<Seed, Refusal> & Readonly<{
+    input: Seed;
+    preparation?: undefined;
+}>;
+/** An intent whose repeatable preparation runs outside custody and is assembled inside it. */
+export type SplitRunProtocolInput<Input extends Readonly<{
+    contractId: ContractId;
+}>, Refusal, Seed extends Readonly<{
+    contractId: ContractId;
+}>, Prepared> = ProtocolAdmission<Input, Refusal> & Readonly<{
     input: Seed;
-    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;
-    }>>;
-}>);
+    preparation: ProtocolPreparation<Input, Refusal, Seed, Prepared>;
+}>;
+export type RunProtocolInput<Input extends Readonly<{
+    contractId: ContractId;
+}>, Refusal, Seed extends Readonly<{
+    contractId: ContractId;
+}> = Input, Prepared = Seed> = DirectRunProtocolInput<Seed, Refusal> | SplitRunProtocolInput<Input, Refusal, Seed, Prepared>;
 export type PreparedProtocolAttempt<Refusal> = Readonly<{
+    kind: "stale";
+}> | Readonly<{
     kind: "refused";
     refusal: Refusal;
 }> | Readonly<{
@@ -76,29 +107,45 @@ 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<{
+/**
+ * The private-state witness a seat-external preparation was computed against. Equal journal heads
+ * mean the same decoded contract state, so the same document, coordinates, and facts.
+ */
+export type ContractStateWitness = Readonly<{
+    head: ContractHead | null;
+}>;
+export declare function contractStateWitness(state: ContractStateWitness): ContractStateWitness;
+/**
+ * A physical worktree capture carried across custody as a witness, never as authority.
+ *
+ * Unlike a ref or a journal head, uncommitted worktree bytes are covered by no atomic
+ * compare-and-swap, so the only sound proof that a seat-external capture still describes the
+ * bytes about to be published is a fresh capture compared against this witness under custody.
+ * A cheaper structural signature (head, merge head, dirty flag, changed paths) cannot judge it:
+ * a writer that rewrites an already-changed path - a conflict materialization, for instance -
+ * leaves every path-level signature identical while the bytes that would be published differ.
+ */
+export type WorktreeWitness = 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 sameWorktreeWitness(prepared: WorktreeWitness | undefined, fresh: WorktreeWitness | 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;
 }>, Refusal, Seed extends Readonly<{
     contractId: ContractId;
-}> = Input>(input: RunProtocolInput<Input, Refusal, Seed>, baseAttempt: AttemptContext): Promise<PreparedProtocolAttempt<Refusal>>;
+}> = Input, Prepared = Seed>(input: RunProtocolInput<Input, Refusal, Seed, Prepared>, baseAttempt: AttemptContext): Promise<PreparedProtocolAttempt<Refusal>>;
 /** Run bounded, verb-neutral attempts and return one real admission on acceptance. */
 export declare function runProtocol<Input extends Readonly<{
     contractId: ContractId;
 }>, Refusal, Seed extends Readonly<{
     contractId: ContractId;
-}> = Input>(input: RunProtocolInput<Input, Refusal, Seed>): Promise<ProtocolResult<Refusal>>;
+}> = Input, Prepared = Seed>(input: RunProtocolInput<Input, Refusal, Seed, Prepared>): Promise<ProtocolResult<Refusal>>;
+export {};

package/build/src/protocol/run.js

@@ -3,16 +3,12 @@ import { appendPrivateStateSeatClose, isPrivateStateSeatContention, mergePrivate
 import { GIT_REF, readRefs } from "../git/repository.js";
 import { admitDecidedOffer } from "./attempt.js";
 export const STALE_PRIVATE_STATE_PREPARATION = {
-    kind: "publication-failed",
-    diagnostic: "stale private-state preparation",
+    kind: "stale",
 };
-export function privateRootCommit(observation) {
-    return observation.admission.snapshot.commit;
+export function contractStateWitness(state) {
+    return { head: state.head };
 }
-export function samePrivateRootObservation(prepared, fresh) {
-    return privateRootCommit(prepared) === privateRootCommit(fresh);
-}
-export function sameSpeculativeWorktreeInput(prepared, fresh) {
+export function sameWorktreeWitness(prepared, fresh) {
     if (prepared === undefined || fresh === undefined)
         return prepared === fresh;
     return (prepared.tree === fresh.tree &&
@@ -32,14 +28,6 @@ export function publicationFailedFromSeatError(error) {
         return { kind: "publication-failed", diagnostic: error.message };
     throw error;
 }
-export async function matchingPrivateRootObservation(repository, channel, contractId, prepared, revalidate) {
-    const fresh = await observeContractsForAdmissionAt(repository, channel, [contractId]);
-    if (!samePrivateRootObservation(prepared, fresh))
-        return STALE_PRIVATE_STATE_PREPARATION;
-    if (revalidate !== undefined && !(await revalidate(fresh)))
-        return STALE_PRIVATE_STATE_PREPARATION;
-    return fresh;
-}
 export async function privateStateSeatAttempt(repository, action, wrap) {
     try {
         return wrap(await withPrivateStatePublicationSeat(repository, action));
@@ -53,30 +41,23 @@ async function observeProtocolDecision(input) {
         ? await observeContractsForAdmissionAt(input.repository, input.channel, input.contracts, input.observationSelection)
         : await input.observe(input.repository, input.channel, input.contracts);
 }
-async function prepareProtocolSeed(input, observation) {
-    if (!("prepareInput" in input) || input.prepareInput === undefined) {
-        return { kind: "prepared", input: input.input, assertions: [] };
-    }
-    const prepared = await input.prepareInput(observation, input.input);
-    return prepared.kind === "refused" ? prepared : { ...prepared, assertions: prepared.assertions ?? [] };
-}
-async function decideDecoratedProtocolOffer(input, baseAttempt, decisionObservation, preparedInput) {
-    const attempt = input.extendAttempt === undefined
-        ? baseAttempt
-        : input.extendAttempt(baseAttempt, decisionObservation.decision.size);
-    const decision = input.decide({
-        input: preparedInput.input,
+async function decideDecoratedProtocolOffer(admission, primaryContract, decisionObservation, prepared) {
+    const attempt = admission.extendAttempt === undefined
+        ? prepared.attempt
+        : admission.extendAttempt(prepared.attempt, decisionObservation.decision.size);
+    const decision = admission.decide({
+        input: prepared.input,
         attempt,
         observation: decisionObservation.decision,
     });
     if (decision.kind === "refused")
         return decision;
-    const companions = input.decorateOffer === undefined
+    const companions = admission.decorateOffer === undefined
         ? []
-        : await input.decorateOffer({
-            repository: input.repository,
+        : await admission.decorateOffer({
+            repository: admission.repository,
             observation: decisionObservation,
-            contractId: input.input.contractId,
+            contractId: primaryContract,
             offer: decision.offer,
         });
     const offer = companions.length === 0
@@ -84,22 +65,31 @@ async function decideDecoratedProtocolOffer(input, baseAttempt, decisionObservat
         : { ...decision.offer, companions: [...(decision.offer.companions ?? []), ...companions] };
     const admissionObservation = companions.length === 0
         ? decisionObservation
-        : await extendAdmissionPathsAt(input.channel, decisionObservation, companions.map(({ path }) => path));
+        : await extendAdmissionPathsAt(admission.channel, decisionObservation, companions.map(({ path }) => path));
     return {
         kind: "offered",
         observation: admissionObservation,
         attempt,
         offer,
-        assertions: preparedInput.assertions,
+        assertions: prepared.assertions,
     };
 }
-/** Form one decided offer without admitting or reinterpreting it. */
-export async function prepareProtocolAttempt(input, baseAttempt) {
-    const decisionObservation = await observeProtocolDecision(input);
-    const preparedInput = await prepareProtocolSeed(input, decisionObservation);
-    if (preparedInput.kind === "refused")
-        return preparedInput;
-    return await decideDecoratedProtocolOffer(input, baseAttempt, decisionObservation, preparedInput);
+async function admitDecidedProtocolOffer(admission, primaryContract, seat, decisionObservation, prepared) {
+    const decided = await decideDecoratedProtocolOffer(admission, primaryContract, decisionObservation, prepared);
+    if (decided.kind === "refused")
+        return decided;
+    return await admitDecidedOffer({
+        channel: admission.channel,
+        repository: admission.repository,
+        seat,
+        decisionObservation: decided.observation,
+        attempt: decided.attempt,
+        offer: decided.offer,
+        primaryContract,
+        ...(admission.progress === undefined ? {} : { progress: admission.progress }),
+        assertions: decided.assertions,
+        ...(admission.validateAdmission === undefined ? {} : { validateAdmission: admission.validateAdmission }),
+    });
 }
 function protocolAttemptWithSeatClose(outcome) {
     return mergePrivateStateSeatClose(outcome, (value, closeLag) => {
@@ -108,47 +98,72 @@ function protocolAttemptWithSeatClose(outcome) {
         return { ...value, seatClose: appendPrivateStateSeatClose(value.seatClose, closeLag) };
     });
 }
-async function speculateProtocolAttempt(input) {
-    const observation = await observeProtocolDecision(input);
-    const prepared = await prepareProtocolSeed(input, observation);
-    return prepared.kind === "refused" ? prepared : { observation, ...prepared };
+async function runDirectProtocolAttempt(input, attempt) {
+    return await privateStateSeatAttempt(input.repository, async (seat) => {
+        const observation = await observeProtocolDecision(input);
+        return await admitDecidedProtocolOffer(input, input.input.contractId, seat, observation, {
+            attempt,
+            input: input.input,
+            assertions: [],
+        });
+    }, protocolAttemptWithSeatClose);
+}
+/**
+ * One full attempt: repeatable preparation outside custody, then a single in-custody cycle of
+ * observation, witness validation, assembly, decision, companions, and atomic publication.
+ */
+async function runSplitProtocolAttempt(input, attempt) {
+    const external = await input.preparation.external(input.input);
+    if (external.kind === "refused")
+        return external;
+    return await privateStateSeatAttempt(input.repository, async (seat) => {
+        const observation = await observeProtocolDecision(input);
+        const assembled = await input.preparation.assemble(observation, input.input, external.prepared);
+        if (assembled.kind !== "prepared")
+            return assembled;
+        const assertions = [...(external.assertions ?? []), ...(assembled.assertions ?? [])];
+        if (!(await privateStateAssertionsMatch(input.repository, assertions)))
+            return STALE_PRIVATE_STATE_PREPARATION;
+        return await admitDecidedProtocolOffer(input, input.input.contractId, seat, observation, {
+            attempt,
+            input: assembled.input,
+            assertions,
+        });
+    }, protocolAttemptWithSeatClose);
 }
-async function admitSpeculativeProtocolAttempt(input, seat, speculated, attempt) {
-    const fresh = await observeProtocolDecision(input);
-    if (!samePrivateRootObservation(speculated.observation, fresh) ||
-        !(await privateStateAssertionsMatch(input.repository, speculated.assertions))) {
-        return STALE_PRIVATE_STATE_PREPARATION;
-    }
-    const decided = await decideDecoratedProtocolOffer(input, attempt, fresh, {
-        kind: "prepared",
-        input: speculated.input,
-        assertions: speculated.assertions,
-    });
-    if (decided.kind === "refused")
-        return decided;
-    return await admitDecidedOffer({
-        channel: input.channel,
-        repository: input.repository,
-        seat,
-        decisionObservation: decided.observation,
-        attempt: decided.attempt,
-        offer: decided.offer,
-        primaryContract: input.input.contractId,
-        ...(input.progress === undefined ? {} : input.progress === undefined ? {} : { progress: input.progress }),
-        assertions: decided.assertions,
-        ...(input.validateAdmission === undefined ? {} : { validateAdmission: input.validateAdmission }),
+/** Form one decided offer without admitting or reinterpreting it. */
+export async function prepareProtocolAttempt(input, baseAttempt) {
+    if (input.preparation === undefined)
+        return await prepareDirectProtocolAttempt(input, baseAttempt);
+    const external = await input.preparation.external(input.input);
+    if (external.kind === "refused")
+        return external;
+    const decisionObservation = await observeProtocolDecision(input);
+    const assembled = await input.preparation.assemble(decisionObservation, input.input, external.prepared);
+    if (assembled.kind !== "prepared")
+        return assembled;
+    return await decideDecoratedProtocolOffer(input, input.input.contractId, decisionObservation, {
+        attempt: baseAttempt,
+        input: assembled.input,
+        assertions: [...(external.assertions ?? []), ...(assembled.assertions ?? [])],
     });
 }
-async function runSpeculativeProtocolAttempt(input, speculated, attempt) {
-    if (speculated.kind === "refused")
-        return speculated;
-    return await privateStateSeatAttempt(input.repository, async (seat) => await admitSpeculativeProtocolAttempt(input, seat, speculated, attempt), protocolAttemptWithSeatClose);
+async function prepareDirectProtocolAttempt(input, baseAttempt) {
+    const decisionObservation = await observeProtocolDecision(input);
+    return await decideDecoratedProtocolOffer(input, input.input.contractId, decisionObservation, {
+        attempt: baseAttempt,
+        input: input.input,
+        assertions: [],
+    });
 }
 /** 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 result = await runSpeculativeProtocolAttempt(input, await speculateProtocolAttempt(input), attempts[index]);
+        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)

package/build/src/runtime/proc/run.d.ts

@@ -8,6 +8,11 @@ type ProcessLaunch = Readonly<{
     readonly cwd?: string;
     readonly env?: NodeJS.ProcessEnv;
     readonly signal?: AbortSignal;
+    /** @internal Mechanical output observation only; it does not affect process ownership or outcome. */
+    readonly onOutput?: (output: Readonly<{
+        stream: "stdout" | "stderr";
+        text: string;
+    }>) => void;
 }>;
 export type CancellableProcess = Readonly<{
     child: ChildProcess;
@@ -27,23 +32,30 @@ type ProcessTerminal = Readonly<{
     readonly stderr: string;
     readonly truncated: boolean;
 }>;
+type ProcessCapture = Readonly<{
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly truncated: boolean;
+}>;
 type ProcessTimeout = Readonly<{
     readonly kind: "timeout";
-}>;
+}> & ProcessCapture;
 type ProcessSpawnError = Readonly<{
     readonly kind: "spawn-error";
     readonly diagnostic: string;
-}>;
+}> & ProcessCapture;
 type ProcessUnknownExit = Readonly<{
     readonly kind: "unknown-exit";
-}>;
+}> & ProcessCapture;
 type ProcessCancelled = Readonly<{
     readonly kind: "cancelled";
-}>;
+}> & ProcessCapture;
 export type ProcessOutcome = ProcessTerminal | ProcessTimeout | ProcessSpawnError | ProcessUnknownExit | ProcessCancelled;
 type ProcessStreamError = Readonly<{
     readonly kind: "stream-error";
     readonly diagnostic: string;
+    readonly stderr: string;
+    readonly truncated: boolean;
 }>;
 export type ProcessConsumption = Readonly<{
     readonly outcome: ProcessOutcome | ProcessStreamError;