@astrosheep/keiyaku 4.0.0 → 4.0.1

package/build/src/protocol/operations.js

@@ -1,8 +1,9 @@
-import { prepareDelivery, prepareReview, } from "../git/delivery.js";
-import { currentBranch, extendContractsForAdmission, observeGit, observeContract, observeContractsForAdmission, } from "../git/observe.js";
-import { reconcile, reconcileBatch, reconcileObservationFailure } from "../git/reconcile.js";
+import { materializeIntegrationSnapshot, planIntegration, prepareReviewIntegration, readDeliveryDiff, } from "../git/integration.js";
+import { captureTender, dirtyTenderDelta, dirtyTenderRefusal, materializeTenderSnapshot, } from "../git/tender.js";
+import { currentBranch, extendContractsForAdmissionAt, observeContractAt, observeContractWorld, observeContractsForAdmissionAt, } from "../git/observe.js";
+import { reconcile, reconcileBatch, reconcileObservationFailure, } from "../git/reconcile.js";
 import { NoGitWorldError, repositoryAt } from "../git/repository.js";
-import { readDeliveryDiff } from "../git/verification.js";
+import { withGitReadObservation } from "../git/read-observation.js";
 import { dependencyKeySet } from "../core/subject.js";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { contractState, documentIsCurrent } from "../core/facts/observation.js";
@@ -12,102 +13,190 @@ import { decideAmend } from "../core/verbs/amend.js";
 import { decideArc } from "../core/verbs/arc.js";
 import { decideDeliver } from "../core/verbs/deliver.js";
 import { decideAttestation } from "../core/verbs/attestation.js";
-import { produceVerification } from "../verification/producer.js";
-import { admitIntent, admitPlacement, mintAttempts, verifyDelivery } from "./intent.js";
-import { auditReport, readAudit } from "./read/audit.js";
+import { admitIntent, verifyDelivery, } from "./intent.js";
+import { admitPlacement } from "./placement.js";
+import { auditReport, readAuditAt } from "./read/audit.js";
 import { readDocuments } from "./read/documents.js";
-import { readContractBoard, readContractObservation, } from "./read/status.js";
-import { admitDecidedOffer } from "./attempt.js";
+import { readContractBoard, readContractObservationAt, } from "./read/status.js";
+import { admitDecidedOffer, mintAttempts } from "./attempt.js";
 export { bindOperation } from "./bind.js";
-import { accepted, admitted, complete } from "./outcome.js";
+import { accepted, admitted, complete, } from "./outcome.js";
 const REVIEWED = gate("reviewed");
 function timestamp() { return new Date().toISOString(); }
 function mergeAdmissions(current, next) {
-    return { ...next, facts: [...current.facts, ...next.facts] };
+    const effects = [...(current.physical?.effects ?? []), ...(next.physical?.effects ?? [])];
+    const lag = [...(current.physical?.lag ?? []), ...(next.physical?.lag ?? [])];
+    return {
+        ...next,
+        facts: [...current.facts, ...next.facts],
+        ...(effects.length === 0 && lag.length === 0 ? {} : { physical: { effects, lag } }),
+    };
 }
 function stepStop(result) {
     if (result.kind === "accepted")
         return undefined;
     return result.kind === "refused" ? { refusal: result.refusal } : { retry: result };
 }
+function verificationStop(step) {
+    return "failure" in step ? step : stepStop(step);
+}
+function placementStop(result) {
+    if (result.kind === "accepted")
+        return undefined;
+    if (result.kind === "placement-failed") {
+        return { failure: "target-placement-failed", diagnostic: result.diagnostic };
+    }
+    if (result.kind === "target-moved") {
+        const { contractId, target, expected, observed } = result;
+        return { failure: "target-moved", contractId, target, expected, observed };
+    }
+    return result.kind === "refused" ? { refusal: result.refusal } : { retry: result };
+}
 export { NoGitWorldError };
 export function scopeOperation(input) { return repositoryAt(input.coordinate); }
 export function currentBranchOperation(input) {
     return currentBranch(input.scope);
 }
-export function contractsOperation(input) { return readContractBoard(input.scope); }
+export async function contractsOperation(input) {
+    return withGitReadObservation(input.scope, input.channel, readContractBoard);
+}
 export function contractObservationOperation(input) {
-    return readContractObservation(input.scope, input.contractId);
+    return readContractObservationAt(input.scope, input.channel, input.contractId);
 }
-export function documentsOperation(input) { return readDocuments(input.scope); }
-export function stateOperation(input) {
-    const state = observeContract(input.scope, input.contractId).state;
+export async function documentsOperationAt(scope, channel) {
+    return withGitReadObservation(scope, channel, readDocuments);
+}
+export async function stateOperation(input) {
+    const state = (await observeContractAt(input.scope, input.channel, input.contractId)).state;
     if (state === null)
         throw new Error(`contract does not exist: ${input.contractId}`);
     return state;
 }
-export function readStateOperation(input) { return observeContract(input.scope, input.contractId).state; }
-export function deliveryOperation(input) {
-    const state = observeContract(input.scope, input.contractId).state;
-    if (state === null || state.delivery === null)
-        return null;
-    return {
-        snapshotId: state.delivery.data.candidate,
-        changeId: state.delivery.data.deliveryPatchId,
-        expectedPredecessor: state.delivery.data.expectedPredecessor,
-    };
+export async function deliveryOperation(input) {
+    const state = (await observeContractAt(input.scope, input.channel, input.contractId)).state;
+    return state?.delivery?.data ?? null;
 }
-function observePrerequisiteClosure(repository, contracts) {
-    let observation = observeContractsForAdmission(repository, contracts);
-    let frontier = contracts.slice(1);
-    while (frontier.length > 0) {
-        const next = new Set();
-        for (const id of frontier) {
-            const state = contractState(observation.decision, id);
-            if (state === null)
-                continue;
-            for (const dependency of state.terms.after) {
-                if (!observation.decision.has(dependency))
-                    next.add(dependency);
-            }
+export async function deliveryDiffOperation(input) { return readDeliveryDiff(input.scope, input.integrationPredecessor, input.integrationSnapshot); }
+export async function amendOperation(input) {
+    const attempts = mintAttempts({ entryCount: 1 });
+    let source = input.source;
+    for (let index = 0; index < attempts.length; index += 1) {
+        let observation = await observeContractsForAdmissionAt(input.scope, input.channel, [input.contractId]);
+        const state = contractState(observation.decision, input.contractId);
+        if (source === undefined && state !== null)
+            source = state.terms;
+        const amendment = source === undefined || input.deriveAmendment === undefined
+            ? undefined
+            : { source, ...input.deriveAmendment(source) };
+        if (amendment !== undefined) {
+            observation = await extendContractsForAdmissionAt(input.channel, observation, [...new Set([...(state?.terms.after ?? []), ...amendment.terms.after])]);
+        }
+        const preparation = amendment === undefined
+            ? undefined
+            : amendment.verification.kind === "prepared"
+                ? { kind: "prepared", data: amendment.terms }
+                : { kind: "refused", refusal: amendment.verification.refusal };
+        const decision = decideAmend({
+            input: {
+                contractId: input.contractId,
+                ...(input.actor === undefined ? {} : { actor: input.actor }),
+                at: timestamp(),
+                ...(amendment === undefined ? {} : { source: amendment.source }),
+                ...(preparation === undefined ? {} : { preparation }),
+            },
+            attempt: attempts[index],
+            observation: observation.decision,
+        });
+        if (decision.kind === "refused")
+            return decision;
+        const admission = await admitDecidedOffer({
+            channel: input.channel,
+            repository: input.scope,
+            decisionObservation: observation,
+            attempt: attempts[index],
+            offer: decision.offer,
+            primaryContract: input.contractId,
+        });
+        if (admission.kind === "accepted") {
+            if (amendment === undefined)
+                throw new Error("accepted amendment is missing its document derivation");
+            return admitted(admission, amendment);
         }
-        frontier = [...next];
-        observation = extendContractsForAdmission(repository, observation, frontier);
+        if (admission.kind === "publication-failed")
+            return { kind: "retry", reason: admission };
+        if (admission.kind === "collision" && index + 1 === attempts.length)
+            return { kind: "retry", reason: admission };
     }
-    return observation;
+    return { kind: "retry", reason: { kind: "exhausted" } };
 }
-export async function deliveryDiffOperation(input) { return readDeliveryDiff(input.scope, input.expectedPredecessor, input.snapshotId); }
-export function amendOperation(input) {
-    const amendment = input.amendment;
-    const preparation = amendment === undefined
-        ? undefined
-        : amendment.verification.kind === "prepared"
-            ? { kind: "prepared", data: amendment.terms }
-            : { kind: "refused", refusal: amendment.verification.refusal };
-    const decisionInput = {
-        contractId: input.contractId,
-        ...(input.actor === undefined ? {} : { actor: input.actor }),
-        at: timestamp(),
-        ...(amendment === undefined ? {} : { source: amendment.source }),
-        ...(preparation === undefined ? {} : { preparation }),
+export function prepareDelivery(repository, stage, input) {
+    const { contractId, coordinates } = stage;
+    if (coordinates.workspace === "here" && coordinates.target !== undefined) {
+        const branch = currentBranch(repository);
+        if (branch !== coordinates.target) {
+            return { kind: "refused", refusal: { kind: "workspace-not-on-target", contractId, target: coordinates.target, branch } };
+        }
+    }
+    const tender = captureTender(repository, stage);
+    if (tender.kind === "refused")
+        return tender;
+    if ((tender.data.dirty && input.includeDirty !== true) || tender.data.changes.submodules.length > 0) {
+        return { kind: "refused", refusal: dirtyTenderRefusal(repository, contractId, tender.data) };
+    }
+    const tenderSnapshot = materializeTenderSnapshot(repository, tender.data, {
+        contractId,
+        title: input.title,
+        ...(input.message === undefined ? {} : { message: input.message }),
+    });
+    const requireBranchesToBeUpToDate = input.requireBranchesToBeUpToDate ?? false;
+    const integration = planIntegration(repository, stage, { ...tender.data, head: tenderSnapshot }, requireBranchesToBeUpToDate);
+    if (integration.kind === "refused")
+        return integration;
+    const integrationSnapshot = coordinates.target === undefined
+        ? tenderSnapshot
+        : materializeIntegrationSnapshot(repository, integration.data.tree, integration.data.predecessor, {
+            contractId,
+            title: input.title,
+            ...(input.message === undefined ? {} : { message: input.message }),
+        });
+    return {
+        kind: "prepared",
+        data: {
+            tenderSnapshot,
+            integration: { predecessor: integration.data.predecessor, snapshot: integrationSnapshot, changeId: integration.data.changeId },
+            method: "squash",
+            policy: { requireBranchesToBeUpToDate },
+        },
     };
-    return complete(admitIntent(input.scope, decisionInput, decideAmend, {
-        observedContracts: [input.contractId, ...(amendment?.terms.after ?? [])],
-        observe: observePrerequisiteClosure,
-    }), undefined);
 }
-function deliverAttempt(input, attempt) {
-    const decisionObservation = observeContractsForAdmission(input.scope, [input.contractId]);
+export function prepareReview(repository, stage) {
+    const tender = captureTender(repository, stage);
+    if (tender.kind === "refused")
+        return tender;
+    if (tender.data.changes.submodules.length > 0) {
+        return { kind: "refused", refusal: dirtyTenderRefusal(repository, stage.contractId, tender.data) };
+    }
+    const workspace = dirtyTenderDelta(repository, tender.data);
+    return prepareReviewIntegration(repository, stage, tender.data, workspace);
+}
+async function deliverAttempt(input, attempt) {
+    let decisionObservation = await observeContractsForAdmissionAt(input.scope, input.channel, [input.contractId]);
     const state = contractState(decisionObservation.decision, input.contractId);
+    if (state !== null) {
+        decisionObservation = await extendContractsForAdmissionAt(input.channel, decisionObservation, state.terms.after);
+    }
+    const derivation = state === null || input.deriveDocument === undefined
+        ? undefined
+        : input.deriveDocument(state);
     let preparation;
-    if (state === null || input.derivation === undefined) {
+    if (state === null || derivation === undefined) {
         preparation = { kind: "unavailable" };
     }
-    else if (input.derivation.verification.kind === "refused") {
+    else if (derivation.verification.kind === "refused") {
         preparation = {
             kind: "refused",
-            document: input.derivation.document,
-            refusal: input.derivation.verification.refusal,
+            document: derivation.document,
+            refusal: derivation.verification.refusal,
         };
     }
     else {
@@ -115,12 +204,14 @@ function deliverAttempt(input, attempt) {
             contractId: state.id,
             coordinates: state.coordinates,
         }, {
-            title: input.derivation.title,
+            title: derivation.title,
             ...(input.message === undefined ? {} : { message: input.message }),
+            requireBranchesToBeUpToDate: input.requireBranchesToBeUpToDate,
+            includeDirty: input.includeDirty,
         });
         preparation = prepared.kind === "refused"
-            ? { kind: "refused", document: input.derivation.document, refusal: prepared.refusal }
-            : { kind: "prepared", document: input.derivation.document, data: prepared.data };
+            ? { kind: "refused", document: derivation.document, refusal: prepared.refusal }
+            : { kind: "prepared", document: derivation.document, data: prepared.data };
     }
     const decisionInput = {
         contractId: input.contractId,
@@ -134,61 +225,64 @@ function deliverAttempt(input, attempt) {
     if (preparation.kind !== "prepared") {
         throw new Error("offered delivery is missing its mechanical preparation");
     }
-    const admitted = admitDecidedOffer(input.scope, decisionObservation, attempt, decision.offer, input.contractId);
+    const admitted = await admitDecidedOffer({
+        channel: input.channel,
+        repository: input.scope,
+        decisionObservation,
+        attempt,
+        offer: decision.offer,
+        primaryContract: input.contractId,
+    });
     if (admitted.kind === "accepted") {
-        return { ...admitted, value: {
-                snapshotId: preparation.data.candidate,
-                changeId: preparation.data.deliveryPatchId,
-                expectedPredecessor: preparation.data.expectedPredecessor,
-            } };
+        if (derivation === undefined)
+            throw new Error("accepted delivery is missing its document derivation");
+        return { ...admitted, value: { delivery: preparation.data, derivation } };
     }
     return admitted;
 }
 async function completeDelivery(input, first) {
-    if (input.derivation === undefined) {
-        throw new Error("accepted delivery is missing its document derivation");
-    }
-    const derivation = input.derivation;
+    const derivation = first.value.derivation;
     if (derivation.verification.kind !== "prepared") {
         throw new Error("accepted delivery is missing its Verification preparation");
     }
     let admission = first;
     let verificationValue;
+    let cleanup;
     let leak;
     const verification = await verifyDelivery({
+        channel: input.channel,
         repository: input.scope,
         contractId: input.contractId,
         ...(input.actor === undefined ? {} : { actor: input.actor }),
         at: timestamp(),
         state: first.state,
         environment: process.env,
-        produce: produceVerification,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
         ...(derivation.verification.data === null
             ? {}
             : { verification: derivation.verification.data }),
     });
     if (verification !== null) {
+        cleanup = verification.cleanup;
         leak = verification.leak;
-        if ("failure" in verification.step)
-            verificationValue = verification.step;
-        else {
-            verificationValue = stepStop(verification.step);
-            if (verification.step.kind === "accepted")
-                admission = mergeAdmissions(admission, verification.step);
+        verificationValue = verificationStop(verification.step);
+        if (!("failure" in verification.step) && verification.step.kind === "accepted") {
+            admission = mergeAdmissions(admission, verification.step);
         }
     }
-    const placement = admitPlacement(input.scope, {
+    const placement = await admitPlacement(input.channel, input.scope, first.state.coordinates.target, {
         contractId: input.contractId,
         ...(input.actor === undefined ? {} : { actor: input.actor }),
         at: timestamp(),
     });
-    const placementValue = stepStop(placement);
+    const placementValue = placementStop(placement);
     if (placement.kind === "accepted")
         admission = mergeAdmissions(admission, placement);
     return admitted(admission, {
-        ...first.value,
+        ...first.value.delivery,
         ...(verificationValue === undefined ? {} : { verification: verificationValue }),
         ...(placementValue === undefined ? {} : { placement: placementValue }),
+        ...(cleanup === undefined ? {} : { cleanup }),
         ...(leak === undefined ? {} : { leak }),
     });
 }
@@ -196,7 +290,7 @@ export async function deliverOperation(input) {
     const attempts = mintAttempts({ entryCount: 2 });
     let first = null;
     for (let index = 0; index < attempts.length; index += 1) {
-        const result = deliverAttempt(input, attempts[index]);
+        const result = await deliverAttempt(input, attempts[index]);
         if (result.kind === "accepted") {
             first = result;
             break;
@@ -214,16 +308,19 @@ export async function deliverOperation(input) {
         return { kind: "retry", reason: { kind: "exhausted" } };
     return completeDelivery(input, first);
 }
-export function abandonOperation(input) {
-    return complete(admitIntent(input.scope, {
+export async function abandonOperation(input) {
+    return complete(await admitIntent(input.channel, input.scope, {
         contractId: input.contractId,
         ...(input.actor === undefined ? {} : { actor: input.actor }),
         at: timestamp(),
         ...(input.note === undefined ? {} : { note: input.note }),
-    }, decideAbandon, input.decorateOffer === undefined ? {} : { decorateOffer: input.decorateOffer }), undefined);
+    }, decideAbandon, {
+        ...(input.decorateOffer === undefined ? {} : { decorateOffer: input.decorateOffer }),
+        ...(input.observationSelection === undefined ? {} : { observationSelection: input.observationSelection }),
+    }), undefined);
 }
-export function arcOperation(input) {
-    return complete(admitIntent(input.scope, {
+export async function arcOperation(input) {
+    return complete(await admitIntent(input.channel, input.scope, {
         contractId: input.contractId,
         ...(input.actor === undefined ? {} : { actor: input.actor }),
         at: timestamp(),
@@ -231,9 +328,13 @@ export function arcOperation(input) {
     }, decideArc), undefined);
 }
 function reviewAttempt(input, attempt) {
-    const decisionObservation = observeContractsForAdmission(input.scope, [input.contractId]);
+    return reviewAttemptObserved(input, attempt);
+}
+async function reviewAttemptObserved(input, attempt) {
+    const decisionObservation = await observeContractsForAdmissionAt(input.scope, input.channel, [input.contractId]);
     const state = contractState(decisionObservation.decision, input.contractId);
     let preparation;
+    let workspace;
     if (state !== null) {
         const prepared = prepareReview(input.scope, { contractId: state.id, coordinates: state.coordinates });
         preparation = prepared.kind === "refused"
@@ -244,12 +345,14 @@ function reviewAttempt(input, attempt) {
                     gate: REVIEWED,
                     subject: dependencyKeySet([
                         { kind: "document", value: state.terms.document.key },
-                        { kind: "change", value: prepared.data },
+                        { kind: "change", value: prepared.data.changeId },
                     ]),
                     verdict: input.verdict,
                     ...(input.summary === undefined ? {} : { summary: input.summary }),
                 },
             };
+        if (prepared.kind === "prepared")
+            workspace = prepared.data.workspace;
     }
     const decisionInput = {
         contractId: input.contractId,
@@ -260,17 +363,27 @@ function reviewAttempt(input, attempt) {
     const decision = decideAttestation({ input: decisionInput, attempt, observation: decisionObservation.decision });
     if (decision.kind === "refused")
         return { kind: "refused", refusal: decision.refusal };
-    const admitted = admitDecidedOffer(input.scope, decisionObservation, attempt, decision.offer, input.contractId);
+    const admitted = await admitDecidedOffer({
+        channel: input.channel,
+        repository: input.scope,
+        decisionObservation,
+        attempt,
+        offer: decision.offer,
+        primaryContract: input.contractId,
+    });
     if (admitted.kind === "accepted")
-        return { ...admitted, value: undefined };
+        return {
+            ...admitted,
+            value: workspace === undefined ? {} : { workspace },
+        };
     return admitted;
 }
-export function reviewOperation(input) {
+export async function reviewOperation(input) {
     const git = input.scope;
-    const attempts = mintAttempts({ entryCount: 2 });
+    const attempts = mintAttempts({ entryCount: 1 });
     let review = null;
     for (let index = 0; index < attempts.length; index += 1) {
-        const result = reviewAttempt(input, attempts[index]);
+        const result = await reviewAttempt(input, attempts[index]);
         if (result.kind === "accepted" || result.kind === "refused") {
             review = result;
             break;
@@ -285,26 +398,23 @@ export function reviewOperation(input) {
     if (review.kind !== "accepted")
         return review;
     if (input.verdict !== "satisfied")
-        return admitted(review, {});
-    const placement = admitPlacement(git, {
+        return admitted(review, review.value);
+    const placement = await admitPlacement(input.channel, git, review.state.coordinates.target, {
         contractId: input.contractId,
         ...(input.actor === undefined ? {} : { actor: input.actor }),
         at: timestamp(),
     });
-    const placementStop = stepStop(placement);
+    const stopped = placementStop(placement);
     const admission = placement.kind === "accepted" ? mergeAdmissions(review, placement) : review;
-    return admitted(admission, placementStop === undefined ? {} : { placement: placementStop });
+    return admitted(admission, { ...review.value, ...(stopped === undefined ? {} : { placement: stopped }) });
 }
 export async function auditOperation(input) {
     const git = input.scope;
-    const initial = readAudit(git, input.contractId, REVIEWED);
+    const initial = await readAuditAt(git, input.channel, input.contractId, REVIEWED);
     if (initial.state === null)
         return { kind: "refused", refusal: { kind: "contract-missing", contractId: input.contractId } };
-    const derivation = input.derivation;
-    if (derivation === undefined) {
-        return { kind: "refused", refusal: { kind: "document-moved", contractId: input.contractId } };
-    }
-    if (!documentIsCurrent(initial.state, derivation.document)) {
+    const derivation = input.deriveDocument?.(initial.state);
+    if (derivation === undefined || !documentIsCurrent(initial.state, derivation.document)) {
         return { kind: "refused", refusal: { kind: "document-moved", contractId: input.contractId } };
     }
     if (derivation.verification.kind === "refused") {
@@ -314,31 +424,27 @@ export async function auditOperation(input) {
         return accepted(initial.state, [], initial.report);
     }
     const verification = await verifyDelivery({
+        channel: input.channel,
         repository: git,
         contractId: input.contractId,
         ...(input.actor === undefined ? {} : { actor: input.actor }),
         at: timestamp(),
         state: initial.state,
         environment: process.env,
-        produce: produceVerification,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
         verification: derivation.verification.data,
     });
     if (verification === null) {
         throw new Error("audit verification preparation unexpectedly produced no attempt");
     }
-    const attempt = "failure" in verification.step
-        ? verification.step
-        : verification.step.kind === "accepted"
-            ? undefined
-            : verification.step.kind === "refused"
-                ? { refusal: verification.step.refusal }
-                : { retry: verification.step };
+    const attempt = verificationStop(verification.step);
     const report = !("failure" in verification.step) && verification.step.kind === "accepted"
-        ? auditReport(verification.step.journal, REVIEWED)
+        ? auditReport(verification.step.journal, REVIEWED, initial.state, initial.report.targetObservation)
         : initial.report;
     const value = {
         ...report,
         ...(attempt === undefined ? {} : { attempt }),
+        ...(verification.cleanup === undefined ? {} : { cleanup: verification.cleanup }),
         ...(verification.leak === undefined ? {} : { leak: verification.leak }),
     };
     return !("failure" in verification.step) && verification.step.kind === "accepted"
@@ -349,9 +455,11 @@ export async function reconcileOperation(input) {
     try {
         const observation = await reconcile({
             repository: input.scope,
+            channel: input.channel,
             contractId: input.contractId,
             hooks: input.hooks,
             retryHooks: input.retryHooks,
+            ...(input.retainTerminalWorktree === undefined ? {} : { retainTerminalWorktree: input.retainTerminalWorktree }),
         });
         return { state: observation.state, report: observation.result };
     }
@@ -363,8 +471,12 @@ export async function reconcileOperation(input) {
 }
 export async function reconcileAllOperation(input) {
     const git = input.scope;
-    const observation = observeGit(git);
-    const contracts = (await reconcileBatch(git, observation.contracts.keys(), input.hooks, input.retryHooks)).map((item) => ({
+    const observation = await withGitReadObservation(input.scope, input.channel, (read) => observeContractWorld(read));
+    const contracts = (await reconcileBatch(git, input.channel, observation.contracts.keys(), {
+        hooks: input.hooks,
+        retryHooks: input.retryHooks,
+        retainTerminalWorktree: input.retainTerminalWorktree ?? false,
+    })).map((item) => ({
         contractId: item.contract,
         state: item.state,
         report: item.result,

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

@@ -1,11 +1,16 @@
 import type { ContractHead, ContractState, JournalEntry } from "../core/facts/types.js";
 import type { AcceptedAdmission } from "./attempt.js";
 import type { ProtocolResult, ProtocolTerminal } from "./run.js";
+import type { ReconcileResult } from "../git/reconcile.js";
+export type AcceptedProtocolStep = AcceptedAdmission & Readonly<{
+    physical?: ReconcileResult;
+}>;
 export type IntentOutcome<Value, Refusal = never> = Readonly<{
     kind: "accepted";
     facts: readonly JournalEntry[];
     head: ContractHead;
     value: Value;
+    physical?: ReconcileResult;
 }> | Readonly<{
     kind: "refused";
     refusal: Refusal;
@@ -13,6 +18,6 @@ export type IntentOutcome<Value, Refusal = never> = Readonly<{
     kind: "retry";
     reason: ProtocolTerminal;
 }>;
-export declare function accepted<Value, Refusal = never>(state: ContractState, facts: readonly JournalEntry[], value: Value): IntentOutcome<Value, Refusal>;
-export declare function admitted<Value, Refusal = never>(admission: AcceptedAdmission, value: Value): IntentOutcome<Value, Refusal>;
+export declare function accepted<Value, Refusal = never>(state: ContractState, facts: readonly JournalEntry[], value: Value, physical?: ReconcileResult): IntentOutcome<Value, Refusal>;
+export declare function admitted<Value, Refusal = never>(admission: AcceptedProtocolStep, value: Value): IntentOutcome<Value, Refusal>;
 export declare function complete<Value, Refusal>(result: ProtocolResult<Refusal>, value: Value): IntentOutcome<Value, Refusal>;

package/build/src/protocol/outcome.js

@@ -1,10 +1,16 @@
-export function accepted(state, facts, value) {
+export function accepted(state, facts, value, physical) {
     if (state.head === null)
         throw new Error("accepted contract is missing its journal head");
-    return { kind: "accepted", facts, head: state.head, value };
+    return {
+        kind: "accepted",
+        facts,
+        head: state.head,
+        value,
+        ...(physical === undefined ? {} : { physical }),
+    };
 }
 export function admitted(admission, value) {
-    return accepted(admission.state, admission.facts, value);
+    return accepted(admission.state, admission.facts, value, admission.physical);
 }
 export function complete(result, value) {
     if (result.kind === "refused")

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

@@ -0,0 +1,30 @@
+import type { ActorId, ContractId, SnapshotId } from "../core/facts/types.js";
+import { type PlacementRefusal } from "../core/verbs/placement.js";
+import type { GitDecodeChannel } from "../git/read-observation.js";
+import { type ReconcileResult } from "../git/reconcile.js";
+import { type GitRepository } from "../git/repository.js";
+import { type TargetPlacementRefusal } from "../git/target-placement.js";
+import { type AcceptedAdmission } from "./attempt.js";
+import { type ProtocolResult } from "./run.js";
+export type PlacementExecutionFailure = Readonly<{
+    kind: "placement-failed";
+    diagnostic: string;
+}>;
+export type TargetMovedStop = Readonly<{
+    kind: "target-moved";
+    contractId: ContractId;
+    target: string;
+    expected: SnapshotId;
+    observed: SnapshotId | null;
+}>;
+export type PlacementProtocolResult = (AcceptedAdmission & Readonly<{
+    physical?: ReconcileResult;
+}>) | Exclude<ProtocolResult<PlacementRefusal | TargetPlacementRefusal>, AcceptedAdmission> | TargetMovedStop | PlacementExecutionFailure;
+type PlacementProtocolInput = Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+}>;
+/** Run the sole placement adjudicator inside the target's physical fence. */
+export declare function admitPlacement(channel: GitDecodeChannel, repository: GitRepository, target: string | undefined, input: PlacementProtocolInput): Promise<PlacementProtocolResult>;
+export {};