@abot-ai/runtime 1.0.0 → 1.2.0

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

@@ -1,8 +1,12 @@
 import type { CanonicalStateHead, CanonicalStateHeadTransactionFailureCode } from "../state-head.js";
 import type { CapabilityAdapterResult } from "../capability-adapters/result.js";
 import type { RuntimeDelegateRoleId, RuntimeRoleId } from "../roles.js";
-export declare const ROLE_CALL_LEDGER_CONTRACT_VERSION = 11;
-export declare const ROLE_CALL_LEDGER_HEAD_KIND: "runtime_role_call_ledger_v11";
+import type { RoleOperationFingerprint, RoleOperationOutcomeFingerprint, RoleOperationSupervisionState } from "./operation-supervision.js";
+import type { RoleCapabilitySelectionSupervisionStage, RoleCapabilitySelectionSupervisionState, RoleCapabilitySelectionSupervisionTrigger } from "./capability-selection-supervision.js";
+import type { RoleCapabilitySelectionReconsiderationCause } from "./reconsideration-cause.js";
+import type { RoleCallResultReceipt } from "./result-receipt.js";
+export declare const ROLE_CALL_LEDGER_CONTRACT_VERSION = 17;
+export declare const ROLE_CALL_LEDGER_HEAD_KIND: "runtime_role_call_ledger_v17";
 export declare const ROLE_CALL_OBJECTIVE_MAX_LENGTH = 8192;
 export declare const ROLE_CALL_RESULT_MAX_LENGTH = 8192;
 export declare const ROLE_CALL_RESPONSE_MAX_LENGTH = 65536;
@@ -68,6 +72,7 @@ export type RoleCapabilitySelectionReconsideration = Readonly<{
     steeringVersion: number;
     fingerprint: string;
     selection: RoleCapabilitySelectionProjection;
+    cause: RoleCapabilitySelectionReconsiderationCause;
 }>;
 export type RoleCallFrame = Readonly<{
     callId: string;
@@ -91,6 +96,7 @@ export type RoleCallResult = Readonly<{
     roleId: RuntimeDelegateRoleId;
     outcome: "completed" | "failed";
     summary: string;
+    receipt?: RoleCallResultReceipt;
 }>;
 export type RoleCallPlanItemStatus = "pending" | "in_progress" | "done" | "blocked";
 export type RoleCallPlanProposal = Readonly<{
@@ -153,8 +159,10 @@ export type RoleCapabilityExecution = Readonly<{
     declaredEffect: RoleCapabilityDeclaredEffect;
     intent: string;
     controlsJson: string;
+    actionFingerprint?: RoleOperationFingerprint;
     status: RoleCapabilityExecutionStatus;
     outcome: RoleCapabilityExecutionOutcome | null;
+    outcomeFingerprint: RoleOperationOutcomeFingerprint | null;
     observedEffect: RoleCapabilityObservedEffect | null;
     summary: string | null;
     referenceData?: string;
@@ -175,6 +183,8 @@ export type RoleCallState = Readonly<{
     results: readonly RoleCallResult[];
     plans: readonly RoleCallPlanState[];
     capabilityExecutions: readonly RoleCapabilityExecution[];
+    operationSupervision: RoleOperationSupervisionState;
+    capabilitySelectionSupervision: RoleCapabilitySelectionSupervisionState;
     rootResponse: string | null;
 }>;
 export type RoleCallLedgerHead = CanonicalStateHead<typeof ROLE_CALL_LEDGER_HEAD_KIND, RoleCallState, RoleCallPolicy>;
@@ -206,6 +216,7 @@ export type ReturnChildRoleCallCommand = Readonly<{
     childCallId: string;
     outcome: "completed" | "failed";
     summary: string;
+    receipt?: RoleCallResultReceipt;
 }>;
 export type BeginRoleCapabilityExecutionCommand = Readonly<{
     authority: "active_role";
@@ -216,6 +227,7 @@ export type BeginRoleCapabilityExecutionCommand = Readonly<{
     declaredEffect: RoleCapabilityDeclaredEffect;
     intent: string;
     controlsJson: string;
+    actionFingerprint?: RoleOperationFingerprint;
 }>;
 export type SettleRoleCapabilityExecutionCommand = Readonly<{
     authority: "runtime";
@@ -223,6 +235,7 @@ export type SettleRoleCapabilityExecutionCommand = Readonly<{
     callId: string;
     executionId: string;
     outcome: RoleCapabilityExecutionOutcome;
+    outcomeFingerprint?: RoleOperationOutcomeFingerprint;
     observedEffect: RoleCapabilityObservedEffect;
     summary: string;
     referenceData?: string;
@@ -234,6 +247,7 @@ export type RoleCapabilityObservationBatchEntry = Readonly<{
     declaredEffect: "observation";
     intent: string;
     controlsJson: string;
+    actionFingerprint?: RoleOperationFingerprint;
 }>;
 export type BeginRoleCapabilityBatchCommand = Readonly<{
     authority: "active_role";
@@ -245,6 +259,7 @@ export type BeginRoleCapabilityBatchCommand = Readonly<{
 export type RoleCapabilityBatchSettlement = Readonly<{
     executionId: string;
     outcome: RoleCapabilityExecutionOutcome;
+    outcomeFingerprint?: RoleOperationOutcomeFingerprint;
     observedEffect: RoleCapabilityObservedEffect;
     summary: string;
     referenceData?: string;
@@ -279,6 +294,7 @@ export type ReconsiderRoleCapabilitySelectionCommand = Readonly<{
     invocationAttempt: number;
     steeringVersion: number;
     selection: RoleCapabilitySelectionProjection;
+    cause: RoleCapabilitySelectionReconsiderationCause;
 }>;
 export type RoleCallLedgerCommand = CreateRootRoleCallCommand | CompleteRootResponseCommand | OpenChildRoleCallCommand | ReturnChildRoleCallCommand | BeginRoleCapabilityExecutionCommand | SettleRoleCapabilityExecutionCommand | BeginRoleCapabilityBatchCommand | SettleRoleCapabilityBatchCommand | UpdateRoleCapabilityScopeCommand | EstablishRoleCallWorkingDirectoryCommand | ReconsiderRoleCapabilitySelectionCommand;
 export type RoleCallCommitEffect = Readonly<{
@@ -302,6 +318,17 @@ export type RoleCallCommitEffect = Readonly<{
     type: "capability_execution_begun";
     callId: string;
     executionId: string;
+}> | Readonly<{
+    type: "operation_supervision_intervened";
+    callId: string;
+    invocationAttempt: number;
+    capabilityId: string;
+    actionFingerprint: RoleOperationFingerprint;
+    priorOutcome: RoleCapabilityExecutionOutcome;
+    outcomeFingerprint: RoleOperationOutcomeFingerprint;
+    originExecutionId: string;
+    matchingOutcomeCount: 2;
+    interventionCount: 1;
 }> | Readonly<{
     type: "capability_execution_settled";
     callId: string;
@@ -327,12 +354,17 @@ export type RoleCallCommitEffect = Readonly<{
     callId: string;
     invocationAttempt: number;
     fingerprint: string;
+    supervisionFingerprint: string;
+    supervisionStage: RoleCapabilitySelectionSupervisionStage;
+    supervisionTrigger: RoleCapabilitySelectionSupervisionTrigger;
+    matchingSelectionCount: number;
+    totalReconsiderationCount: number;
 }>;
 export type RoleCallValidationIssue = Readonly<{
     code: string;
     path: string;
 }>;
-export type RoleCallTransitionRejectionCode = "invalid_current_state" | "invalid_policy" | "invalid_command" | "root_already_created" | "root_missing" | "caller_not_active" | "root_response_not_allowed" | "supervisor_child_forbidden" | "child_role_not_authorized" | "child_dependency_invalid" | "planner_plan_binding_invalid" | "planner_plan_already_declared" | "planner_plan_missing" | "planner_plan_item_unavailable" | "planner_plan_incomplete" | "depth_limit_exceeded" | "call_limit_exceeded" | "child_return_mismatch" | "capability_caller_invalid" | "capability_invocation_mismatch" | "capability_execution_limit_exceeded" | "capability_execution_mismatch" | "capability_scope_update_invalid" | "working_directory_establishment_invalid" | "capability_selection_reconsideration_invalid";
+export type RoleCallTransitionRejectionCode = "invalid_current_state" | "invalid_policy" | "invalid_command" | "root_already_created" | "root_missing" | "caller_not_active" | "root_response_not_allowed" | "supervisor_child_forbidden" | "child_role_not_authorized" | "child_dependency_invalid" | "planner_plan_binding_invalid" | "planner_plan_already_declared" | "planner_plan_missing" | "planner_plan_item_unavailable" | "planner_plan_incomplete" | "depth_limit_exceeded" | "call_limit_exceeded" | "child_return_mismatch" | "capability_caller_invalid" | "capability_invocation_mismatch" | "capability_execution_limit_exceeded" | "capability_execution_mismatch" | "capability_scope_update_invalid" | "working_directory_establishment_invalid" | "capability_selection_reconsideration_invalid" | "capability_selection_supervision_limit_exceeded" | "operation_supervision_limit_exceeded" | "role_activation_limit_exceeded";
 export type RoleCallTransitionResult = Readonly<{
     ok: true;
     state: RoleCallState;
@@ -375,6 +407,16 @@ export type RoleCallLedgerCommitObservers = Readonly<{
 export type RoleCallTransactionInput<TCommand extends RoleCallLedgerCommand> = Readonly<{
     expectedHead: unknown;
 } & Omit<TCommand, "authority" | "type">>;
+/** Transient root fence evaluated after ledger-head admission and before transition. */
+export type RoleCallCapabilityExecutionAdmission = Readonly<{
+    isCurrent(): boolean;
+}>;
+export type BeginRoleCapabilityExecutionTransactionInput = RoleCallTransactionInput<BeginRoleCapabilityExecutionCommand> & Readonly<{
+    admission?: RoleCallCapabilityExecutionAdmission;
+}>;
+export type BeginRoleCapabilityBatchTransactionInput = RoleCallTransactionInput<BeginRoleCapabilityBatchCommand> & Readonly<{
+    admission?: RoleCallCapabilityExecutionAdmission;
+}>;
 export type RoleCallTransactionSuccess<TEffectType extends RoleCallCommitEffect["type"]> = Readonly<{
     ok: true;
     commit: RoleCallLedgerCommit & Readonly<{
@@ -398,9 +440,9 @@ export type RoleCallTransactions = Readonly<{
     completeRootResponse(input: RoleCallTransactionInput<CompleteRootResponseCommand>): Promise<RoleCallTransactionResult<"root_response_committed", "root_response_transition_invalid">>;
     openChild(input: RoleCallTransactionInput<OpenChildRoleCallCommand>): Promise<RoleCallTransactionResult<"child_opened", "child_open_transition_invalid">>;
     returnChild(input: RoleCallTransactionInput<ReturnChildRoleCallCommand>): Promise<RoleCallTransactionResult<"child_returned", "child_return_transition_invalid">>;
-    beginCapabilityExecution(input: RoleCallTransactionInput<BeginRoleCapabilityExecutionCommand>): Promise<RoleCallTransactionResult<"capability_execution_begun", "commit_effect_invalid">>;
+    beginCapabilityExecution(input: BeginRoleCapabilityExecutionTransactionInput): Promise<RoleCallTransactionResult<"capability_execution_begun" | "operation_supervision_intervened", "commit_effect_invalid">>;
     settleCapabilityExecution(input: RoleCallTransactionInput<SettleRoleCapabilityExecutionCommand>): Promise<RoleCallTransactionResult<"capability_execution_settled", "commit_effect_invalid">>;
-    beginCapabilityBatch(input: RoleCallTransactionInput<BeginRoleCapabilityBatchCommand>): Promise<RoleCallTransactionResult<"capability_batch_begun", "commit_effect_invalid">>;
+    beginCapabilityBatch(input: BeginRoleCapabilityBatchTransactionInput): Promise<RoleCallTransactionResult<"capability_batch_begun" | "operation_supervision_intervened", "commit_effect_invalid">>;
     settleCapabilityBatch(input: RoleCallTransactionInput<SettleRoleCapabilityBatchCommand>): Promise<RoleCallTransactionResult<"capability_batch_settled", "commit_effect_invalid">>;
     updateCapabilityScope(input: RoleCallTransactionInput<UpdateRoleCapabilityScopeCommand>): Promise<RoleCallTransactionResult<"capability_scope_updated", "capability_scope_transition_invalid">>;
     establishWorkingDirectory(input: RoleCallTransactionInput<EstablishRoleCallWorkingDirectoryCommand>): Promise<RoleCallTransactionResult<"working_directory_established", "working_directory_transition_invalid">>;
@@ -414,5 +456,6 @@ export type RoleCallLedger = Readonly<{
     apply(input: Readonly<{
         expectedHead: unknown;
         command: unknown;
+        capabilityExecutionAdmission?: RoleCallCapabilityExecutionAdmission;
     }>): Promise<RoleCallLedgerCommitResult>;
 }>;

package/dist/src/runtime/orchestration/role-calls/contracts.js

@@ -1,5 +1,5 @@
-export const ROLE_CALL_LEDGER_CONTRACT_VERSION = 11;
-export const ROLE_CALL_LEDGER_HEAD_KIND = "runtime_role_call_ledger_v11";
+export const ROLE_CALL_LEDGER_CONTRACT_VERSION = 17;
+export const ROLE_CALL_LEDGER_HEAD_KIND = "runtime_role_call_ledger_v17";
 export const ROLE_CALL_OBJECTIVE_MAX_LENGTH = 8_192;
 export const ROLE_CALL_RESULT_MAX_LENGTH = 8_192;
 export const ROLE_CALL_RESPONSE_MAX_LENGTH = 65_536;
@@ -24,8 +24,8 @@ export function isRoleCapabilityId(input) {
 }
 export const SUPERVISOR_WORKER_V1_AUTHORITY_SNAPSHOT = Object.freeze({
     id: "supervisor-worker-v1",
-    version: 1,
-    definitionHash: "sha256:40cf0e04cbf5cf2f0ae5ce6d0e1c7aa87c21247416a7771441083ec0c73db62f",
+    version: 2,
+    definitionHash: "sha256:2ee79cee6dbb27ffaeb59f84c4c838cf9d16a965ca4f07e7d638e8589868e036",
     rootContractId: "supervisor",
     availableSubordinateContractIds: Object.freeze([
         "planner",

package/dist/src/runtime/orchestration/role-calls/dependency-results.d.ts

@@ -1,5 +1,5 @@
 import type { RoleCallFrame, RoleCallLedgerHead, RoleCallResult } from "./contracts.js";
-export type RoleCallDependencyResult = Readonly<Pick<RoleCallResult, "resultRef" | "producerCallId" | "roleId" | "outcome" | "summary">>;
+export type RoleCallDependencyResult = Readonly<Pick<RoleCallResult, "resultRef" | "producerCallId" | "roleId" | "outcome" | "summary" | "receipt">>;
 /**
  * Resolves only the canonical direct-sibling results attached to this call.
  * The role-executor boundary selects them mechanically; this projection

package/dist/src/runtime/orchestration/role-calls/dependency-results.js

@@ -67,6 +67,7 @@ function projectRoleCallDependencyResultsUnchecked(head, suppliedCall) {
             roleId: result.roleId,
             outcome: result.outcome,
             summary: result.summary,
+            ...(result.receipt ? { receipt: result.receipt } : {}),
         });
     });
     return Object.freeze(results);

package/dist/src/runtime/orchestration/role-calls/diagnostics.d.ts

@@ -4,7 +4,11 @@ export type RoleCallRejectedCommandDiagnostic = Readonly<{
     attemptedDependencyResultRefs?: readonly string[];
     attemptedExecutionId?: string;
     attemptedInvocationAttempt?: number;
+    attemptedSteeringVersion?: number;
     attemptedCapabilityId?: string;
+    attemptedActionFingerprint?: string;
+    attemptedSelectionReceiptFingerprint?: string;
+    attemptedSelectionSupervisionFingerprint?: string;
     attemptedPlanMode?: "declare" | "select" | "extend";
     attemptedPlanItemIds?: readonly string[];
     attemptedPlanItemCount?: number;

package/dist/src/runtime/orchestration/role-calls/diagnostics.js

@@ -1,7 +1,10 @@
 import { traceDebug } from "../../observability/debug-logger.js";
+import { resolveRoleActivationBudget } from "./activation-budget.js";
+import { isSuccessfulObservedMutation } from "./operation-supervision.js";
 const ROLE_CALL_LOG_SCOPE = "runtime.role_calls";
 export function traceRoleCallCommit(params) {
     const state = params.head.state;
+    const activationBudget = resolveRoleActivationBudget(state, params.head.policy);
     const common = {
         requestId: state.requestId,
         previousRevision: params.previousHead.revision,
@@ -15,11 +18,13 @@ export function traceRoleCallCommit(params) {
         maxCalls: params.head.policy.limits.maxCalls,
         maxCapabilityExecutions: params.head.policy.limits.maxCapabilityExecutions,
         maxDepth: params.head.policy.limits.maxDepth,
+        ...activationBudget,
     };
     traceDebug(ROLE_CALL_LOG_SCOPE, "transition.committed", {
         ...common,
         effectType: params.effect.type,
     });
+    traceCapabilitySelectionSupervisionReset(params, common);
     switch (params.effect.type) {
         case "root_created": {
             traceDebug(ROLE_CALL_LOG_SCOPE, "root.created", {
@@ -108,6 +113,7 @@ export function traceRoleCallCommit(params) {
                 invocationAttempt: execution?.invocationAttempt,
                 capabilityId: execution?.capabilityId,
                 declaredEffect: execution?.declaredEffect,
+                actionFingerprint: execution?.actionFingerprint,
             });
             traceDebug(ROLE_CALL_LOG_SCOPE, "caller.suspended", {
                 ...common,
@@ -116,6 +122,23 @@ export function traceRoleCallCommit(params) {
             });
             return;
         }
+        case "operation_supervision_intervened": {
+            const call = findCall(params.head, params.effect.callId);
+            traceDebug(ROLE_CALL_LOG_SCOPE, "operation.supervision_intervened", {
+                ...common,
+                callId: params.effect.callId,
+                invocationAttempt: params.effect.invocationAttempt,
+                capabilityId: params.effect.capabilityId,
+                actionFingerprint: params.effect.actionFingerprint,
+                priorOutcome: params.effect.priorOutcome,
+                outcomeFingerprint: params.effect.outcomeFingerprint,
+                originExecutionId: params.effect.originExecutionId,
+                matchingOutcomeCount: params.effect.matchingOutcomeCount,
+                interventionCount: params.effect.interventionCount,
+                activationCount: call?.activationCount,
+            });
+            return;
+        }
         case "capability_execution_settled": {
             const execution = findCapabilityExecution(params.head, params.effect.executionId);
             const call = findCall(params.head, params.effect.callId);
@@ -126,10 +149,28 @@ export function traceRoleCallCommit(params) {
                 invocationAttempt: execution?.invocationAttempt,
                 capabilityId: execution?.capabilityId,
                 declaredEffect: execution?.declaredEffect,
+                actionFingerprint: execution?.actionFingerprint,
                 outcome: execution?.outcome,
+                outcomeFingerprint: execution?.outcomeFingerprint,
                 observedEffect: execution?.observedEffect,
                 summaryLength: execution?.summary?.length ?? 0,
             });
+            if (execution &&
+                isSuccessfulObservedMutation(execution) &&
+                didClearOperationSupervision(params)) {
+                traceDebug(ROLE_CALL_LOG_SCOPE, "operation.supervision_reset", {
+                    ...common,
+                    callId: params.effect.callId,
+                    executionId: params.effect.executionId,
+                    invocationAttempt: execution.invocationAttempt,
+                    capabilityId: execution.capabilityId,
+                    actionFingerprint: execution.actionFingerprint,
+                    cause: "successful_observed_mutation",
+                    clearedEntryCount: params.previousHead.state.operationSupervision.entries.length,
+                    clearedInterventionCount: params.previousHead.state.operationSupervision.interventions.length,
+                    activationCount: call?.activationCount,
+                });
+            }
             traceDebug(ROLE_CALL_LOG_SCOPE, "caller.resumed", {
                 ...common,
                 callId: params.effect.callId,
@@ -167,6 +208,7 @@ export function traceRoleCallCommit(params) {
                 invocationAttempt: executions[0]?.invocationAttempt,
                 capabilityIds: executions.map((execution) => execution?.capabilityId),
                 outcomes: executions.map((execution) => execution?.outcome),
+                outcomeFingerprints: executions.map((execution) => execution?.outcomeFingerprint),
                 observedEffects: executions.map((execution) => execution?.observedEffect),
                 summaryLength: executions.reduce((total, execution) => total + (execution?.summary?.length ?? 0), 0),
             });
@@ -203,17 +245,46 @@ export function traceRoleCallCommit(params) {
         }
         case "capability_selection_reconsidered": {
             const call = findCall(params.head, params.effect.callId);
+            const reconsideration = call?.lastCapabilitySelectionReconsideration;
+            const cause = reconsideration?.cause;
             traceDebug(ROLE_CALL_LOG_SCOPE, "capability.selection_reconsidered", {
                 ...common,
                 callId: params.effect.callId,
                 invocationAttempt: params.effect.invocationAttempt,
+                steeringVersion: reconsideration?.steeringVersion,
                 selectionFingerprint: params.effect.fingerprint,
+                selectionReceiptFingerprint: params.effect.fingerprint,
+                selectionSupervisionFingerprint: params.effect.supervisionFingerprint,
+                selectionSupervisionStage: params.effect.supervisionStage,
+                selectionSupervisionTrigger: params.effect.supervisionTrigger,
+                matchingSelectionCount: params.effect.matchingSelectionCount,
+                totalReconsiderationCount: params.effect.totalReconsiderationCount,
                 activationCount: call?.activationCount,
+                causeKind: cause?.kind,
+                ...(cause?.kind === "refinement_declined"
+                    ? { declinedInvocationCount: cause.entries.length }
+                    : {}),
+                ...(cause?.kind === "refinement_invalid_output"
+                    ? {
+                        validationStage: cause.validationStage,
+                        issueCount: cause.issues.length,
+                        repairAttempts: cause.repairAttempts,
+                        repeatedInvalidOutput: cause.repeatedInvalidOutput,
+                    }
+                    : {}),
             });
             return;
         }
     }
 }
+function didClearOperationSupervision(params) {
+    const previous = params.previousHead.state.operationSupervision;
+    const current = params.head.state.operationSupervision;
+    const hadSupervisionEvidence = previous.entries.length > 0 || previous.interventions.length > 0;
+    return (hadSupervisionEvidence &&
+        current.entries.length === 0 &&
+        current.interventions.length === 0);
+}
 export function traceRoleCallCommitFault(params) {
     traceDebug(ROLE_CALL_LOG_SCOPE, "transition.committed_with_fault", {
         requestId: params.head.state.requestId,
@@ -233,10 +304,12 @@ export function traceRoleCallCommitFault(params) {
     });
 }
 export function traceRoleCallRejection(params) {
+    const activationBudget = resolveRoleActivationBudget(params.head.state, params.head.policy);
     const execution = params.command.attemptedExecutionId
         ? findCapabilityExecution(params.head, params.command.attemptedExecutionId)
         : undefined;
-    traceDebug(ROLE_CALL_LOG_SCOPE, "transition.rejected", {
+    const selectionSupervision = projectRejectedCapabilitySelectionSupervision(params);
+    const rejectionDiagnostic = {
         requestId: params.head.state.requestId,
         revision: params.head.revision,
         phase: params.head.state.phase,
@@ -244,7 +317,9 @@ export function traceRoleCallRejection(params) {
         activeCallId: params.head.state.activeCallId,
         commandType: params.commandType,
         rejectionCode: params.code,
+        ...activationBudget,
         ...params.command,
+        ...selectionSupervision,
         ...(execution
             ? {
                 capabilityId: execution.capabilityId,
@@ -260,6 +335,82 @@ export function traceRoleCallRejection(params) {
         maxCalls: params.head.policy.limits.maxCalls,
         maxCapabilityExecutions: params.head.policy.limits.maxCapabilityExecutions,
         maxDepth: params.head.policy.limits.maxDepth,
+    };
+    traceDebug(ROLE_CALL_LOG_SCOPE, "transition.rejected", rejectionDiagnostic);
+    if (params.code === "capability_selection_supervision_limit_exceeded") {
+        traceDebug(ROLE_CALL_LOG_SCOPE, "capability_selection.supervision_terminal", rejectionDiagnostic);
+    }
+}
+function traceCapabilitySelectionSupervisionReset(params, common) {
+    const previous = params.previousHead.state.capabilitySelectionSupervision;
+    const current = params.head.state.capabilitySelectionSupervision;
+    if (previous.records.length === 0)
+        return;
+    const cause = resolveCapabilitySelectionSupervisionResetCause(params);
+    if (!cause)
+        return;
+    traceDebug(ROLE_CALL_LOG_SCOPE, "capability_selection.supervision_reset", {
+        ...common,
+        callId: previous.epoch?.callId,
+        steeringVersion: previous.epoch?.steeringVersion,
+        resetReason: cause,
+        clearedRecordCount: previous.records.length,
+        clearedIdentityCount: new Set(previous.records.map((record) => record.supervisionFingerprint)).size,
+        nextSteeringVersion: current.epoch?.steeringVersion,
+    });
+}
+function resolveCapabilitySelectionSupervisionResetCause(params) {
+    const previous = params.previousHead.state.capabilitySelectionSupervision;
+    const current = params.head.state.capabilitySelectionSupervision;
+    if (params.effect.type === "capability_selection_reconsidered" &&
+        previous.epoch?.steeringVersion !== current.epoch?.steeringVersion) {
+        return "steering_version_changed";
+    }
+    if (current.records.length > 0)
+        return undefined;
+    switch (params.effect.type) {
+        case "root_response_committed":
+            return "root_completed";
+        case "child_opened":
+            return "child_opened";
+        case "child_returned":
+            return "child_returned";
+        case "capability_execution_begun":
+        case "capability_batch_begun":
+        case "operation_supervision_intervened":
+            return "materialized_capability_attempt";
+        case "capability_scope_updated":
+            return "capability_scope_updated";
+        case "working_directory_established":
+            return "working_directory_established";
+        default:
+            return undefined;
+    }
+}
+function projectRejectedCapabilitySelectionSupervision(params) {
+    if (params.code !== "capability_selection_supervision_limit_exceeded" ||
+        !params.command.attemptedSelectionSupervisionFingerprint) {
+        return Object.freeze({});
+    }
+    const state = params.head.state.capabilitySelectionSupervision;
+    const sameEpoch = state.epoch?.callId === params.command.attemptedCallId &&
+        state.epoch?.steeringVersion === params.command.attemptedSteeringVersion;
+    const matchingSelectionCount = (sameEpoch
+        ? state.records.filter((record) => record.supervisionFingerprint ===
+            params.command.attemptedSelectionSupervisionFingerprint).length
+        : 0) + 1;
+    const totalReconsiderationCount = (sameEpoch ? state.records.length : 0) + 1;
+    const issueCode = params.issues?.[0]?.code;
+    const trigger = issueCode === "capability_selection_repeat_limit_exceeded"
+        ? "repeat_identity"
+        : issueCode === "capability_selection_total_limit_exceeded"
+            ? "total_budget"
+            : "repeat_and_total";
+    return Object.freeze({
+        selectionSupervisionStage: "terminal",
+        selectionSupervisionTrigger: trigger,
+        matchingSelectionCount,
+        totalReconsiderationCount,
     });
 }
 function findCall(head, callId) {

package/dist/src/runtime/orchestration/role-calls/index.d.ts

@@ -1,9 +1,19 @@
 export * from "./contracts.js";
+export * from "./activation-budget.js";
+export * from "./operation-supervision.js";
+export * from "./operation-supervision-projection.js";
+export * from "./operation-supervision-state-validation.js";
 export * from "./capability-selection-reconsideration.js";
+export * from "./capability-selection-supervision.js";
+export * from "./reconsideration-cause.js";
+export * from "./result-receipt.js";
+export * from "./return-result-receipt.js";
+export * from "./work-result-lineage.js";
+export * from "./work-result-receipt.js";
 export * from "./assignment-scope.js";
 export * from "./child-return.js";
 export * from "./dependency-results.js";
-export * from "./ledger.js";
+export { createRoleCallLedger } from "./ledger.js";
 export * from "./plan.js";
 export * from "./reducer.js";
 export * from "./transactions.js";

package/dist/src/runtime/orchestration/role-calls/index.js

@@ -1,9 +1,19 @@
 export * from "./contracts.js";
+export * from "./activation-budget.js";
+export * from "./operation-supervision.js";
+export * from "./operation-supervision-projection.js";
+export * from "./operation-supervision-state-validation.js";
 export * from "./capability-selection-reconsideration.js";
+export * from "./capability-selection-supervision.js";
+export * from "./reconsideration-cause.js";
+export * from "./result-receipt.js";
+export * from "./return-result-receipt.js";
+export * from "./work-result-lineage.js";
+export * from "./work-result-receipt.js";
 export * from "./assignment-scope.js";
 export * from "./child-return.js";
 export * from "./dependency-results.js";
-export * from "./ledger.js";
+export { createRoleCallLedger } from "./ledger.js";
 export * from "./plan.js";
 export * from "./reducer.js";
 export * from "./transactions.js";

package/dist/src/runtime/orchestration/role-calls/ledger.d.ts

@@ -1,5 +1,7 @@
-import { type RoleCallLedger, type RoleCallPolicyInput } from "./contracts.js";
+import { type RoleCallLedger, type RoleCallLedgerHead, type RoleCallPolicyInput } from "./contracts.js";
 export declare function createRoleCallLedger(params: {
     requestId: string;
     policy: RoleCallPolicyInput;
 }): RoleCallLedger;
+/** Confirms exact current-head ownership without trusting structural ledgers. */
+export declare function isCurrentRoleCallLedgerHead(ledger: RoleCallLedger, head: RoleCallLedgerHead): boolean;