@abot-ai/runtime 1.0.0 → 1.2.0

package/dist/src/runtime/orchestration/role-calls/work-result-receipt.js

@@ -0,0 +1,187 @@
+import { exactKeys, isRecord } from "../../validation/strict-record.js";
+import { ROLE_CALL_RESULT_MAX_LENGTH, SUPERVISOR_WORKER_V1_AUTHORITY_SNAPSHOT, } from "./contracts.js";
+import { createCanonicalRoleCallWorkResultLineage, projectRoleCallWorkResultLineage, } from "./work-result-lineage.js";
+export const ROLE_CALL_WORK_RESULT_RECEIPT_KIND = "work_result_v1";
+export const ROLE_CALL_WORK_RESULT_FINGERPRINT_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+const ROLE_CALL_WORK_RESULT_REFERENCE_MAX_LENGTH = 256;
+export function normalizeRoleCallWorkResultReceipt(input) {
+    if (input === undefined)
+        return undefined;
+    if (!isRecord(input))
+        return null;
+    if (!hasExactWorkResultReceiptKeys(input))
+        return null;
+    if (input.kind !== ROLE_CALL_WORK_RESULT_RECEIPT_KIND)
+        return null;
+    if (!isBoundedReference(input.producerCallId))
+        return null;
+    if (!isBoundedReference(input.callerCallId))
+        return null;
+    if (!isNonNegativeSafeInteger(input.sourceRevision))
+        return null;
+    if (!isLineageFingerprint(input.lineageFingerprint))
+        return null;
+    const plannerPlanRef = normalizePlannerPlanReference(input.plannerPlanRef);
+    if (plannerPlanRef === null)
+        return null;
+    const receipt = {
+        kind: ROLE_CALL_WORK_RESULT_RECEIPT_KIND,
+        producerCallId: input.producerCallId.trim(),
+        callerCallId: input.callerCallId.trim(),
+        sourceRevision: input.sourceRevision,
+        lineageFingerprint: input.lineageFingerprint,
+        ...(plannerPlanRef ? { plannerPlanRef } : {}),
+    };
+    if (JSON.stringify(receipt).length > ROLE_CALL_RESULT_MAX_LENGTH)
+        return null;
+    return deepFreeze(receipt);
+}
+export function mustIssueSupervisorWorkResultReceipt(input) {
+    if (input.child.roleId !== "planner" && input.child.roleId !== "worker") {
+        return false;
+    }
+    const expected = SUPERVISOR_WORKER_V1_AUTHORITY_SNAPSHOT;
+    return (input.policy.authority.id === expected.id &&
+        input.policy.authority.version === expected.version &&
+        input.policy.authority.definitionHash === expected.definitionHash);
+}
+export function createCanonicalRoleCallWorkResultReceipt(input) {
+    if (!mustIssueSupervisorWorkResultReceipt(input))
+        return null;
+    if (!hasCanonicalReturnBinding(input))
+        return null;
+    const sourceRevision = input.admittedHeadRevision;
+    if (sourceRevision === undefined)
+        return null;
+    const lineage = createCanonicalRoleCallWorkResultLineage({
+        state: input.state,
+        producer: input.child,
+        resultRef: input.resultRef,
+        outcome: input.outcome,
+        sourceRevision,
+    });
+    if (!lineage)
+        return null;
+    const receipt = normalizeRoleCallWorkResultReceipt({
+        kind: ROLE_CALL_WORK_RESULT_RECEIPT_KIND,
+        producerCallId: input.child.callId,
+        callerCallId: input.caller.callId,
+        sourceRevision,
+        lineageFingerprint: lineage.lineageFingerprint,
+        ...(lineage.planner
+            ? {
+                plannerPlanRef: {
+                    planId: lineage.planner.planId,
+                    planVersion: lineage.planner.planVersion,
+                },
+            }
+            : {}),
+    });
+    return receipt ?? null;
+}
+export function isRoleCallWorkResultReceiptValidForStoredResult(input) {
+    const receipt = normalizeRoleCallWorkResultReceipt(input.receipt);
+    if (!receipt)
+        return false;
+    if (!mustIssueSupervisorWorkResultReceipt({
+        child: input.producer,
+        policy: input.policy,
+    })) {
+        return false;
+    }
+    if (!isStoredResultBoundToReceipt(input, receipt))
+        return false;
+    return projectRoleCallWorkResultLineage({
+        state: input.state,
+        receipt,
+    }) !== null;
+}
+function hasExactWorkResultReceiptKeys(input) {
+    return exactKeys(input, [
+        "kind",
+        "producerCallId",
+        "callerCallId",
+        "sourceRevision",
+        "lineageFingerprint",
+    ], ["plannerPlanRef"]);
+}
+function normalizePlannerPlanReference(input) {
+    if (input === undefined)
+        return undefined;
+    if (!isRecord(input))
+        return null;
+    if (!exactKeys(input, ["planId", "planVersion"]))
+        return null;
+    if (!isBoundedReference(input.planId))
+        return null;
+    if (!isPositiveSafeInteger(input.planVersion))
+        return null;
+    return Object.freeze({
+        planId: input.planId.trim(),
+        planVersion: input.planVersion,
+    });
+}
+function hasCanonicalReturnBinding(input) {
+    if (!isNonNegativeSafeInteger(input.admittedHeadRevision))
+        return false;
+    if (!isBoundedReference(input.resultRef))
+        return false;
+    if (input.state.phase !== "running")
+        return false;
+    if (input.state.activeCallId !== input.child.callId)
+        return false;
+    const canonicalCaller = input.state.calls.find(({ callId }) => callId === input.caller.callId);
+    const canonicalChild = input.state.calls.find(({ callId }) => callId === input.child.callId);
+    if (canonicalCaller !== input.caller || canonicalChild !== input.child) {
+        return false;
+    }
+    if (input.caller.status !== "waiting_for_child")
+        return false;
+    if (input.child.status !== "active" || input.child.resultRef !== null) {
+        return false;
+    }
+    if (input.child.parentCallId !== input.caller.callId)
+        return false;
+    if (!input.caller.childCallIds.includes(input.child.callId))
+        return false;
+    return input.outcome === "completed" || input.outcome === "failed";
+}
+function isStoredResultBoundToReceipt(input, receipt) {
+    if (input.producer.callId !== receipt.producerCallId)
+        return false;
+    if (input.producer.parentCallId !== receipt.callerCallId)
+        return false;
+    if (input.producer.status !== "completed")
+        return false;
+    if (input.producer.resultRef !== input.result.resultRef)
+        return false;
+    if (input.result.producerCallId !== input.producer.callId)
+        return false;
+    if (input.result.roleId !== input.producer.roleId)
+        return false;
+    return input.state.results.includes(input.result);
+}
+function isBoundedReference(input) {
+    return (typeof input === "string" &&
+        input.trim().length > 0 &&
+        input.length <= ROLE_CALL_WORK_RESULT_REFERENCE_MAX_LENGTH);
+}
+function isNonNegativeSafeInteger(input) {
+    return Number.isSafeInteger(input) && input >= 0;
+}
+function isPositiveSafeInteger(input) {
+    return Number.isSafeInteger(input) && input >= 1;
+}
+function isLineageFingerprint(input) {
+    return (typeof input === "string" &&
+        ROLE_CALL_WORK_RESULT_FINGERPRINT_PATTERN.test(input));
+}
+function deepFreeze(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value)) {
+        return value;
+    }
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return value;
+}

package/dist/src/runtime/orchestration/role-executors/activation/capability-continuation.d.ts

@@ -0,0 +1,15 @@
+import type { RoleCallFrame, RoleCallLedger, RoleCallLedgerHead } from "../../role-calls/index.js";
+import type { RoleExecutionContinuation, RoleExecutionContinuationReference } from "../contracts.js";
+import type { RoleExecutorDiagnosticContext } from "../shared/diagnostic-context.js";
+export type RoleCapabilityContinuationResolution = Readonly<{
+    call: RoleCallFrame;
+    continuationReference?: RoleExecutionContinuationReference;
+}>;
+export declare function continueRoleThroughCapability(params: Readonly<{
+    ledger: RoleCallLedger;
+    before: RoleCallLedgerHead;
+    currentCall: RoleCallFrame;
+    diagnostic: RoleExecutorDiagnosticContext;
+    continuation: RoleExecutionContinuation["continuation"];
+    turnCount: number;
+}>): RoleCapabilityContinuationResolution;

package/dist/src/runtime/orchestration/role-executors/activation/capability-continuation.js

@@ -0,0 +1,73 @@
+import { traceRoleExecutorContinued, traceRoleExecutorContinuationRejected, } from "../diagnostics.js";
+import { continuationError, readLedgerOrReject, } from "../shared/runtime-invariants.js";
+import { validateCapabilityContinuation, validateOperationSupervisionInterventionContinuation, } from "./state-validation.js";
+export function continueRoleThroughCapability(params) {
+    const after = readLedgerOrReject({
+        ledger: params.ledger,
+        diagnostic: params.diagnostic,
+        turnCount: params.turnCount,
+    });
+    if (params.continuation.kind === "operation_supervision_intervention") {
+        return continueAfterOperationSupervisionIntervention({ ...params, continuation: params.continuation }, after);
+    }
+    return continueAfterCapabilityExecution({ ...params, continuation: params.continuation }, after);
+}
+function continueAfterCapabilityExecution(params, after) {
+    const executionIds = params.continuation.kind === "capability_batch_execution"
+        ? params.continuation.executionIds
+        : [params.continuation.executionId];
+    const continuation = validateCapabilityContinuation({
+        before: params.before,
+        after,
+        currentCall: params.currentCall,
+        executionIds,
+    });
+    const diagnosticIds = params.continuation.kind === "capability_batch_execution"
+        ? { executionIds }
+        : { executionId: executionIds[0] };
+    if (!continuation.ok) {
+        traceRoleExecutorContinuationRejected(params.diagnostic, {
+            continuationKind: params.continuation.kind,
+            issueCode: continuation.issueCode,
+            ...diagnosticIds,
+            fromActivation: params.currentCall.activationCount,
+            turnCount: params.turnCount,
+        });
+        throw continuationError(params.currentCall.roleId, continuation.issueCode);
+    }
+    traceRoleExecutorContinued(params.diagnostic, {
+        continuationKind: params.continuation.kind,
+        ...diagnosticIds,
+        fromActivation: params.currentCall.activationCount,
+        toActivation: continuation.call.activationCount,
+        turnCount: params.turnCount,
+    });
+    return Object.freeze({
+        call: continuation.call,
+        continuationReference: params.continuation,
+    });
+}
+function continueAfterOperationSupervisionIntervention(params, after) {
+    const continuation = validateOperationSupervisionInterventionContinuation({
+        before: params.before,
+        after,
+        currentCall: params.currentCall,
+        commit: params.continuation.commit,
+    });
+    if (!continuation.ok) {
+        traceRoleExecutorContinuationRejected(params.diagnostic, {
+            continuationKind: params.continuation.kind,
+            issueCode: continuation.issueCode,
+            fromActivation: params.currentCall.activationCount,
+            turnCount: params.turnCount,
+        });
+        throw continuationError(params.currentCall.roleId, continuation.issueCode);
+    }
+    traceRoleExecutorContinued(params.diagnostic, {
+        continuationKind: params.continuation.kind,
+        fromActivation: params.currentCall.activationCount,
+        toActivation: continuation.call.activationCount,
+        turnCount: params.turnCount,
+    });
+    return Object.freeze({ call: continuation.call });
+}

package/dist/src/runtime/orchestration/role-executors/activation/loop.d.ts

@@ -16,6 +16,5 @@ export declare class RoleActivationLoop<TContext, TValue> {
     private runActivation;
     private completeTerminal;
     private continueThroughChild;
-    private continueThroughCapability;
 }
 export {};

package/dist/src/runtime/orchestration/role-executors/activation/loop.js

@@ -1,10 +1,11 @@
 import { isRuntimeDelegateRoleId } from "../../roles.js";
-import { traceRoleExecutorCompleted, traceRoleExecutorContinued, traceRoleExecutorContinuationRejected, traceRoleExecutorFailed, traceRoleExecutorInitialStateRejected, traceRoleExecutorResolved, traceRoleExecutorResultRejected, traceRoleExecutorStarted, traceRoleExecutorStateRejected, traceRoleExecutorUnavailable, } from "../diagnostics.js";
+import { traceRoleExecutorCompleted, traceRoleExecutorFailed, traceRoleExecutorInitialStateRejected, traceRoleExecutorResolved, traceRoleExecutorResultRejected, traceRoleExecutorStarted, traceRoleExecutorStateRejected, traceRoleExecutorUnavailable, } from "../diagnostics.js";
 import { requireResumedCallerCall } from "../child-invocation/state-validation.js";
 import { createAttemptDiagnostic, createDiagnostic, } from "../shared/diagnostic-context.js";
-import { continuationError, readLedgerOrReject, stateError, } from "../shared/runtime-invariants.js";
+import { readLedgerOrReject, stateError, } from "../shared/runtime-invariants.js";
+import { continueRoleThroughCapability } from "./capability-continuation.js";
 import { normalizeRoleExecutorActivationResult } from "./result-normalization.js";
-import { resolveCurrentCall, validateCapabilityContinuation, } from "./state-validation.js";
+import { resolveCurrentCall } from "./state-validation.js";
 export class RoleActivationLoop {
     params;
     expectedCall;
@@ -14,24 +15,14 @@ export class RoleActivationLoop {
         this.expectedCall = params.input.call;
     }
     async run() {
-        const { executor, initialHead, call } = this.resolveInitialActivation();
+        const { executor, call } = this.resolveInitialActivation();
         this.expectedCall = call;
-        const maximumTurns = initialHead.policy.limits.maxCalls +
-            initialHead.policy.limits.maxCapabilityExecutions +
-            1;
-        for (let turnCount = 1; turnCount <= maximumTurns; turnCount += 1) {
+        for (let turnCount = 1;; turnCount += 1) {
             const activation = this.requireCurrentActivation(turnCount);
             const terminal = await this.runActivation(executor, activation, turnCount);
             if (terminal)
                 return terminal;
         }
-        const exhaustedDiagnostic = createDiagnostic({
-            requestId: this.params.input.requestId,
-            call: this.expectedCall,
-            registeredRoleIds: this.params.registeredRoleIds,
-        });
-        traceRoleExecutorStateRejected(exhaustedDiagnostic, "continuation_limit_exceeded", maximumTurns);
-        throw stateError("continuation_limit_exceeded");
     }
     resolveInitialActivation() {
         const { input, registeredRoleIds, executorByRoleId } = this.params;
@@ -78,7 +69,6 @@ export class RoleActivationLoop {
         traceRoleExecutorResolved(initialDiagnostic);
         return Object.freeze({
             executor,
-            initialHead,
             call: initialAuthority.call,
         });
     }
@@ -148,7 +138,16 @@ export class RoleActivationLoop {
                 await this.continueThroughChild(activation, result.value, turnCount);
                 return undefined;
             }
-            this.continueThroughCapability(activation, result.value, turnCount);
+            const continued = continueRoleThroughCapability({
+                ledger: input.ledger,
+                before: activation.before,
+                currentCall: activation.call,
+                diagnostic: activation.diagnostic,
+                continuation: result.value.continuation,
+                turnCount,
+            });
+            this.expectedCall = continued.call;
+            this.continuationReference = continued.continuationReference;
             return undefined;
         }
         catch (error) {
@@ -202,43 +201,6 @@ export class RoleActivationLoop {
         this.expectedCall = requireResumedCallerCall(child.returnCommit, activation.call);
         this.continuationReference = continuationReference;
     }
-    continueThroughCapability(activation, result, turnCount) {
-        const after = readLedgerOrReject({
-            ledger: this.params.input.ledger,
-            diagnostic: activation.diagnostic,
-            turnCount,
-        });
-        const executionIds = result.continuation.kind === "capability_batch_execution"
-            ? result.continuation.executionIds
-            : [result.continuation.executionId];
-        const continuation = validateCapabilityContinuation({
-            before: activation.before,
-            after,
-            currentCall: activation.call,
-            executionIds,
-        });
-        if (!continuation.ok) {
-            traceRoleExecutorContinuationRejected(activation.diagnostic, {
-                issueCode: continuation.issueCode,
-                ...(result.continuation.kind === "capability_batch_execution"
-                    ? { executionIds }
-                    : { executionId: executionIds[0] }),
-                fromActivation: activation.call.activationCount,
-                turnCount,
-            });
-            throw continuationError(activation.call.roleId, continuation.issueCode);
-        }
-        traceRoleExecutorContinued(activation.diagnostic, {
-            ...(result.continuation.kind === "capability_batch_execution"
-                ? { executionIds }
-                : { executionId: executionIds[0] }),
-            fromActivation: activation.call.activationCount,
-            toActivation: continuation.call.activationCount,
-            turnCount,
-        });
-        this.expectedCall = continuation.call;
-        this.continuationReference = result.continuation;
-    }
 }
 function isTerminalStateFresh(after, before) {
     return after === before;

package/dist/src/runtime/orchestration/role-executors/activation/result-normalization.js

@@ -1,12 +1,14 @@
-import { isRoleCallWorkingDirectoryRoleId, normalizeRoleCallWorkingDirectory, parseRoleCallPlanBinding, parseRoleCallWorkerCapabilityScope, } from "../../role-calls/index.js";
+import { isRoleCallWorkingDirectoryRoleId, normalizeRoleCallWorkingDirectory, normalizeRoleCallResultReceipt, parseRoleCallPlanBinding, parseRoleCallWorkerCapabilityScope, } from "../../role-calls/index.js";
 import { isRuntimeDelegateRoleId } from "../../roles.js";
 export function normalizeRoleExecutorActivationResult(input, maxSummaryLength, maxObjectiveLength) {
     if (!isPlainRecord(input)) {
         return { ok: false, issueCode: "result_not_object" };
     }
     if (input.kind === "terminal") {
-        if (!hasExactKeys(input, ["kind", "outcome", "summary"], ["value"]) ||
-            (input.outcome !== "completed" && input.outcome !== "failed")) {
+        const receipt = normalizeRoleCallResultReceipt(input.receipt);
+        if (!hasExactKeys(input, ["kind", "outcome", "summary"], ["receipt", "value"]) ||
+            (input.outcome !== "completed" && input.outcome !== "failed") ||
+            receipt === null) {
             return { ok: false, issueCode: "terminal_shape_invalid" };
         }
         if (typeof input.summary !== "string" ||
@@ -20,6 +22,7 @@ export function normalizeRoleExecutorActivationResult(input, maxSummaryLength, m
                 kind: "terminal",
                 outcome: input.outcome,
                 summary: input.summary.trim(),
+                ...(receipt ? { receipt } : {}),
                 ...(input.value !== undefined ? { value: input.value } : {}),
             }),
         };
@@ -62,6 +65,20 @@ export function normalizeRoleExecutorActivationResult(input, maxSummaryLength, m
         !isPlainRecord(input.continuation)) {
         return { ok: false, issueCode: "continuation_shape_invalid" };
     }
+    if (hasExactKeys(input.continuation, ["kind", "commit"]) &&
+        input.continuation.kind === "operation_supervision_intervention" &&
+        isPlainRecord(input.continuation.commit)) {
+        return {
+            ok: true,
+            value: Object.freeze({
+                kind: "continue",
+                continuation: Object.freeze({
+                    kind: "operation_supervision_intervention",
+                    commit: input.continuation.commit,
+                }),
+            }),
+        };
+    }
     if (hasExactKeys(input.continuation, ["kind", "executionId"]) &&
         input.continuation.kind === "capability_execution" &&
         isCapabilityExecutionId(input.continuation.executionId)) {

package/dist/src/runtime/orchestration/role-executors/activation/state-validation.d.ts

@@ -1,4 +1,4 @@
-import type { RoleCallFrame, RoleCallLedgerHead } from "../../role-calls/index.js";
+import type { RoleCallFrame, RoleCallLedgerHead, RoleCallOperationSupervisionInterventionCommit } from "../../role-calls/index.js";
 export declare function resolveCurrentCall(params: Readonly<{
     head: RoleCallLedgerHead;
     requestId: string;
@@ -22,3 +22,15 @@ export declare function validateCapabilityContinuation(params: Readonly<{
     ok: false;
     issueCode: string;
 }>;
+export declare function validateOperationSupervisionInterventionContinuation(params: Readonly<{
+    before: RoleCallLedgerHead;
+    after: RoleCallLedgerHead;
+    currentCall: RoleCallFrame;
+    commit: RoleCallOperationSupervisionInterventionCommit;
+}>): Readonly<{
+    ok: true;
+    call: RoleCallFrame;
+}> | Readonly<{
+    ok: false;
+    issueCode: string;
+}>;

package/dist/src/runtime/orchestration/role-executors/activation/state-validation.js

@@ -1,3 +1,4 @@
+import { isSameRoleOperationIdentity } from "../../role-calls/index.js";
 import { isRuntimeDelegateRoleId } from "../../roles.js";
 import { sameCallFrame, sameCallIdentity, } from "../shared/runtime-invariants.js";
 export function resolveCurrentCall(params) {
@@ -46,7 +47,9 @@ export function validateCapabilityContinuation(params) {
             afterState.capabilityExecutionSequence !==
                 beforeState.capabilityExecutionSequence + params.executionIds.length ||
             afterState.activeCallId !== params.currentCall.callId ||
-            afterState.results !== beforeState.results) {
+            afterState.results !== beforeState.results ||
+            afterState.capabilitySelectionSupervision.epoch !== null ||
+            afterState.capabilitySelectionSupervision.records.length !== 0) {
             return { ok: false, issueCode: "ledger_progress_invalid" };
         }
         if (afterState.calls.length !== beforeState.calls.length) {
@@ -105,6 +108,139 @@ export function validateCapabilityContinuation(params) {
         return { ok: false, issueCode: "continuation_state_invalid" };
     }
 }
+export function validateOperationSupervisionInterventionContinuation(params) {
+    try {
+        const commitIssue = validateOperationSupervisionInterventionCommit(params);
+        if (commitIssue)
+            return { ok: false, issueCode: commitIssue };
+        const progressIssue = validateOperationSupervisionInterventionProgress(params);
+        if (progressIssue)
+            return { ok: false, issueCode: progressIssue };
+        const nextCall = params.after.state.calls.find((candidate) => candidate.callId === params.currentCall.callId);
+        if (!nextCall)
+            return { ok: false, issueCode: "call_unavailable" };
+        const callIssue = validateIntervenedCall({
+            before: params.before,
+            after: params.after,
+            currentCall: params.currentCall,
+            nextCall,
+        });
+        if (callIssue)
+            return { ok: false, issueCode: callIssue };
+        const supervisionIssue = validateOperationSupervisionTransition(params);
+        if (supervisionIssue) {
+            return { ok: false, issueCode: supervisionIssue };
+        }
+        return { ok: true, call: nextCall };
+    }
+    catch {
+        return { ok: false, issueCode: "continuation_state_invalid" };
+    }
+}
+function validateOperationSupervisionInterventionCommit(params) {
+    const { commit } = params;
+    if (commit.previousHead !== params.before || commit.head !== params.after) {
+        return "continuation_commit_mismatch";
+    }
+    if (commit.effect.type !== "operation_supervision_intervened") {
+        return "continuation_effect_invalid";
+    }
+    if (commit.effect.callId !== params.currentCall.callId ||
+        commit.effect.invocationAttempt !== params.currentCall.activationCount ||
+        commit.effect.matchingOutcomeCount !== 2 ||
+        commit.effect.interventionCount !== 1) {
+        return "continuation_effect_mismatch";
+    }
+    return undefined;
+}
+function validateOperationSupervisionInterventionProgress(params) {
+    if (params.after === params.before)
+        return "ledger_not_advanced";
+    if (params.after.revision !== params.before.revision + 1) {
+        return "revision_advance_invalid";
+    }
+    if (params.after.kind !== params.before.kind)
+        return "ledger_kind_changed";
+    if (params.after.policy !== params.before.policy)
+        return "policy_changed";
+    const beforeState = params.before.state;
+    const afterState = params.after.state;
+    const unrelatedStateChanged = afterState.contractVersion !== beforeState.contractVersion ||
+        afterState.requestId !== beforeState.requestId ||
+        afterState.phase !== beforeState.phase ||
+        afterState.phase !== "running" ||
+        afterState.rootCallId !== beforeState.rootCallId ||
+        afterState.rootResponse !== beforeState.rootResponse ||
+        afterState.callSequence !== beforeState.callSequence ||
+        afterState.resultSequence !== beforeState.resultSequence ||
+        afterState.capabilityExecutionSequence !==
+            beforeState.capabilityExecutionSequence ||
+        afterState.activeCallId !== params.currentCall.callId ||
+        afterState.results !== beforeState.results ||
+        afterState.plans !== beforeState.plans ||
+        afterState.capabilityExecutions !== beforeState.capabilityExecutions ||
+        afterState.capabilitySelectionSupervision.epoch !== null ||
+        afterState.capabilitySelectionSupervision.records.length !== 0;
+    return unrelatedStateChanged ? "ledger_progress_invalid" : undefined;
+}
+function validateIntervenedCall(params) {
+    if (params.after.state.calls.length !== params.before.state.calls.length) {
+        return "call_set_changed";
+    }
+    const callDidNotAdvanceExactlyOnce = params.nextCall.status !== "active" ||
+        params.nextCall.activationCount !==
+            params.currentCall.activationCount + 1 ||
+        params.nextCall.lastCapabilitySelectionReconsideration !==
+            params.currentCall.lastCapabilitySelectionReconsideration ||
+        !sameCallIdentity(params.nextCall, params.currentCall);
+    if (callDidNotAdvanceExactlyOnce)
+        return "activation_advance_invalid";
+    const unrelatedCallChanged = params.before.state.calls.some((beforeCall) => beforeCall.callId !== params.currentCall.callId &&
+        params.after.state.calls.find((candidate) => candidate.callId === beforeCall.callId) !== beforeCall);
+    return unrelatedCallChanged ? "unrelated_call_changed" : undefined;
+}
+function validateOperationSupervisionTransition(params) {
+    const beforeSupervision = params.before.state.operationSupervision;
+    const afterSupervision = params.after.state.operationSupervision;
+    const effect = params.commit.effect;
+    const entryIndex = beforeSupervision.entries.findIndex((entry) => isSameRoleOperationIdentity(entry, effect));
+    const beforeEntry = beforeSupervision.entries[entryIndex];
+    const afterEntry = afterSupervision.entries[entryIndex];
+    const unrelatedEntryChanged = beforeSupervision.entries.some((entry, index) => index !== entryIndex && afterSupervision.entries[index] !== entry);
+    const interventionRecord = afterSupervision.interventions[afterSupervision.interventions.length - 1];
+    const interventionHistoryChangedAppendOnly = afterSupervision.interventions.length ===
+        beforeSupervision.interventions.length + 1 &&
+        beforeSupervision.interventions.every((intervention, index) => afterSupervision.interventions[index] === intervention);
+    const transitionDoesNotMatchEffect = afterSupervision === beforeSupervision ||
+        entryIndex < 0 ||
+        afterSupervision.entries.length !== beforeSupervision.entries.length ||
+        unrelatedEntryChanged ||
+        beforeEntry?.stage !== "warning" ||
+        !hasMatchingOperationSupervisionEvidence(beforeEntry, effect) ||
+        afterEntry === beforeEntry ||
+        afterEntry?.stage !== "intervened" ||
+        !hasMatchingOperationSupervisionEvidence(afterEntry, effect) ||
+        !hasMatchingOperationSupervisionIntervention(afterEntry, effect) ||
+        !interventionHistoryChangedAppendOnly ||
+        !interventionRecord ||
+        !hasMatchingOperationSupervisionEvidence(interventionRecord, effect) ||
+        !hasMatchingOperationSupervisionIntervention(interventionRecord, effect);
+    return transitionDoesNotMatchEffect
+        ? "operation_supervision_state_invalid"
+        : undefined;
+}
+function hasMatchingOperationSupervisionEvidence(evidence, effect) {
+    return (isSameRoleOperationIdentity(evidence, effect) &&
+        evidence.priorOutcome === effect.priorOutcome &&
+        evidence.outcomeFingerprint === effect.outcomeFingerprint &&
+        evidence.originExecutionId === effect.originExecutionId &&
+        evidence.matchingOutcomeCount === effect.matchingOutcomeCount);
+}
+function hasMatchingOperationSupervisionIntervention(intervention, effect) {
+    return (intervention.interventionCount === effect.interventionCount &&
+        intervention.interventionCallId === effect.callId &&
+        intervention.interventionInvocationAttempt === effect.invocationAttempt);
+}
 function validateSettledExecution(params) {
     const execution = params.execution;
     if (!execution)

package/dist/src/runtime/orchestration/role-executors/child-invocation/transaction.js

@@ -169,6 +169,7 @@ export class ChildInvocationTransaction {
             childCallId: openedChild.call.callId,
             outcome: execution.outcome,
             summary: execution.summary,
+            ...(execution.receipt ? { receipt: execution.receipt } : {}),
         });
         if (!returnedResult.ok) {
             this.rejectChild({

package/dist/src/runtime/orchestration/role-executors/contracts.d.ts

@@ -1,10 +1,11 @@
-import type { RoleCallChildReturnCommit, RoleCallFrame, RoleCallLedger, RoleCallLedgerHead, RoleCallPlanBinding, RoleCallWorkerCapabilityScope } from "../role-calls/index.js";
+import type { RoleCallChildReturnCommit, RoleCallFrame, RoleCallLedger, RoleCallLedgerHead, RoleCallOperationSupervisionInterventionCommit, RoleCallPlanBinding, RoleCallResultReceipt, RoleCallWorkerCapabilityScope } from "../role-calls/index.js";
 import type { RuntimeDelegateRoleId } from "../roles.js";
 export type RoleExecutionOutcome = "completed" | "failed";
 export type RoleExecutionResult<TValue = unknown> = Readonly<{
     kind: "terminal";
     outcome: RoleExecutionOutcome;
     summary: string;
+    receipt?: RoleCallResultReceipt;
     value?: TValue;
 }>;
 export type RoleChildInvocationResult<TValue = unknown> = Readonly<{
@@ -19,14 +20,18 @@ export type RoleCapabilityBatchExecutionContinuationReference = Readonly<{
     kind: "capability_batch_execution";
     executionIds: readonly string[];
 }>;
+export type RoleOperationSupervisionInterventionContinuation = Readonly<{
+    kind: "operation_supervision_intervention";
+    commit: RoleCallOperationSupervisionInterventionCommit;
+}>;
 export type RoleChildContinuationReference = Readonly<{
     kind: "role_child";
     commit: RoleCallChildReturnCommit;
 }>;
-export type RoleExecutionContinuationReference = RoleCapabilityExecutionContinuationReference | RoleCapabilityBatchExecutionContinuationReference | RoleChildContinuationReference;
+export type RoleExecutionContinuationReference = RoleCapabilityExecutionContinuationReference | RoleCapabilityBatchExecutionContinuationReference | RoleOperationSupervisionInterventionContinuation | RoleChildContinuationReference;
 export type RoleExecutionContinuation = Readonly<{
     kind: "continue";
-    continuation: RoleCapabilityExecutionContinuationReference | RoleCapabilityBatchExecutionContinuationReference;
+    continuation: RoleCapabilityExecutionContinuationReference | RoleCapabilityBatchExecutionContinuationReference | RoleOperationSupervisionInterventionContinuation;
 }>;
 export type RoleExecutionChildInvocation = Readonly<{
     kind: "invoke_role";