@abot-ai/runtime 1.0.0 → 1.2.0

package/dist/src/runtime/orchestration/role-calls/command-dispatch/call-scope-transitions.js

@@ -0,0 +1,86 @@
+import { resetRoleCapabilitySelectionSupervisionState } from "../capability-selection-supervision.js";
+import { commit, reject } from "../reducer-primitives.js";
+import { parseRoleCallWorkerCapabilityScope } from "../worker-capability-scope.js";
+import { normalizeEstablishedRoleCallWorkingDirectory } from "../working-directory.js";
+import { findActiveCapabilityCaller } from "./active-capability-caller.js";
+import { replaceCall } from "./call-frame-state.js";
+export function establishWorkingDirectory(state, command, policy) {
+    const { callId, invocationAttempt, workingDirectory } = command;
+    const call = findActiveCapabilityCaller({ state, policy, callId });
+    if (!canEstablishWorkingDirectory(call, invocationAttempt)) {
+        return reject(state, "working_directory_establishment_invalid");
+    }
+    const normalized = normalizeEstablishedRoleCallWorkingDirectory(workingDirectory);
+    if (!normalized) {
+        return reject(state, "working_directory_establishment_invalid");
+    }
+    return commit({
+        ...state,
+        capabilitySelectionSupervision: resetRoleCapabilitySelectionSupervisionState(),
+        calls: replaceCall(state.calls, {
+            ...call,
+            workingDirectory: normalized,
+        }),
+    }, { type: "working_directory_established", callId });
+}
+export function updateCapabilityScope(state, command, policy) {
+    const { callId, invocationAttempt, mode, catalogGroupIds } = command;
+    const call = findActiveCapabilityCaller({ state, policy, callId });
+    if (!call) {
+        return reject(state, "capability_caller_invalid");
+    }
+    if (call.activationCount !== invocationAttempt) {
+        return reject(state, "capability_invocation_mismatch");
+    }
+    const requestedScope = parseRoleCallWorkerCapabilityScope({
+        catalogGroupIds,
+    });
+    if (!requestedScope) {
+        return reject(state, "invalid_command");
+    }
+    const nextScope = resolveCapabilityScopeUpdate(mode, call.workerCapabilityScope, requestedScope);
+    if (!nextScope) {
+        return reject(state, "capability_scope_update_invalid");
+    }
+    return commit({
+        ...state,
+        capabilitySelectionSupervision: resetRoleCapabilitySelectionSupervisionState(),
+        calls: replaceCall(state.calls, {
+            ...call,
+            workerCapabilityScope: nextScope,
+            activationCount: call.activationCount + 1,
+        }),
+    }, {
+        type: "capability_scope_updated",
+        callId,
+        mode,
+        catalogGroupIds: nextScope.catalogGroupIds,
+    });
+}
+function canEstablishWorkingDirectory(call, invocationAttempt) {
+    if (!call)
+        return false;
+    if (call.activationCount !== invocationAttempt)
+        return false;
+    return call.workingDirectory === undefined;
+}
+function resolveCapabilityScopeUpdate(mode, currentScope, requestedScope) {
+    if (mode === "open" && currentScope !== undefined)
+        return undefined;
+    if (mode === "open")
+        return requestedScope;
+    if (!currentScope)
+        return undefined;
+    if (hasOverlappingCapabilityCatalogGroups(currentScope, requestedScope)) {
+        return undefined;
+    }
+    return parseRoleCallWorkerCapabilityScope({
+        catalogGroupIds: [
+            ...currentScope.catalogGroupIds,
+            ...requestedScope.catalogGroupIds,
+        ],
+    });
+}
+function hasOverlappingCapabilityCatalogGroups(currentScope, requestedScope) {
+    return requestedScope.catalogGroupIds.some((groupId) => currentScope.catalogGroupIds.includes(groupId));
+}

package/dist/src/runtime/orchestration/role-calls/command-dispatch/capability-batch-transitions.d.ts

@@ -0,0 +1,3 @@
+import { type BeginRoleCapabilityBatchCommand, type RoleCallPolicy, type RoleCallState, type RoleCallTransitionResult, type SettleRoleCapabilityBatchCommand } from "../contracts.js";
+export declare function beginCapabilityBatch(state: RoleCallState, command: BeginRoleCapabilityBatchCommand, policy: RoleCallPolicy): RoleCallTransitionResult;
+export declare function settleCapabilityBatch(state: RoleCallState, command: SettleRoleCapabilityBatchCommand, policy: RoleCallPolicy): RoleCallTransitionResult;

package/dist/src/runtime/orchestration/role-calls/command-dispatch/capability-batch-transitions.js

@@ -0,0 +1,172 @@
+import { resetRoleCapabilitySelectionSupervisionState } from "../capability-selection-supervision.js";
+import { hasCapabilityAuthority } from "../candidate-validation.js";
+import { assessRoleOperationSupervisionBatchAttempt } from "../operation-supervision.js";
+import { commit, findCall, reject } from "../reducer-primitives.js";
+import { findActiveCapabilityCaller } from "./active-capability-caller.js";
+import { replaceCall } from "./call-frame-state.js";
+import { createRunningCapabilityExecution, nextCapabilityExecutionId, } from "./capability-execution-state.js";
+import { hasValidCapabilityInvocation } from "./capability-invocation.js";
+import { advanceOperationSupervisionForCapabilitySettlement, hasValidCapabilitySettlement, settleCapabilityExecutionRecord, } from "./capability-settlement.js";
+import { commitOperationSupervisionIntervention } from "./operation-supervision-intervention.js";
+export function beginCapabilityBatch(state, command, policy) {
+    const { callId, invocationAttempt, entries } = command;
+    const call = findActiveCapabilityCaller({ state, policy, callId });
+    if (!call) {
+        return reject(state, "capability_caller_invalid");
+    }
+    if (call.activationCount !== invocationAttempt) {
+        return reject(state, "capability_invocation_mismatch");
+    }
+    if (!hasRunnableCapabilityBatchEntries(entries)) {
+        return reject(state, "invalid_command");
+    }
+    const supervisionDecision = assessRoleOperationSupervisionBatchAttempt({
+        state: state.operationSupervision,
+        callId,
+        invocationAttempt,
+        attempts: entries,
+    });
+    if (supervisionDecision.disposition === "reject") {
+        return reject(state, supervisionDecision.issueCode);
+    }
+    if (supervisionDecision.disposition === "intervene") {
+        return commitOperationSupervisionIntervention({
+            state,
+            call,
+            invocationAttempt,
+            operationSupervision: supervisionDecision.state,
+            entry: supervisionDecision.entry,
+        });
+    }
+    if (state.capabilityExecutions.length + entries.length >
+        policy.limits.maxCapabilityExecutions) {
+        return reject(state, "capability_execution_limit_exceeded");
+    }
+    const executions = entries.map((entry, index) => createRunningCapabilityExecution({
+        executionId: nextCapabilityExecutionId(state, index),
+        callId,
+        invocationAttempt,
+        capabilityId: entry.capabilityId,
+        declaredEffect: "observation",
+        intent: entry.intent,
+        controlsJson: entry.controlsJson,
+        actionFingerprint: entry.actionFingerprint,
+    }));
+    const executionIds = Object.freeze(executions.map((execution) => execution.executionId));
+    return commit({
+        ...state,
+        capabilityExecutionSequence: state.capabilityExecutionSequence + executions.length,
+        capabilitySelectionSupervision: resetRoleCapabilitySelectionSupervisionState(),
+        calls: replaceCall(state.calls, {
+            ...call,
+            status: "waiting_for_capability",
+        }),
+        capabilityExecutions: [...state.capabilityExecutions, ...executions],
+    }, {
+        type: "capability_batch_begun",
+        callId,
+        executionIds,
+    });
+}
+export function settleCapabilityBatch(state, command, policy) {
+    const { callId, settlements } = command;
+    const matchedBatch = findMatchingCapabilityBatchSettlement(state, policy, callId, settlements);
+    if (!matchedBatch) {
+        return reject(state, "capability_execution_mismatch");
+    }
+    const { call, ownedRunning } = matchedBatch;
+    if (!hasValidCapabilityBatchSettlements(settlements, ownedRunning, call, policy)) {
+        return reject(state, "capability_execution_mismatch");
+    }
+    const byExecutionId = new Map(settlements.map((settlement) => [settlement.executionId, settlement]));
+    return commit({
+        ...state,
+        operationSupervision: advanceBatchOperationSupervision(state.operationSupervision, ownedRunning, settlements),
+        calls: replaceCall(state.calls, {
+            ...call,
+            status: "active",
+            activationCount: call.activationCount + 1,
+        }),
+        capabilityExecutions: state.capabilityExecutions.map((execution) => settleCapabilityExecutionFromBatch(execution, byExecutionId)),
+    }, {
+        type: "capability_batch_settled",
+        callId,
+        executionIds: Object.freeze(settlements.map((settlement) => settlement.executionId)),
+    });
+}
+function hasRunnableCapabilityBatchEntries(entries) {
+    if (!Array.isArray(entries))
+        return false;
+    if (entries.length < 2)
+        return false;
+    if (hasDuplicateOperationIdentities(entries))
+        return false;
+    return entries.every(hasValidCapabilityBatchEntry);
+}
+function hasValidCapabilityBatchEntry(entry) {
+    return hasValidCapabilityInvocation(entry, "observation");
+}
+function findMatchingCapabilityBatchSettlement(state, policy, callId, settlements) {
+    if (state.phase !== "running")
+        return undefined;
+    if (state.activeCallId !== callId)
+        return undefined;
+    const call = findCall(state, callId);
+    if (!hasCapabilityAuthority(policy.authority, state, call))
+        return undefined;
+    if (call.status !== "waiting_for_capability")
+        return undefined;
+    const ownedRunning = state.capabilityExecutions.filter((execution) => execution.callId === callId && execution.status === "running");
+    if (ownedRunning.length < 2)
+        return undefined;
+    if (settlements.length !== ownedRunning.length)
+        return undefined;
+    if (hasMismatchedBatchSettlementOrder(settlements, ownedRunning)) {
+        return undefined;
+    }
+    return { call, ownedRunning };
+}
+function hasMismatchedBatchSettlementOrder(settlements, ownedRunning) {
+    return settlements.some((settlement, index) => settlement.executionId !== ownedRunning[index]?.executionId);
+}
+function hasValidCapabilityBatchSettlements(settlements, ownedRunning, call, policy) {
+    for (let index = 0; index < settlements.length; index += 1) {
+        if (!hasValidCapabilityBatchSettlement(settlements[index], ownedRunning[index], call, policy)) {
+            return false;
+        }
+    }
+    return true;
+}
+function hasValidCapabilityBatchSettlement(settlement, execution, call, policy) {
+    if (execution.invocationAttempt !== call.activationCount)
+        return false;
+    if (execution.declaredEffect !== "observation")
+        return false;
+    return hasValidCapabilitySettlement(settlement, call, execution, policy);
+}
+function settleCapabilityExecutionFromBatch(execution, byExecutionId) {
+    const settlement = byExecutionId.get(execution.executionId);
+    if (!settlement)
+        return execution;
+    return settleCapabilityExecutionRecord(execution, settlement);
+}
+function hasDuplicateOperationIdentities(entries) {
+    const fingerprintsByCapability = new Map();
+    for (const entry of entries) {
+        const fingerprint = entry.actionFingerprint;
+        if (!fingerprint)
+            continue;
+        const fingerprints = fingerprintsByCapability.get(entry.capabilityId) ?? new Set();
+        if (fingerprints.has(fingerprint))
+            return true;
+        fingerprints.add(fingerprint);
+        fingerprintsByCapability.set(entry.capabilityId, fingerprints);
+    }
+    return false;
+}
+function advanceBatchOperationSupervision(current, executions, settlements) {
+    return executions.reduce((supervision, execution, index) => {
+        const settlement = settlements[index];
+        return advanceOperationSupervisionForCapabilitySettlement(supervision, execution, settlement);
+    }, current);
+}

package/dist/src/runtime/orchestration/role-calls/command-dispatch/capability-execution-state.d.ts

@@ -0,0 +1,9 @@
+import type { BeginRoleCapabilityExecutionCommand, RoleCallState, RoleCapabilityExecution } from "../contracts.js";
+type RunningCapabilityExecutionInput = Pick<BeginRoleCapabilityExecutionCommand, "callId" | "invocationAttempt" | "capabilityId" | "declaredEffect" | "intent" | "controlsJson" | "actionFingerprint"> & Readonly<{
+    executionId: string;
+}>;
+export declare function createRunningCapabilityExecution(input: RunningCapabilityExecutionInput): RoleCapabilityExecution;
+export declare function findCapabilityExecution(state: RoleCallState, executionId: string): RoleCapabilityExecution | undefined;
+export declare function replaceCapabilityExecution(executions: readonly RoleCapabilityExecution[], replacement: RoleCapabilityExecution): RoleCapabilityExecution[];
+export declare function nextCapabilityExecutionId(state: RoleCallState, offset?: number): string;
+export {};

package/dist/src/runtime/orchestration/role-calls/command-dispatch/capability-execution-state.js

@@ -0,0 +1,28 @@
+export function createRunningCapabilityExecution(input) {
+    return {
+        executionId: input.executionId,
+        callId: input.callId,
+        invocationAttempt: input.invocationAttempt,
+        capabilityId: input.capabilityId,
+        declaredEffect: input.declaredEffect,
+        intent: input.intent.trim(),
+        controlsJson: input.controlsJson,
+        ...(input.actionFingerprint
+            ? { actionFingerprint: input.actionFingerprint }
+            : {}),
+        status: "running",
+        outcome: null,
+        outcomeFingerprint: null,
+        observedEffect: null,
+        summary: null,
+    };
+}
+export function findCapabilityExecution(state, executionId) {
+    return state.capabilityExecutions.find((execution) => execution.executionId === executionId);
+}
+export function replaceCapabilityExecution(executions, replacement) {
+    return executions.map((execution) => execution.executionId === replacement.executionId ? replacement : execution);
+}
+export function nextCapabilityExecutionId(state, offset = 0) {
+    return `capability-execution-${state.capabilityExecutionSequence + offset + 1}`;
+}

package/dist/src/runtime/orchestration/role-calls/command-dispatch/capability-execution-transitions.d.ts

@@ -0,0 +1,3 @@
+import { type BeginRoleCapabilityExecutionCommand, type RoleCallPolicy, type RoleCallState, type RoleCallTransitionResult, type SettleRoleCapabilityExecutionCommand } from "../contracts.js";
+export declare function beginCapabilityExecution(state: RoleCallState, command: BeginRoleCapabilityExecutionCommand, policy: RoleCallPolicy): RoleCallTransitionResult;
+export declare function settleCapabilityExecution(state: RoleCallState, command: SettleRoleCapabilityExecutionCommand, policy: RoleCallPolicy): RoleCallTransitionResult;

package/dist/src/runtime/orchestration/role-calls/command-dispatch/capability-execution-transitions.js

@@ -0,0 +1,117 @@
+import { resetRoleCapabilitySelectionSupervisionState } from "../capability-selection-supervision.js";
+import { hasCapabilityAuthority } from "../candidate-validation.js";
+import { assessRoleOperationSupervisionAttempt } from "../operation-supervision.js";
+import { commit, findCall, reject } from "../reducer-primitives.js";
+import { findActiveCapabilityCaller } from "./active-capability-caller.js";
+import { replaceCall } from "./call-frame-state.js";
+import { createRunningCapabilityExecution, findCapabilityExecution, nextCapabilityExecutionId, replaceCapabilityExecution, } from "./capability-execution-state.js";
+import { hasValidCapabilityInvocation } from "./capability-invocation.js";
+import { advanceOperationSupervisionForCapabilitySettlement, hasValidCapabilitySettlement, settleCapabilityExecutionRecord, } from "./capability-settlement.js";
+import { commitOperationSupervisionIntervention } from "./operation-supervision-intervention.js";
+export function beginCapabilityExecution(state, command, policy) {
+    const { callId, invocationAttempt, capabilityId, declaredEffect, intent, controlsJson, actionFingerprint, } = command;
+    const call = findActiveCapabilityCaller({ state, policy, callId });
+    if (!call) {
+        return reject(state, "capability_caller_invalid");
+    }
+    if (call.activationCount !== invocationAttempt) {
+        return reject(state, "capability_invocation_mismatch");
+    }
+    if (!hasValidCapabilityInvocation(command)) {
+        return reject(state, "invalid_command");
+    }
+    const supervisionDecision = assessRoleOperationSupervisionAttempt({
+        state: state.operationSupervision,
+        callId,
+        invocationAttempt,
+        capabilityId,
+        actionFingerprint,
+    });
+    if (supervisionDecision.disposition === "reject") {
+        return reject(state, supervisionDecision.issueCode);
+    }
+    if (supervisionDecision.disposition === "intervene") {
+        return commitOperationSupervisionIntervention({
+            state,
+            call,
+            invocationAttempt,
+            operationSupervision: supervisionDecision.state,
+            entry: supervisionDecision.entry,
+        });
+    }
+    if (state.capabilityExecutions.length >= policy.limits.maxCapabilityExecutions) {
+        return reject(state, "capability_execution_limit_exceeded");
+    }
+    const executionId = nextCapabilityExecutionId(state);
+    const execution = createRunningCapabilityExecution({
+        executionId,
+        callId,
+        invocationAttempt,
+        capabilityId,
+        declaredEffect,
+        intent,
+        controlsJson,
+        actionFingerprint,
+    });
+    return commit({
+        ...state,
+        capabilityExecutionSequence: state.capabilityExecutionSequence + 1,
+        capabilitySelectionSupervision: resetRoleCapabilitySelectionSupervisionState(),
+        calls: replaceCall(state.calls, {
+            ...call,
+            status: "waiting_for_capability",
+        }),
+        capabilityExecutions: [...state.capabilityExecutions, execution],
+    }, {
+        type: "capability_execution_begun",
+        callId,
+        executionId,
+    });
+}
+export function settleCapabilityExecution(state, command, policy) {
+    const { callId, executionId } = command;
+    const matchedSettlement = findMatchingCapabilitySettlement(state, policy, callId, executionId);
+    if (!matchedSettlement) {
+        return reject(state, "capability_execution_mismatch");
+    }
+    const { call, execution } = matchedSettlement;
+    if (!hasValidCapabilitySettlement(command, call, execution, policy)) {
+        return reject(state, "capability_execution_mismatch");
+    }
+    return commit({
+        ...state,
+        operationSupervision: advanceOperationSupervisionForCapabilitySettlement(state.operationSupervision, execution, command),
+        calls: replaceCall(state.calls, {
+            ...call,
+            status: "active",
+            activationCount: call.activationCount + 1,
+        }),
+        capabilityExecutions: replaceCapabilityExecution(state.capabilityExecutions, settleCapabilityExecutionRecord(execution, command)),
+    }, {
+        type: "capability_execution_settled",
+        callId,
+        executionId,
+    });
+}
+function findMatchingCapabilitySettlement(state, policy, callId, executionId) {
+    if (state.phase !== "running")
+        return undefined;
+    if (state.activeCallId !== callId)
+        return undefined;
+    const call = findCall(state, callId);
+    if (!hasCapabilityAuthority(policy.authority, state, call))
+        return undefined;
+    if (call.status !== "waiting_for_capability")
+        return undefined;
+    const execution = findCapabilityExecution(state, executionId);
+    if (execution?.status !== "running")
+        return undefined;
+    if (execution.callId !== callId)
+        return undefined;
+    if (execution.invocationAttempt !== call.activationCount)
+        return undefined;
+    const ownedRunningCount = state.capabilityExecutions.filter((candidate) => candidate.callId === callId && candidate.status === "running").length;
+    if (ownedRunningCount !== 1)
+        return undefined;
+    return { call, execution };
+}

package/dist/src/runtime/orchestration/role-calls/command-dispatch/capability-invocation.d.ts

@@ -0,0 +1,4 @@
+import { type BeginRoleCapabilityExecutionCommand, type RoleCapabilityDeclaredEffect } from "../contracts.js";
+type CapabilityInvocation = Pick<BeginRoleCapabilityExecutionCommand, "capabilityId" | "declaredEffect" | "intent" | "controlsJson">;
+export declare function hasValidCapabilityInvocation(invocation: CapabilityInvocation, requiredDeclaredEffect?: RoleCapabilityDeclaredEffect): boolean;
+export {};

package/dist/src/runtime/orchestration/role-calls/command-dispatch/capability-invocation.js

@@ -0,0 +1,16 @@
+import { isRoleCapabilityId, ROLE_CAPABILITY_INVOCATION_INTENT_MAX_LENGTH, } from "../contracts.js";
+import { isBoundedText, isExactJsonObjectString, isRoleCapabilityDeclaredEffect, } from "../reducer-primitives.js";
+export function hasValidCapabilityInvocation(invocation, requiredDeclaredEffect) {
+    if (!isRoleCapabilityId(invocation.capabilityId))
+        return false;
+    if (requiredDeclaredEffect !== undefined &&
+        invocation.declaredEffect !== requiredDeclaredEffect) {
+        return false;
+    }
+    if (!isRoleCapabilityDeclaredEffect(invocation.declaredEffect))
+        return false;
+    if (!isBoundedText(invocation.intent, ROLE_CAPABILITY_INVOCATION_INTENT_MAX_LENGTH)) {
+        return false;
+    }
+    return isExactJsonObjectString(invocation.controlsJson);
+}

package/dist/src/runtime/orchestration/role-calls/command-dispatch/capability-selection-transition.d.ts

@@ -0,0 +1,2 @@
+import type { ReconsiderRoleCapabilitySelectionCommand, RoleCallPolicy, RoleCallState, RoleCallTransitionResult } from "../contracts.js";
+export declare function reconsiderCapabilitySelection(state: RoleCallState, command: ReconsiderRoleCapabilitySelectionCommand, policy: RoleCallPolicy): RoleCallTransitionResult;

package/dist/src/runtime/orchestration/role-calls/command-dispatch/capability-selection-transition.js

@@ -0,0 +1,114 @@
+import { createRoleCapabilitySelectionFingerprint, normalizeRoleCapabilitySelectionProjection, } from "../capability-selection-reconsideration.js";
+import { assessRoleCapabilitySelectionSupervisionReconsideration, } from "../capability-selection-supervision.js";
+import { isReconsiderationCauseBoundToInvocationCount, normalizeRoleCapabilitySelectionReconsiderationCause, } from "../reconsideration-cause.js";
+import { commit, reject, sameStringArray } from "../reducer-primitives.js";
+import { findActiveCapabilityCaller } from "./active-capability-caller.js";
+import { replaceCall } from "./call-frame-state.js";
+export function reconsiderCapabilitySelection(state, command, policy) {
+    const { callId, invocationAttempt, steeringVersion, selection, cause } = command;
+    const call = findActiveCapabilityCaller({ state, policy, callId });
+    if (!call) {
+        return reject(state, "capability_selection_reconsideration_invalid");
+    }
+    if (!matchesActiveCapabilitySelection(call, invocationAttempt, selection)) {
+        return reject(state, "capability_selection_reconsideration_invalid");
+    }
+    if (!isNonNegativeSafeSteeringVersion(steeringVersion)) {
+        return reject(state, "capability_selection_reconsideration_invalid");
+    }
+    const normalizedSelection = normalizeRoleCapabilitySelectionProjection(selection);
+    const normalizedCause = normalizeRoleCapabilitySelectionReconsiderationCause(cause);
+    if (!normalizedSelection || !normalizedCause) {
+        return reject(state, "capability_selection_reconsideration_invalid");
+    }
+    if (!isCauseBoundToSelectedInvocations(normalizedCause, normalizedSelection)) {
+        return reject(state, "capability_selection_reconsideration_invalid");
+    }
+    const fingerprint = createRoleCapabilitySelectionFingerprint({
+        steeringVersion,
+        selection: normalizedSelection,
+    });
+    const supervisionEpoch = state.capabilitySelectionSupervision.epoch;
+    if (!isCompatibleSelectionSupervisionEpoch(supervisionEpoch, callId, steeringVersion)) {
+        return reject(state, "capability_selection_reconsideration_invalid");
+    }
+    const supervision = assessRoleCapabilitySelectionSupervisionReconsideration({
+        state: state.capabilitySelectionSupervision,
+        callId,
+        invocationAttempt,
+        steeringVersion,
+        receiptFingerprint: fingerprint,
+        selection: normalizedSelection,
+    });
+    if (supervision.disposition === "reject") {
+        return reject(state, supervision.issueCode, [
+            {
+                code: capabilitySelectionLimitIssueCode(supervision.trigger),
+                path: "state.capabilitySelectionSupervision",
+            },
+        ]);
+    }
+    const reconsideration = {
+        invocationAttempt,
+        steeringVersion,
+        fingerprint,
+        selection: normalizedSelection,
+        cause: normalizedCause,
+    };
+    return commit({
+        ...state,
+        capabilitySelectionSupervision: supervision.state,
+        calls: replaceCall(state.calls, {
+            ...call,
+            activationCount: call.activationCount + 1,
+            lastCapabilitySelectionReconsideration: reconsideration,
+        }),
+    }, {
+        type: "capability_selection_reconsidered",
+        callId,
+        invocationAttempt,
+        fingerprint,
+        supervisionFingerprint: supervision.supervisionFingerprint,
+        supervisionStage: supervision.disposition,
+        supervisionTrigger: supervision.trigger,
+        matchingSelectionCount: supervision.identityCount,
+        totalReconsiderationCount: supervision.totalCount,
+    });
+}
+function matchesActiveCapabilitySelection(call, invocationAttempt, selection) {
+    if (call.activationCount !== invocationAttempt)
+        return false;
+    const activeScope = call.workerCapabilityScope?.catalogGroupIds;
+    if (!activeScope)
+        return false;
+    if (!sameStringArray(activeScope, selection.activeCapabilityCatalogGroupIds)) {
+        return false;
+    }
+    if (call.workingDirectory === undefined)
+        return true;
+    return selection.workingDirectory === call.workingDirectory;
+}
+function isNonNegativeSafeSteeringVersion(steeringVersion) {
+    if (!Number.isSafeInteger(steeringVersion))
+        return false;
+    return steeringVersion >= 0;
+}
+function isCauseBoundToSelectedInvocations(cause, selection) {
+    return isReconsiderationCauseBoundToInvocationCount(cause, selection.invocations.length);
+}
+function isCompatibleSelectionSupervisionEpoch(epoch, callId, steeringVersion) {
+    if (!epoch)
+        return true;
+    if (epoch.callId !== callId)
+        return false;
+    return steeringVersion >= epoch.steeringVersion;
+}
+function capabilitySelectionLimitIssueCode(trigger) {
+    if (trigger === "repeat_identity") {
+        return "capability_selection_repeat_limit_exceeded";
+    }
+    if (trigger === "total_budget") {
+        return "capability_selection_total_limit_exceeded";
+    }
+    return "capability_selection_repeat_and_total_limit_exceeded";
+}

package/dist/src/runtime/orchestration/role-calls/command-dispatch/capability-settlement.d.ts

@@ -0,0 +1,6 @@
+import { type RoleCallFrame, type RoleCallPolicy, type RoleCallState, type RoleCapabilityBatchSettlement, type RoleCapabilityExecution } from "../contracts.js";
+type CapabilitySettlement = Omit<RoleCapabilityBatchSettlement, "executionId">;
+export declare function hasValidCapabilitySettlement(settlement: CapabilitySettlement, call: RoleCallFrame, execution: RoleCapabilityExecution, policy: RoleCallPolicy): boolean;
+export declare function settleCapabilityExecutionRecord(execution: RoleCapabilityExecution, settlement: CapabilitySettlement): RoleCapabilityExecution;
+export declare function advanceOperationSupervisionForCapabilitySettlement(current: RoleCallState["operationSupervision"], execution: RoleCapabilityExecution, settlement: CapabilitySettlement): RoleCallState["operationSupervision"];
+export {};

package/dist/src/runtime/orchestration/role-calls/command-dispatch/capability-settlement.js

@@ -0,0 +1,54 @@
+import { ROLE_CAPABILITY_REFERENCE_DATA_MAX_LENGTH, } from "../contracts.js";
+import { advanceRoleOperationSupervisionSettlement } from "../operation-supervision.js";
+import { isBoundedText, isExactResultValidForCall, isOptionalBoundedText, isSettledObservedEffectCompatible, isValidCapabilityResultReferences, } from "../reducer-primitives.js";
+export function hasValidCapabilitySettlement(settlement, call, execution, policy) {
+    if (!isBoundedText(settlement.summary, policy.limits.maxResultChars)) {
+        return false;
+    }
+    if (!isOptionalBoundedText(settlement.referenceData, ROLE_CAPABILITY_REFERENCE_DATA_MAX_LENGTH)) {
+        return false;
+    }
+    if (!isValidCapabilityResultReferences(settlement.references))
+        return false;
+    if (!isExactResultValidForCall(call, settlement.exactResult))
+        return false;
+    if (settlement.outcome !== "succeeded" && settlement.outcome !== "failed") {
+        return false;
+    }
+    return isSettledObservedEffectCompatible({
+        declaredEffect: execution.declaredEffect,
+        outcome: settlement.outcome,
+        observedEffect: settlement.observedEffect,
+    });
+}
+export function settleCapabilityExecutionRecord(execution, settlement) {
+    return {
+        ...execution,
+        status: "settled",
+        outcome: settlement.outcome,
+        outcomeFingerprint: settlement.outcomeFingerprint ?? null,
+        observedEffect: settlement.observedEffect,
+        summary: settlement.summary.trim(),
+        ...(settlement.referenceData
+            ? { referenceData: settlement.referenceData }
+            : {}),
+        ...(settlement.references && settlement.references.length > 0
+            ? { references: Object.freeze([...settlement.references]) }
+            : {}),
+        exactResult: settlement.exactResult,
+    };
+}
+export function advanceOperationSupervisionForCapabilitySettlement(current, execution, settlement) {
+    return advanceRoleOperationSupervisionSettlement(current, {
+        capabilityId: execution.capabilityId,
+        ...(execution.actionFingerprint
+            ? { actionFingerprint: execution.actionFingerprint }
+            : {}),
+        outcome: settlement.outcome,
+        ...(settlement.outcomeFingerprint
+            ? { outcomeFingerprint: settlement.outcomeFingerprint }
+            : {}),
+        observedEffect: settlement.observedEffect,
+        originExecutionId: execution.executionId,
+    });
+}

package/dist/src/runtime/orchestration/role-calls/command-dispatch/child-transitions.d.ts

@@ -0,0 +1,3 @@
+import type { OpenChildRoleCallCommand, ReturnChildRoleCallCommand, RoleCallPolicy, RoleCallState, RoleCallTransitionResult } from "../contracts.js";
+export declare function openChild(state: RoleCallState, command: OpenChildRoleCallCommand, policy: RoleCallPolicy): RoleCallTransitionResult;
+export declare function returnChild(state: RoleCallState, command: ReturnChildRoleCallCommand, policy: RoleCallPolicy, admittedHeadRevision?: number): RoleCallTransitionResult;