@abot-ai/runtime 1.0.0 → 1.2.0

package/dist/src/runtime/orchestration/role-calls/capability-selection-supervision.js

@@ -0,0 +1,339 @@
+import { createHash } from "node:crypto";
+import { exactKeys, isRecord } from "../../validation/strict-record.js";
+import { isRoleCapabilityId, ROLE_CAPABILITY_INVOCATION_CONTROLS_JSON_MAX_LENGTH, ROLE_CAPABILITY_SELECTION_INVOCATION_LIMIT_MAX, } from "./contracts.js";
+import { normalizeEstablishedRoleCallWorkingDirectory } from "./working-directory.js";
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_FINGERPRINT_PATTERN = /^sha256:[a-f0-9]{64}$/;
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_REPEAT_WARNING_COUNT = 2;
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_REPEAT_INTERVENTION_COUNT = 3;
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_REPEAT_LIMIT = 4;
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_WARNING_COUNT = 6;
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_INTERVENTION_COUNT = 7;
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_LIMIT = 8;
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_RECORD_LIMIT = ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_LIMIT - 1;
+export function createInitialRoleCapabilitySelectionSupervisionState() {
+    return Object.freeze({
+        epoch: null,
+        records: Object.freeze([]),
+    });
+}
+export function createRoleCapabilitySelectionSupervisionFingerprint(input) {
+    if (!isNonNegativeSafeInteger(input.steeringVersion)) {
+        throw new Error("role_capability_selection_supervision_steering_version_invalid");
+    }
+    const canonicalSelection = canonicalizeSupervisedSelection(input.selection);
+    if (!canonicalSelection) {
+        throw new Error("role_capability_selection_supervision_selection_invalid");
+    }
+    const canonical = JSON.stringify({
+        steeringVersion: input.steeringVersion,
+        ...canonicalSelection,
+    });
+    return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+export function assessRoleCapabilitySelectionSupervisionReconsideration(input) {
+    if (!isRoleCapabilitySelectionSupervisionState(input.state)) {
+        throw new Error("role_capability_selection_supervision_state_invalid");
+    }
+    if (!isBoundedCallId(input.callId)) {
+        throw new Error("role_capability_selection_supervision_call_id_invalid");
+    }
+    if (!Number.isSafeInteger(input.invocationAttempt) ||
+        input.invocationAttempt < 1) {
+        throw new Error("role_capability_selection_supervision_invocation_attempt_invalid");
+    }
+    if (!isRoleCapabilitySelectionSupervisionFingerprint(input.receiptFingerprint)) {
+        throw new Error("role_capability_selection_supervision_receipt_fingerprint_invalid");
+    }
+    const epochState = resolveAssessmentEpoch(input);
+    const previousRecord = epochState.records.at(-1);
+    if (previousRecord &&
+        input.invocationAttempt <= previousRecord.invocationAttempt) {
+        throw new Error("role_capability_selection_supervision_invocation_order_invalid");
+    }
+    const supervisionFingerprint = createRoleCapabilitySelectionSupervisionFingerprint({
+        steeringVersion: input.steeringVersion,
+        selection: input.selection,
+    });
+    const identityCount = epochState.records.filter((record) => record.supervisionFingerprint === supervisionFingerprint).length + 1;
+    const totalCount = epochState.records.length + 1;
+    const stageDecision = strongestStageDecision(identityCount, totalCount);
+    const attemptedRecord = Object.freeze({
+        invocationAttempt: input.invocationAttempt,
+        receiptFingerprint: input.receiptFingerprint,
+        supervisionFingerprint,
+    });
+    if (stageDecision.stage === "reject") {
+        return Object.freeze({
+            disposition: "reject",
+            issueCode: "capability_selection_supervision_limit_exceeded",
+            attemptedRecord,
+            supervisionFingerprint,
+            identityCount,
+            totalCount,
+            trigger: stageDecision.trigger,
+        });
+    }
+    const record = Object.freeze({
+        ...attemptedRecord,
+        identityCount,
+        totalCount,
+        stage: stageDecision.stage,
+        trigger: stageDecision.trigger,
+    });
+    const state = Object.freeze({
+        epoch: epochState.epoch,
+        records: Object.freeze([...epochState.records, record]),
+    });
+    return Object.freeze({
+        disposition: stageDecision.stage,
+        state,
+        record,
+        supervisionFingerprint,
+        identityCount,
+        totalCount,
+        trigger: stageDecision.trigger,
+    });
+}
+export function resetRoleCapabilitySelectionSupervisionState() {
+    return createInitialRoleCapabilitySelectionSupervisionState();
+}
+export function replayRoleCapabilitySelectionSupervisionRecords(input) {
+    if (input.epoch === null) {
+        return input.records.length === 0
+            ? createInitialRoleCapabilitySelectionSupervisionState()
+            : undefined;
+    }
+    if (!isRoleCapabilitySelectionSupervisionEpoch(input.epoch))
+        return undefined;
+    if (input.records.length < 1 ||
+        input.records.length > ROLE_CAPABILITY_SELECTION_SUPERVISION_RECORD_LIMIT) {
+        return undefined;
+    }
+    const replayed = [];
+    for (const candidate of input.records) {
+        if (!isRoleCapabilitySelectionSupervisionRecord(candidate))
+            return undefined;
+        const previous = replayed.at(-1);
+        if (previous && candidate.invocationAttempt <= previous.invocationAttempt) {
+            return undefined;
+        }
+        const identityCount = replayed.filter((record) => record.supervisionFingerprint === candidate.supervisionFingerprint).length + 1;
+        const decision = strongestStageDecision(identityCount, replayed.length + 1);
+        if (decision.stage === "reject" ||
+            decision.stage !== candidate.stage ||
+            candidate.identityCount !== identityCount ||
+            candidate.totalCount !== replayed.length + 1 ||
+            candidate.trigger !== decision.trigger) {
+            return undefined;
+        }
+        replayed.push(Object.freeze({ ...candidate }));
+    }
+    return Object.freeze({
+        epoch: Object.freeze({ ...input.epoch }),
+        records: Object.freeze(replayed),
+    });
+}
+export function isRoleCapabilitySelectionSupervisionState(input) {
+    if (!isRecord(input) ||
+        !exactKeys(input, ["epoch", "records"]) ||
+        !Array.isArray(input.records)) {
+        return false;
+    }
+    return (replayRoleCapabilitySelectionSupervisionRecords({
+        epoch: input.epoch,
+        records: input.records,
+    }) !== undefined);
+}
+export function isRoleCapabilitySelectionSupervisionFingerprint(input) {
+    return (typeof input === "string" &&
+        ROLE_CAPABILITY_SELECTION_SUPERVISION_FINGERPRINT_PATTERN.test(input));
+}
+function resolveAssessmentEpoch(input) {
+    if (!isNonNegativeSafeInteger(input.steeringVersion)) {
+        throw new Error("role_capability_selection_supervision_steering_version_invalid");
+    }
+    const epoch = input.state.epoch;
+    if (!epoch) {
+        return createEpochState(input.callId, input.steeringVersion);
+    }
+    if (epoch.callId !== input.callId) {
+        throw new Error("role_capability_selection_supervision_epoch_call_invalid");
+    }
+    if (input.steeringVersion < epoch.steeringVersion) {
+        throw new Error("role_capability_selection_supervision_steering_stale");
+    }
+    return input.steeringVersion === epoch.steeringVersion
+        ? Object.freeze({ epoch, records: input.state.records })
+        : createEpochState(input.callId, input.steeringVersion);
+}
+function createEpochState(callId, steeringVersion) {
+    return Object.freeze({
+        epoch: Object.freeze({ callId, steeringVersion }),
+        records: Object.freeze([]),
+    });
+}
+function strongestStageDecision(identityCount, totalCount) {
+    const repeatStage = repeatStageForCount(identityCount);
+    const totalStage = totalStageForCount(totalCount);
+    const repeatRank = stageRank(repeatStage);
+    const totalRank = stageRank(totalStage);
+    const trigger = totalCount >= ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_WARNING_COUNT &&
+        repeatRank === totalRank
+        ? "repeat_and_total"
+        : totalRank > repeatRank
+            ? "total_budget"
+            : "repeat_identity";
+    return Object.freeze({
+        stage: repeatRank >= totalRank ? repeatStage : totalStage,
+        trigger,
+    });
+}
+function repeatStageForCount(count) {
+    if (count >= ROLE_CAPABILITY_SELECTION_SUPERVISION_REPEAT_LIMIT) {
+        return "reject";
+    }
+    if (count >= ROLE_CAPABILITY_SELECTION_SUPERVISION_REPEAT_INTERVENTION_COUNT) {
+        return "intervened";
+    }
+    return count >= ROLE_CAPABILITY_SELECTION_SUPERVISION_REPEAT_WARNING_COUNT
+        ? "warning"
+        : "tracking";
+}
+function totalStageForCount(count) {
+    if (count >= ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_LIMIT) {
+        return "reject";
+    }
+    if (count >= ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_INTERVENTION_COUNT) {
+        return "intervened";
+    }
+    return count >= ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_WARNING_COUNT
+        ? "warning"
+        : "tracking";
+}
+function stageRank(stage) {
+    return stage === "tracking"
+        ? 0
+        : stage === "warning"
+            ? 1
+            : stage === "intervened"
+                ? 2
+                : 3;
+}
+function canonicalizeSupervisedSelection(selection) {
+    if (!isRecord(selection) || !Array.isArray(selection.invocations)) {
+        return undefined;
+    }
+    const selectionKind = selection.action === "invoke_capability"
+        ? "single"
+        : selection.action === "invoke_capabilities"
+            ? "batch"
+            : undefined;
+    if (!selectionKind ||
+        selection.invocations.length < 1 ||
+        selection.invocations.length >
+            ROLE_CAPABILITY_SELECTION_INVOCATION_LIMIT_MAX ||
+        (selectionKind === "single"
+            ? selection.invocations.length !== 1
+            : selection.invocations.length < 2)) {
+        return undefined;
+    }
+    const workingDirectory = normalizeEffectiveWorkingDirectory(selection.workingDirectory);
+    if (!workingDirectory)
+        return undefined;
+    const invocations = selection.invocations.map((invocation) => {
+        if (!isRecord(invocation) || !isRoleCapabilityId(invocation.capabilityId)) {
+            return undefined;
+        }
+        const selectionControlsJson = canonicalizeControlsJson(invocation.selectionControlsJson);
+        return selectionControlsJson === undefined
+            ? undefined
+            : Object.freeze({
+                capabilityId: invocation.capabilityId,
+                selectionControlsJson,
+            });
+    });
+    if (invocations.some((invocation) => invocation === undefined)) {
+        return undefined;
+    }
+    const canonicalInvocations = invocations;
+    return Object.freeze({
+        selectionKind,
+        workingDirectory,
+        invocations: Object.freeze(selectionKind === "batch"
+            ? [...canonicalInvocations].sort(compareCanonicalInvocation)
+            : canonicalInvocations),
+    });
+}
+function normalizeEffectiveWorkingDirectory(input) {
+    return input === undefined || input === null
+        ? "."
+        : normalizeEstablishedRoleCallWorkingDirectory(input);
+}
+function canonicalizeControlsJson(input) {
+    if (typeof input !== "string" ||
+        input.length < 2 ||
+        input.length > ROLE_CAPABILITY_INVOCATION_CONTROLS_JSON_MAX_LENGTH) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(input);
+        return isRecord(parsed)
+            ? JSON.stringify(canonicalizeJsonValue(parsed))
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function canonicalizeJsonValue(input) {
+    if (Array.isArray(input))
+        return input.map(canonicalizeJsonValue);
+    if (!isRecord(input))
+        return input;
+    return Object.fromEntries(Object.keys(input)
+        .sort()
+        .map((key) => [key, canonicalizeJsonValue(input[key])]));
+}
+function compareCanonicalInvocation(left, right) {
+    const leftJson = JSON.stringify(left);
+    const rightJson = JSON.stringify(right);
+    return leftJson < rightJson ? -1 : leftJson > rightJson ? 1 : 0;
+}
+function isRoleCapabilitySelectionSupervisionEpoch(input) {
+    return (isRecord(input) &&
+        exactKeys(input, ["callId", "steeringVersion"]) &&
+        isBoundedCallId(input.callId) &&
+        isNonNegativeSafeInteger(input.steeringVersion));
+}
+function isRoleCapabilitySelectionSupervisionRecord(input) {
+    return (isRecord(input) &&
+        exactKeys(input, [
+            "invocationAttempt",
+            "receiptFingerprint",
+            "supervisionFingerprint",
+            "identityCount",
+            "totalCount",
+            "stage",
+            "trigger",
+        ]) &&
+        Number.isSafeInteger(input.invocationAttempt) &&
+        input.invocationAttempt >= 1 &&
+        isRoleCapabilitySelectionSupervisionFingerprint(input.receiptFingerprint) &&
+        isRoleCapabilitySelectionSupervisionFingerprint(input.supervisionFingerprint) &&
+        Number.isSafeInteger(input.identityCount) &&
+        input.identityCount >= 1 &&
+        Number.isSafeInteger(input.totalCount) &&
+        input.totalCount >= 1 &&
+        (input.stage === "tracking" ||
+            input.stage === "warning" ||
+            input.stage === "intervened") &&
+        (input.trigger === "repeat_identity" ||
+            input.trigger === "total_budget" ||
+            input.trigger === "repeat_and_total"));
+}
+function isBoundedCallId(input) {
+    return typeof input === "string" && input.length > 0 && input.length <= 256;
+}
+function isNonNegativeSafeInteger(input) {
+    return Number.isSafeInteger(input) && input >= 0;
+}

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

@@ -1,5 +1,7 @@
 import { type RoleCallCommitEffect, type RoleCallLedger, type RoleCallLedgerCommitResult, type RoleCallLedgerHead, type RoleCallWorkerCapabilityScope } from "./contracts.js";
 import { type RuntimeDelegateRoleId } from "../roles.js";
+import { type RoleCallResultReceipt } from "./result-receipt.js";
+import { type RoleCallWorkResultLineage } from "./work-result-lineage.js";
 export type CompletedRoleChildResult = Readonly<{
     callerCallId: string;
     childCallId: string;
@@ -11,6 +13,8 @@ export type CompletedRoleChildResult = Readonly<{
     dependencyResultRefs: readonly string[];
     outcome: "completed" | "failed";
     summary: string;
+    receipt?: RoleCallResultReceipt;
+    workLineage?: RoleCallWorkResultLineage;
 }>;
 export type RoleChildReturnContext = Readonly<{
     callerCallId: string;

package/dist/src/runtime/orchestration/role-calls/child-return.js

@@ -1,5 +1,7 @@
 import { ROLE_CALL_OBJECTIVE_MAX_LENGTH, ROLE_CALL_RESULT_MAX_LENGTH, } from "./contracts.js";
 import { isRuntimeDelegateRoleId, } from "../roles.js";
+import { isRoleCallResultReceiptValidForStoredResult, } from "./result-receipt.js";
+import { projectRoleCallWorkResultLineage, } from "./work-result-lineage.js";
 export function requireRoleCallChildReturnCommit(commit) {
     if (!commit.ok || commit.effect.type !== "child_returned") {
         throw new Error("role_child_return_commit_invalid");
@@ -27,7 +29,7 @@ export function projectRoleChildReturnContext(ledger, commit) {
         !caller.childCallIds.includes(childCallId)) {
         throw new Error("role_child_return_transition_invalid");
     }
-    const completedChildren = projectCompletedChildren(returned.head.state, caller);
+    const completedChildren = projectCompletedChildren(returned.head.state, caller, returned.head.policy);
     const returnedChild = completedChildren.find((child) => child.childCallId === childCallId && child.resultRef === resultRef);
     if (returnedChild?.childCallId !== childCallId ||
         returnedChild.resultRef !== resultRef) {
@@ -41,13 +43,13 @@ export function projectRoleChildReturnContext(ledger, commit) {
         completedChildren: Object.freeze(completedChildren),
     });
 }
-function projectCompletedChildren(state, caller) {
+function projectCompletedChildren(state, caller, policy) {
     return Object.freeze(caller.childCallIds.map((completedChildCallId) => projectCompletedChild(state, {
         callerCallId: caller.callId,
         childCallId: completedChildCallId,
-    })));
+    }, policy)));
 }
-function projectCompletedChild(state, refs) {
+function projectCompletedChild(state, refs, policy) {
     const child = state.calls.find((call) => call.callId === refs.childCallId);
     const result = state.results.find((candidate) => candidate.resultRef === child?.resultRef);
     if (child?.status !== "completed" ||
@@ -58,9 +60,17 @@ function projectCompletedChild(state, refs) {
         result?.producerCallId !== child.callId ||
         result.roleId !== child.roleId ||
         (result.outcome !== "completed" && result.outcome !== "failed") ||
-        !isBoundedText(result.summary, ROLE_CALL_RESULT_MAX_LENGTH)) {
+        !isBoundedText(result.summary, ROLE_CALL_RESULT_MAX_LENGTH) ||
+        !isRoleCallResultReceiptValidForStoredResult({
+            receipt: result.receipt,
+            producer: child,
+            result,
+            policy,
+            state,
+        })) {
         throw new Error("role_completed_child_projection_invalid");
     }
+    const workLineage = projectCompletedChildWorkLineage(state, result.receipt);
     return Object.freeze({
         callerCallId: refs.callerCallId,
         childCallId: child.callId,
@@ -76,8 +86,18 @@ function projectCompletedChild(state, refs) {
         dependencyResultRefs: child.dependencyResultRefs,
         outcome: result.outcome,
         summary: result.summary,
+        ...(result.receipt ? { receipt: result.receipt } : {}),
+        ...(workLineage ? { workLineage } : {}),
     });
 }
+function projectCompletedChildWorkLineage(state, receipt) {
+    if (receipt?.kind !== "work_result_v1")
+        return undefined;
+    const lineage = projectRoleCallWorkResultLineage({ state, receipt });
+    if (!lineage)
+        throw new Error("role_completed_child_projection_invalid");
+    return lineage;
+}
 function isBoundedText(value, maximumLength) {
     return (typeof value === "string" &&
         value.trim().length > 0 &&

package/dist/src/runtime/orchestration/role-calls/command-decoder.js

@@ -1,7 +1,10 @@
 import { isRuntimeDelegateRoleId, RUNTIME_ROOT_ROLE_ID } from "../roles.js";
 import { normalizeRoleCapabilitySelectionProjection } from "./capability-selection-reconsideration.js";
+import { isRoleOperationFingerprint, isRoleOperationOutcomeFingerprintForOutcome, } from "./operation-supervision.js";
+import { isReconsiderationCauseBoundToInvocationCount, normalizeRoleCapabilitySelectionReconsiderationCause, } from "./reconsideration-cause.js";
 import { isRoleCapabilityId, } from "./contracts.js";
 import { parseRoleCallPlanBinding } from "./plan.js";
+import { normalizeRoleCallResultReceipt } from "./result-receipt.js";
 import { parseRoleCallWorkerCapabilityScope } from "./worker-capability-scope.js";
 import { isRoleCallWorkingDirectoryRoleId, normalizeEstablishedRoleCallWorkingDirectory, normalizeRoleCallWorkingDirectory, } from "./working-directory.js";
 import { exactKeys, isRecord, isRoleCapabilityDeclaredEffect, isRoleCapabilityObservedEffect, isUniqueStringArray, parseCapabilityResultReferences, parseOptionalCapabilityAdapterResult, } from "./reducer-primitives.js";
@@ -88,7 +91,8 @@ export function decodeRoleCallCommand(input) {
                 }
                 : { ok: false, code: "invalid_command" };
         }
-        case "return_child":
+        case "return_child": {
+            const receipt = normalizeRoleCallResultReceipt(input.receipt);
             return exactKeys(input, [
                 "authority",
                 "type",
@@ -96,12 +100,13 @@ export function decodeRoleCallCommand(input) {
                 "childCallId",
                 "outcome",
                 "summary",
-            ]) &&
+            ], ["receipt"]) &&
                 input.authority === "runtime" &&
                 typeof input.callerCallId === "string" &&
                 typeof input.childCallId === "string" &&
                 (input.outcome === "completed" || input.outcome === "failed") &&
-                typeof input.summary === "string"
+                typeof input.summary === "string" &&
+                receipt !== null
                 ? {
                     ok: true,
                     value: {
@@ -111,9 +116,11 @@ export function decodeRoleCallCommand(input) {
                         childCallId: input.childCallId,
                         outcome: input.outcome,
                         summary: input.summary,
+                        ...(receipt ? { receipt } : {}),
                     },
                 }
                 : { ok: false, code: "invalid_command" };
+        }
         case "begin_capability_execution":
             return exactKeys(input, [
                 "authority",
@@ -124,12 +131,13 @@ export function decodeRoleCallCommand(input) {
                 "declaredEffect",
                 "intent",
                 "controlsJson",
-            ]) &&
+            ], ["actionFingerprint"]) &&
                 input.authority === "active_role" &&
                 typeof input.callId === "string" &&
                 Number.isInteger(input.invocationAttempt) &&
                 typeof input.capabilityId === "string" &&
                 isRoleCapabilityDeclaredEffect(input.declaredEffect) &&
+                isEligibleActionFingerprintInput(input) &&
                 typeof input.intent === "string" &&
                 typeof input.controlsJson === "string"
                 ? {
@@ -143,6 +151,9 @@ export function decodeRoleCallCommand(input) {
                         declaredEffect: input.declaredEffect,
                         intent: input.intent,
                         controlsJson: input.controlsJson,
+                        ...(typeof input.actionFingerprint === "string"
+                            ? { actionFingerprint: input.actionFingerprint }
+                            : {}),
                     },
                 }
                 : { ok: false, code: "invalid_command" };
@@ -158,11 +169,13 @@ export function decodeRoleCallCommand(input) {
                 "observedEffect",
                 "summary",
                 "exactResult",
-            ], ["referenceData", "references"]) &&
+            ], ["outcomeFingerprint", "referenceData", "references"]) &&
                 input.authority === "runtime" &&
                 typeof input.callId === "string" &&
                 typeof input.executionId === "string" &&
                 (input.outcome === "succeeded" || input.outcome === "failed") &&
+                (input.outcomeFingerprint === undefined ||
+                    isRoleOperationOutcomeFingerprintForOutcome(input.outcomeFingerprint, input.outcome)) &&
                 isRoleCapabilityObservedEffect(input.observedEffect) &&
                 typeof input.summary === "string" &&
                 (input.referenceData === undefined ||
@@ -178,6 +191,9 @@ export function decodeRoleCallCommand(input) {
                         callId: input.callId,
                         executionId: input.executionId,
                         outcome: input.outcome,
+                        ...(typeof input.outcomeFingerprint === "string"
+                            ? { outcomeFingerprint: input.outcomeFingerprint }
+                            : {}),
                         observedEffect: input.observedEffect,
                         summary: input.summary,
                         ...(typeof input.referenceData === "string"
@@ -288,6 +304,7 @@ export function decodeRoleCallCommand(input) {
         }
         case "reconsider_capability_selection": {
             const selection = normalizeRoleCapabilitySelectionProjection(input.selection);
+            const cause = normalizeRoleCapabilitySelectionReconsiderationCause(input.cause);
             return exactKeys(input, [
                 "authority",
                 "type",
@@ -295,13 +312,16 @@ export function decodeRoleCallCommand(input) {
                 "invocationAttempt",
                 "steeringVersion",
                 "selection",
+                "cause",
             ]) &&
                 input.authority === "active_role" &&
                 typeof input.callId === "string" &&
                 Number.isInteger(input.invocationAttempt) &&
                 Number.isSafeInteger(input.steeringVersion) &&
                 input.steeringVersion >= 0 &&
-                selection
+                selection &&
+                cause &&
+                isReconsiderationCauseBoundToInvocationCount(cause, selection.invocations.length)
                 ? {
                     ok: true,
                     value: {
@@ -311,6 +331,7 @@ export function decodeRoleCallCommand(input) {
                         invocationAttempt: input.invocationAttempt,
                         steeringVersion: input.steeringVersion,
                         selection,
+                        cause,
                     },
                 }
                 : { ok: false, code: "invalid_command" };
@@ -319,19 +340,20 @@ export function decodeRoleCallCommand(input) {
             return { ok: false, code: "invalid_command" };
     }
 }
+function isEligibleActionFingerprintInput(input) {
+    return (input.actionFingerprint === undefined ||
+        isRoleOperationFingerprint(input.actionFingerprint));
+}
 function parseObservationBatchEntries(input) {
     if (!Array.isArray(input) || input.length < 2)
         return undefined;
     const entries = input.map((entry) => {
         if (!isRecord(entry) ||
-            !exactKeys(entry, [
-                "capabilityId",
-                "declaredEffect",
-                "intent",
-                "controlsJson",
-            ]) ||
+            !exactKeys(entry, ["capabilityId", "declaredEffect", "intent", "controlsJson"], ["actionFingerprint"]) ||
             !isRoleCapabilityId(entry.capabilityId) ||
             entry.declaredEffect !== "observation" ||
+            (entry.actionFingerprint !== undefined &&
+                !isRoleOperationFingerprint(entry.actionFingerprint)) ||
             typeof entry.intent !== "string" ||
             typeof entry.controlsJson !== "string") {
             return undefined;
@@ -341,6 +363,9 @@ function parseObservationBatchEntries(input) {
             declaredEffect: "observation",
             intent: entry.intent,
             controlsJson: entry.controlsJson,
+            ...(typeof entry.actionFingerprint === "string"
+                ? { actionFingerprint: entry.actionFingerprint }
+                : {}),
         });
     });
     return entries.some((entry) => entry === undefined)
@@ -356,11 +381,13 @@ function parseCapabilityBatchSettlements(input) {
             ? parseOptionalCapabilityAdapterResult(entry.exactResult)
             : null;
         if (!isRecord(entry) ||
-            !exactKeys(entry, ["executionId", "outcome", "observedEffect", "summary", "exactResult"], ["referenceData", "references"]) ||
+            !exactKeys(entry, ["executionId", "outcome", "observedEffect", "summary", "exactResult"], ["outcomeFingerprint", "referenceData", "references"]) ||
             typeof entry.executionId !== "string" ||
             entry.executionId.length === 0 ||
             seen.has(entry.executionId) ||
             (entry.outcome !== "succeeded" && entry.outcome !== "failed") ||
+            (entry.outcomeFingerprint !== undefined &&
+                !isRoleOperationOutcomeFingerprintForOutcome(entry.outcomeFingerprint, entry.outcome)) ||
             !isRoleCapabilityObservedEffect(entry.observedEffect) ||
             typeof entry.summary !== "string" ||
             (entry.referenceData !== undefined &&
@@ -375,6 +402,9 @@ function parseCapabilityBatchSettlements(input) {
         return Object.freeze({
             executionId: entry.executionId,
             outcome: entry.outcome,
+            ...(typeof entry.outcomeFingerprint === "string"
+                ? { outcomeFingerprint: entry.outcomeFingerprint }
+                : {}),
             observedEffect: entry.observedEffect,
             summary: entry.summary,
             ...(typeof entry.referenceData === "string"

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

@@ -0,0 +1,6 @@
+import type { RoleCallFrame, RoleCallPolicy, RoleCallState } from "../contracts.js";
+export declare function findActiveCapabilityCaller(params: {
+    state: RoleCallState;
+    policy: RoleCallPolicy;
+    callId: string;
+}): RoleCallFrame | undefined;

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

@@ -0,0 +1,15 @@
+import { hasCapabilityAuthority } from "../candidate-validation.js";
+import { findCall } from "../reducer-primitives.js";
+export function findActiveCapabilityCaller(params) {
+    if (params.state.phase !== "running")
+        return undefined;
+    if (params.state.activeCallId !== params.callId)
+        return undefined;
+    const call = findCall(params.state, params.callId);
+    if (call?.status !== "active")
+        return undefined;
+    if (!hasCapabilityAuthority(params.policy.authority, params.state, call)) {
+        return undefined;
+    }
+    return call;
+}

package/dist/src/runtime/orchestration/role-calls/command-dispatch/call-frame-state.d.ts

@@ -0,0 +1,3 @@
+import type { RoleCallFrame, RoleCallState } from "../contracts.js";
+export declare function replaceCall(calls: readonly RoleCallFrame[], replacement: RoleCallFrame): RoleCallFrame[];
+export declare function nextCallId(state: RoleCallState): string;

package/dist/src/runtime/orchestration/role-calls/command-dispatch/call-frame-state.js

@@ -0,0 +1,6 @@
+export function replaceCall(calls, replacement) {
+    return calls.map((call) => call.callId === replacement.callId ? replacement : call);
+}
+export function nextCallId(state) {
+    return `call-${state.callSequence + 1}`;
+}

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

@@ -0,0 +1,3 @@
+import type { EstablishRoleCallWorkingDirectoryCommand, RoleCallPolicy, RoleCallState, RoleCallTransitionResult, UpdateRoleCapabilityScopeCommand } from "../contracts.js";
+export declare function establishWorkingDirectory(state: RoleCallState, command: EstablishRoleCallWorkingDirectoryCommand, policy: RoleCallPolicy): RoleCallTransitionResult;
+export declare function updateCapabilityScope(state: RoleCallState, command: UpdateRoleCapabilityScopeCommand, policy: RoleCallPolicy): RoleCallTransitionResult;