@abot-ai/runtime 1.0.0 → 1.1.0

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

@@ -1,8 +1,11 @@
 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";
+export declare const ROLE_CALL_LEDGER_CONTRACT_VERSION = 15;
+export declare const ROLE_CALL_LEDGER_HEAD_KIND: "runtime_role_call_ledger_v15";
 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 +71,7 @@ export type RoleCapabilitySelectionReconsideration = Readonly<{
     steeringVersion: number;
     fingerprint: string;
     selection: RoleCapabilitySelectionProjection;
+    cause: RoleCapabilitySelectionReconsiderationCause;
 }>;
 export type RoleCallFrame = Readonly<{
     callId: string;
@@ -153,8 +157,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 +181,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>;
@@ -216,6 +224,7 @@ export type BeginRoleCapabilityExecutionCommand = Readonly<{
     declaredEffect: RoleCapabilityDeclaredEffect;
     intent: string;
     controlsJson: string;
+    actionFingerprint?: RoleOperationFingerprint;
 }>;
 export type SettleRoleCapabilityExecutionCommand = Readonly<{
     authority: "runtime";
@@ -223,6 +232,7 @@ export type SettleRoleCapabilityExecutionCommand = Readonly<{
     callId: string;
     executionId: string;
     outcome: RoleCapabilityExecutionOutcome;
+    outcomeFingerprint?: RoleOperationOutcomeFingerprint;
     observedEffect: RoleCapabilityObservedEffect;
     summary: string;
     referenceData?: string;
@@ -234,6 +244,7 @@ export type RoleCapabilityObservationBatchEntry = Readonly<{
     declaredEffect: "observation";
     intent: string;
     controlsJson: string;
+    actionFingerprint?: RoleOperationFingerprint;
 }>;
 export type BeginRoleCapabilityBatchCommand = Readonly<{
     authority: "active_role";
@@ -245,6 +256,7 @@ export type BeginRoleCapabilityBatchCommand = Readonly<{
 export type RoleCapabilityBatchSettlement = Readonly<{
     executionId: string;
     outcome: RoleCapabilityExecutionOutcome;
+    outcomeFingerprint?: RoleOperationOutcomeFingerprint;
     observedEffect: RoleCapabilityObservedEffect;
     summary: string;
     referenceData?: string;
@@ -279,6 +291,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 +315,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 +351,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 +404,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 +437,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 +453,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 = 15;
+export const ROLE_CALL_LEDGER_HEAD_KIND = "runtime_role_call_ledger_v15";
 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;

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,5 +1,11 @@
 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 "./assignment-scope.js";
 export * from "./child-return.js";
 export * from "./dependency-results.js";

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

@@ -1,5 +1,11 @@
 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 "./assignment-scope.js";
 export * from "./child-return.js";
 export * from "./dependency-results.js";

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

@@ -2,17 +2,23 @@ import { consumeUnexpectedThenable } from "../synchronous-boundary.js";
 import { createCanonicalStateHeadFactory } from "../state-head.js";
 import { ROLE_CALL_LEDGER_HEAD_KIND, } from "./contracts.js";
 import { traceRoleCallCommit, traceRoleCallCommitFault, traceRoleCallRejection, } from "./diagnostics.js";
+import { issueCanonicalRoleOperationSupervisionTransition } from "./operation-supervision-issuance.js";
+import { isRoleOperationFingerprint } from "./operation-supervision.js";
+import { createRoleCapabilitySelectionFingerprint, normalizeRoleCapabilitySelectionProjection, } from "./capability-selection-reconsideration.js";
+import { createRoleCapabilitySelectionSupervisionFingerprint } from "./capability-selection-supervision.js";
+import { isIssuedRoleCapabilitySelectionSupervisionState, issueCanonicalRoleCapabilitySelectionSupervisionTransition, resolveRoleCapabilitySelectionSupervisionIssuanceAuthority, } from "./capability-selection-supervision-issuance.js";
 import { applyRoleCallCommand, createInitialRoleCallState, sealRoleCallPolicy, validateRoleCallCandidate, } from "./reducer.js";
 import { createRoleCallTransactions } from "./transactions.js";
 import { ROLE_CALL_WORKING_DIRECTORY_MAX_LENGTH } from "./working-directory.js";
-const createRoleCallStateHead = createCanonicalStateHeadFactory({
-    compatibilityHeadKind: ROLE_CALL_LEDGER_HEAD_KIND,
-    validationLabel: "role-call ledger head",
-    validateCandidate: validateRoleCallCandidate,
-});
 export function createRoleCallLedger(params) {
+    const initialState = createInitialRoleCallState(params.requestId);
+    const capabilitySelectionSupervisionIssuanceAuthority = resolveRoleCapabilitySelectionSupervisionIssuanceAuthority(initialState);
+    if (!capabilitySelectionSupervisionIssuanceAuthority) {
+        throw new Error("role_call_capability_selection_supervision_issuance_authority_missing");
+    }
+    const createRoleCallStateHead = createRoleCallStateHeadFactory(capabilitySelectionSupervisionIssuanceAuthority);
     const channel = createRoleCallStateHead({
-        state: createInitialRoleCallState(params.requestId),
+        state: initialState,
         policy: sealRoleCallPolicy(params.policy),
     });
     const commitObservers = new Set();
@@ -29,10 +35,12 @@ export function createRoleCallLedger(params) {
         const commandType = classifyCommandType(input.command);
         const capturedCommand = captureCommand(input.command);
         const commandDiagnostic = projectRejectedCommand(capturedCommand);
+        const capabilityExecutionAdmission = input.capabilityExecutionAdmission;
         const result = await channel.writer.transaction({
             expectedHead: input.expectedHead,
             run(transaction) {
-                const transition = applyRoleCallCommand(transaction.head.state, capturedCommand, transaction.head.policy);
+                const admittedCommand = projectAdmittedCapabilityExecutionCommand(commandType, capturedCommand, capabilityExecutionAdmission);
+                const transition = applyRoleCallCommand(transaction.head.state, admittedCommand, transaction.head.policy);
                 if (!transition.ok) {
                     return {
                         kind: "transition_rejected",
@@ -40,6 +48,20 @@ export function createRoleCallLedger(params) {
                         ...(transition.issues ? { issues: transition.issues } : {}),
                     };
                 }
+                if (!issueCanonicalRoleOperationSupervisionTransition({
+                    before: transaction.head.state,
+                    after: transition.state,
+                    effect: transition.effect,
+                })) {
+                    throw new Error("role_call_operation_supervision_transition_invalid");
+                }
+                if (!issueCanonicalRoleCapabilitySelectionSupervisionTransition({
+                    before: transaction.head.state,
+                    after: transition.state,
+                    effect: transition.effect,
+                })) {
+                    throw new Error("role_call_capability_selection_supervision_transition_invalid");
+                }
                 attemptedCommitEffect = transition.effect;
                 const commit = transaction.commit({
                     state: transition.state,
@@ -116,6 +138,67 @@ export function createRoleCallLedger(params) {
         apply,
     });
 }
+function createRoleCallStateHeadFactory(capabilitySelectionSupervisionIssuanceAuthority) {
+    return createCanonicalStateHeadFactory({
+        compatibilityHeadKind: ROLE_CALL_LEDGER_HEAD_KIND,
+        validationLabel: "role-call ledger head",
+        validateCandidate(candidate) {
+            const issues = validateRoleCallCandidate(candidate);
+            if (isIssuedRoleCapabilitySelectionSupervisionState({
+                state: candidate.state,
+                authority: capabilitySelectionSupervisionIssuanceAuthority,
+            }) ||
+                issues.some((issue) => issue.code === "invalid_role_capability_selection_supervision" &&
+                    issue.path === "state.capabilitySelectionSupervision")) {
+                return issues;
+            }
+            return Object.freeze([
+                ...issues,
+                Object.freeze({
+                    code: "invalid_role_capability_selection_supervision",
+                    path: "state.capabilitySelectionSupervision",
+                }),
+            ]);
+        },
+    });
+}
+function projectAdmittedCapabilityExecutionCommand(commandType, command, admission) {
+    if (admission === undefined || !isCapabilityExecutionBegin(commandType)) {
+        return command;
+    }
+    return isCapabilityExecutionCurrent(admission)
+        ? command
+        : withoutTrackedActionFingerprints(commandType, command);
+}
+function isCapabilityExecutionBegin(commandType) {
+    return (commandType === "begin_capability_execution" ||
+        commandType === "begin_capability_batch");
+}
+function isCapabilityExecutionCurrent(admission) {
+    try {
+        const result = admission.isCurrent();
+        if (consumeUnexpectedThenable(result))
+            return false;
+        return result === true;
+    }
+    catch {
+        return false;
+    }
+}
+function withoutTrackedActionFingerprints(commandType, command) {
+    if (typeof command !== "object" ||
+        command === null ||
+        Array.isArray(command)) {
+        return command;
+    }
+    const untrackedCommand = { ...command };
+    delete untrackedCommand.actionFingerprint;
+    if (commandType === "begin_capability_batch" &&
+        Array.isArray(untrackedCommand.entries)) {
+        untrackedCommand.entries = untrackedCommand.entries.map((entry) => withoutTrackedActionFingerprints("begin_capability_execution", entry));
+    }
+    return untrackedCommand;
+}
 function notifyCommitObservers(observers, commit) {
     let failed = false;
     const frozenCommit = Object.freeze(commit);
@@ -260,11 +343,52 @@ function projectRejectedCommand(input) {
             ...(safeIdentifier(command.capabilityId)
                 ? { attemptedCapabilityId: command.capabilityId }
                 : {}),
+            ...(isRoleOperationFingerprint(command.actionFingerprint)
+                ? { attemptedActionFingerprint: command.actionFingerprint }
+                : {}),
             ...(isCapabilityEffect(command.declaredEffect)
                 ? { attemptedDeclaredEffect: command.declaredEffect }
                 : {}),
         });
     }
+    if (command.type === "reconsider_capability_selection") {
+        const selection = normalizeRoleCapabilitySelectionProjection(command.selection);
+        const steeringVersion = Number.isSafeInteger(command.steeringVersion)
+            ? command.steeringVersion
+            : undefined;
+        let receiptFingerprint;
+        let supervisionFingerprint;
+        if (selection && steeringVersion !== undefined && steeringVersion >= 0) {
+            receiptFingerprint = createRoleCapabilitySelectionFingerprint({
+                steeringVersion,
+                selection,
+            });
+            supervisionFingerprint =
+                createRoleCapabilitySelectionSupervisionFingerprint({
+                    steeringVersion,
+                    selection,
+                });
+        }
+        return Object.freeze({
+            ...(safeIdentifier(command.callId)
+                ? { attemptedCallId: command.callId }
+                : {}),
+            ...(Number.isInteger(command.invocationAttempt)
+                ? { attemptedInvocationAttempt: command.invocationAttempt }
+                : {}),
+            ...(steeringVersion !== undefined
+                ? { attemptedSteeringVersion: steeringVersion }
+                : {}),
+            ...(receiptFingerprint
+                ? { attemptedSelectionReceiptFingerprint: receiptFingerprint }
+                : {}),
+            ...(supervisionFingerprint
+                ? {
+                    attemptedSelectionSupervisionFingerprint: supervisionFingerprint,
+                }
+                : {}),
+        });
+    }
     if (command.type === "update_capability_scope") {
         return Object.freeze({
             ...(safeIdentifier(command.callId)

package/dist/src/runtime/orchestration/role-calls/operation-supervision-issuance.d.ts

@@ -0,0 +1,11 @@
+import type { RoleCallCommitEffect, RoleCallState } from "./contracts.js";
+import { type RoleOperationSupervisionInterventionRecord } from "./operation-supervision.js";
+export declare function issueCanonicalRoleOperationSupervisionTransition(input: {
+    before: RoleCallState;
+    after: RoleCallState;
+    effect: RoleCallCommitEffect;
+}): boolean;
+export declare function isIssuedRoleOperationSupervisionInterventionForRequest(input: {
+    requestId: string;
+    intervention: RoleOperationSupervisionInterventionRecord;
+}): boolean;