@abot-ai/runtime 1.1.0 → 1.3.0

package/dist/src/runtime/orchestration/role-calls/candidate-validation.js

@@ -1,13 +1,15 @@
 import { isRuntimeDelegateRoleId, RUNTIME_ROOT_ROLE_ID, RUNTIME_ROLE_IDS, } from "../roles.js";
 import { createRoleCapabilitySelectionFingerprint, normalizeRoleCapabilitySelectionProjection, } from "./capability-selection-reconsideration.js";
-import { createRoleCapabilitySelectionSupervisionFingerprint, isRoleCapabilitySelectionSupervisionState, } from "./capability-selection-supervision.js";
-import { isIssuedRoleCapabilitySelectionSupervisionState } from "./capability-selection-supervision-issuance.js";
+import { isRoleCapabilitySelectionSupervisionState, } from "./capability-selection-supervision.js";
+import { isValidRoleCapabilitySelectionSupervision } from "./capability-selection-supervision-validation.js";
+import { validateRoleMemoryRecalls } from "./memory-recall-state-validation.js";
 import { isRoleOperationFingerprint, isRoleOperationOutcomeFingerprintForOutcome, isSameRoleOperationIdentity, replayRoleOperationSupervisionEvidence, } from "./operation-supervision.js";
 import { isIssuedRoleOperationSupervisionInterventionForRequest } from "./operation-supervision-issuance.js";
 import { isRoleOperationSupervisionSettlementHistoryValid, isRoleOperationSupervisionState, } from "./operation-supervision-state-validation.js";
 import { isReconsiderationCauseBoundToInvocationCount } from "./reconsideration-cause.js";
 import { isRoleCapabilityId, ROLE_CAPABILITY_EXECUTION_LIMIT_MAX, ROLE_CAPABILITY_INVOCATION_INTENT_MAX_LENGTH, ROLE_CAPABILITY_REFERENCE_DATA_MAX_LENGTH, ROLE_CALL_LEDGER_CONTRACT_VERSION, } from "./contracts.js";
 import { validateRoleCallPlans } from "./plan.js";
+import { isRoleCallResultReceiptValidForStoredResult } from "./result-receipt.js";
 import { findRoleActivationBudgetIssue } from "./activation-budget.js";
 import { isRoleCallWorkerCapabilityScope } from "./worker-capability-scope.js";
 import { isRoleCallWorkingDirectoryRoleId, normalizeEstablishedRoleCallWorkingDirectory, normalizeRoleCallWorkingDirectory, } from "./working-directory.js";
@@ -43,6 +45,7 @@ export function validateRoleCallState(state, policy) {
         !Array.isArray(state?.results) ||
         !Array.isArray(state?.plans) ||
         !Array.isArray(state?.capabilityExecutions) ||
+        !Array.isArray(state?.memoryRecalls) ||
         !isRoleOperationSupervisionState(state?.operationSupervision) ||
         !isRoleCapabilitySelectionSupervisionState(state?.capabilitySelectionSupervision) ||
         !Number.isInteger(state?.callSequence) ||
@@ -66,7 +69,7 @@ export function validateRoleCallState(state, policy) {
     const root = state.rootCallId
         ? state.calls.find((call) => call.callId === state.rootCallId)
         : undefined;
-    const turnOwnerCalls = state.calls.filter((call) => call.status === "active" || call.status === "waiting_for_capability");
+    const turnOwnerCalls = state.calls.filter((call) => call.status === "active" || call.status === "waiting_for_capability" || call.status === "waiting_for_memory");
     if (state.phase === "empty") {
         if (state.rootCallId !== null ||
             state.activeCallId !== null ||
@@ -74,6 +77,7 @@ export function validateRoleCallState(state, policy) {
             state.results.length > 0 ||
             state.plans.length > 0 ||
             state.capabilityExecutions.length > 0 ||
+            state.memoryRecalls.length > 0 ||
             state.operationSupervision.entries.length > 0 ||
             state.operationSupervision.interventions.length > 0 ||
             state.capabilitySelectionSupervision.epoch !== null ||
@@ -112,6 +116,7 @@ export function validateRoleCallState(state, policy) {
                 "active",
                 "waiting_for_child",
                 "waiting_for_capability",
+                "waiting_for_memory",
                 "completed",
             ].includes(call.status) ||
             !Number.isInteger(call.depth) ||
@@ -157,16 +162,23 @@ export function validateRoleCallState(state, policy) {
             producer.status !== "completed" ||
             producer.roleId !== result.roleId ||
             (result.outcome !== "completed" && result.outcome !== "failed") ||
-            !isBoundedText(result.summary, policy.limits.maxResultChars)) {
+            !isBoundedText(result.summary, policy.limits.maxResultChars) ||
+            !isRoleCallResultReceiptValidForStoredResult({
+                receipt: result.receipt,
+                producer,
+                result,
+                policy, state,
+            })) {
             issues.push(issue("invalid_role_call_result_owner", `state.results.${result.resultRef}`));
         }
     }
     issues.push(...validateRoleCallPlans(state, policy));
     validateCapabilityExecutions(state, policy, issues);
+    issues.push(...validateRoleMemoryRecalls(state));
     if (!isValidRoleOperationSupervision(state, policy)) {
         issues.push(issue("invalid_role_operation_supervision", "state.operationSupervision"));
     }
-    if (!isValidRoleCapabilitySelectionSupervision(state, policy)) {
+    if (!isValidRoleCapabilitySelectionSupervision(state, policy, hasCapabilityAuthority)) {
         issues.push(issue("invalid_role_capability_selection_supervision", "state.capabilitySelectionSupervision"));
     }
     const activationBudgetIssue = findRoleActivationBudgetIssue(state, policy);
@@ -174,51 +186,6 @@ export function validateRoleCallState(state, policy) {
         issues.push(activationBudgetIssue);
     return issues;
 }
-function isValidRoleCapabilitySelectionSupervision(state, policy) {
-    const supervision = state.capabilitySelectionSupervision;
-    if (!isRoleCapabilitySelectionSupervisionState(supervision))
-        return false;
-    if (supervision.epoch === null)
-        return supervision.records.length === 0;
-    if (!isIssuedRoleCapabilitySelectionSupervisionState({ state }))
-        return false;
-    if (state.phase !== "running" || supervision.records.length < 1) {
-        return false;
-    }
-    const call = findCall(state, supervision.epoch.callId);
-    const lastRecord = supervision.records.at(-1);
-    const reconsideration = call?.lastCapabilitySelectionReconsideration;
-    let expectedSupervisionFingerprint;
-    if (reconsideration) {
-        try {
-            expectedSupervisionFingerprint =
-                createRoleCapabilitySelectionSupervisionFingerprint({
-                    steeringVersion: reconsideration.steeringVersion,
-                    selection: reconsideration.selection,
-                });
-        }
-        catch {
-            return false;
-        }
-    }
-    if (!hasCapabilityAuthority(policy.authority, state, call) ||
-        state.activeCallId !== call.callId ||
-        call.status !== "active" ||
-        !lastRecord ||
-        !reconsideration ||
-        supervision.epoch.steeringVersion !== reconsideration.steeringVersion ||
-        lastRecord.invocationAttempt !== reconsideration.invocationAttempt ||
-        lastRecord.receiptFingerprint !== reconsideration.fingerprint ||
-        lastRecord.supervisionFingerprint !== expectedSupervisionFingerprint ||
-        call.activationCount !== lastRecord.invocationAttempt + 1) {
-        return false;
-    }
-    return supervision.records.every((record, index, records) => {
-        const previous = records[index - 1];
-        return (record.invocationAttempt < call.activationCount &&
-            (!previous || record.invocationAttempt === previous.invocationAttempt + 1));
-    });
-}
 function isValidCapabilitySelectionReconsideration(call, policy, state) {
     const reconsideration = call.lastCapabilitySelectionReconsideration;
     if (reconsideration === undefined)

package/dist/src/runtime/orchestration/role-calls/capability-selection-reconsideration.d.ts

@@ -23,3 +23,12 @@ export declare function isImmediateRoleCapabilitySelectionReconsideration(input:
     };
     steeringVersion: number;
 };
+export declare function isRoleCapabilityReconsiderationBoundToScope(input: {
+    call: RoleCallFrame;
+    steeringVersion: number;
+}): input is {
+    call: RoleCallFrame & {
+        lastCapabilitySelectionReconsideration: RoleCapabilitySelectionReconsideration;
+    };
+    steeringVersion: number;
+};

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

@@ -96,16 +96,25 @@ export function createRoleCapabilitySelectionFingerprint(input) {
     return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
 }
 export function isImmediateRoleCapabilitySelectionReconsideration(input) {
+    if (!isRoleCapabilityReconsiderationBoundToScope(input))
+        return false;
+    return (input.call.activationCount ===
+        input.call.lastCapabilitySelectionReconsideration.invocationAttempt + 1);
+}
+export function isRoleCapabilityReconsiderationBoundToScope(input) {
     const reconsideration = input.call.lastCapabilitySelectionReconsideration;
+    if (!reconsideration)
+        return false;
+    if (input.steeringVersion !== reconsideration.steeringVersion)
+        return false;
     const activeScope = input.call.workerCapabilityScope?.catalogGroupIds;
-    return (reconsideration !== undefined &&
-        input.call.activationCount === reconsideration.invocationAttempt + 1 &&
-        input.steeringVersion === reconsideration.steeringVersion &&
-        activeScope !== undefined &&
-        sameStringArray(activeScope, reconsideration.selection.activeCapabilityCatalogGroupIds) &&
-        (input.call.workingDirectory === undefined ||
-            input.call.workingDirectory ===
-                reconsideration.selection.workingDirectory));
+    if (activeScope === undefined)
+        return false;
+    if (!sameStringArray(activeScope, reconsideration.selection.activeCapabilityCatalogGroupIds))
+        return false;
+    if (input.call.workingDirectory === undefined)
+        return true;
+    return (input.call.workingDirectory === reconsideration.selection.workingDirectory);
 }
 function canonicalizeControls(input) {
     const canonical = canonicalizeJsonValue(input);

package/dist/src/runtime/orchestration/role-calls/capability-selection-supervision-validation.d.ts

@@ -0,0 +1,2 @@
+import type { ExecutionPolicyAuthoritySnapshot, RoleCallFrame, RoleCallPolicy, RoleCallState } from "./contracts.js";
+export declare function isValidRoleCapabilitySelectionSupervision(state: RoleCallState, policy: RoleCallPolicy, hasCapabilityAuthority: (authority: ExecutionPolicyAuthoritySnapshot, state: RoleCallState, call: RoleCallFrame | undefined) => call is RoleCallFrame): boolean;

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

@@ -0,0 +1,62 @@
+import { createRoleCapabilitySelectionSupervisionFingerprint, isRoleCapabilitySelectionSupervisionState, } from "./capability-selection-supervision.js";
+import { isIssuedRoleCapabilitySelectionSupervisionState } from "./capability-selection-supervision-issuance.js";
+import { hasSettledMemoryRecallActivationRange } from "./memory-recall-state-validation.js";
+import { findCall } from "./reducer-primitives.js";
+export function isValidRoleCapabilitySelectionSupervision(state, policy, hasCapabilityAuthority) {
+    const supervision = state.capabilitySelectionSupervision;
+    if (!isRoleCapabilitySelectionSupervisionState(supervision))
+        return false;
+    if (supervision.epoch === null)
+        return supervision.records.length === 0;
+    if (!isIssuedRoleCapabilitySelectionSupervisionState({ state }))
+        return false;
+    if (state.phase !== "running" || supervision.records.length < 1)
+        return false;
+    const call = findCall(state, supervision.epoch.callId);
+    if (!hasCapabilityAuthority(policy.authority, state, call))
+        return false;
+    if (state.activeCallId !== call.callId)
+        return false;
+    if (!isSelectionSupervisionTurnOwner(call))
+        return false;
+    const lastRecord = supervision.records.at(-1);
+    const reconsideration = call.lastCapabilitySelectionReconsideration;
+    if (!lastRecord || !reconsideration)
+        return false;
+    if (supervision.epoch.steeringVersion !== reconsideration.steeringVersion)
+        return false;
+    if (!isSelectionReceiptBoundToLatestRecord(call, lastRecord))
+        return false;
+    if (!hasSettledMemoryRecallActivationRange(state, call.callId, lastRecord.invocationAttempt + 1, call.activationCount))
+        return false;
+    return supervision.records.every((record, index, records) => hasContiguousSupervisionActivation(state, call, record, records[index - 1]));
+}
+function isSelectionSupervisionTurnOwner(call) {
+    return call.status === "active" || call.status === "waiting_for_memory";
+}
+function isSelectionReceiptBoundToLatestRecord(call, lastRecord) {
+    const reconsideration = call.lastCapabilitySelectionReconsideration;
+    if (!reconsideration)
+        return false;
+    if (lastRecord.invocationAttempt !== reconsideration.invocationAttempt)
+        return false;
+    if (lastRecord.receiptFingerprint !== reconsideration.fingerprint)
+        return false;
+    try {
+        const fingerprint = createRoleCapabilitySelectionSupervisionFingerprint({
+            steeringVersion: reconsideration.steeringVersion,
+            selection: reconsideration.selection,
+        });
+        return lastRecord.supervisionFingerprint === fingerprint;
+    }
+    catch {
+        return false;
+    }
+}
+function hasContiguousSupervisionActivation(state, call, record, previous) {
+    if (record.invocationAttempt >= call.activationCount)
+        return false;
+    if (!previous)
+        return true;
+    return hasSettledMemoryRecallActivationRange(state, call.callId, previous.invocationAttempt + 1, record.invocationAttempt);
+}

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

@@ -4,6 +4,8 @@ import { isRoleOperationFingerprint, isRoleOperationOutcomeFingerprintForOutcome
 import { isReconsiderationCauseBoundToInvocationCount, normalizeRoleCapabilitySelectionReconsiderationCause, } from "./reconsideration-cause.js";
 import { isRoleCapabilityId, } from "./contracts.js";
 import { parseRoleCallPlanBinding } from "./plan.js";
+import { normalizeRoleCallResultReceipt } from "./result-receipt.js";
+import { decodeMemoryRecallCommand } from "./memory-recall-decoder.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";
@@ -12,6 +14,9 @@ export function decodeRoleCallCommand(input) {
         return { ok: false, code: "invalid_command" };
     }
     switch (input.type) {
+        case "begin_memory_recall":
+        case "settle_memory_recall":
+            return decodeMemoryRecallCommand(input);
         case "create_root":
             return exactKeys(input, ["authority", "type"]) &&
                 input.authority === "runtime"
@@ -90,7 +95,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",
@@ -98,12 +104,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: {
@@ -113,9 +120,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",

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

@@ -1,3 +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): RoleCallTransitionResult;
+export declare function returnChild(state: RoleCallState, command: ReturnChildRoleCallCommand, policy: RoleCallPolicy, admittedHeadRevision?: number): RoleCallTransitionResult;

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

@@ -3,6 +3,7 @@ import { resetRoleCapabilitySelectionSupervisionState } from "../capability-sele
 import { bindRoleCallPlanChild, plannerPlanHasOpenItems, settleRoleCallPlanChild, } from "../plan.js";
 import { areOwnedDependencyResults, commit, findCall, isBoundedText, reject, } from "../reducer-primitives.js";
 import { isRoleCallWorkingDirectoryRoleId } from "../working-directory.js";
+import { resolveCanonicalResultReceiptForReturn } from "../return-result-receipt.js";
 import { nextCallId, replaceCall } from "./call-frame-state.js";
 export function openChild(state, command, policy) {
     const { callerCallId, objective, workerCapabilityScope, workingDirectory, dependencyResultRefs = [], plannerPlan, } = command;
@@ -91,8 +92,8 @@ export function openChild(state, command, policy) {
             : {}),
     });
 }
-export function returnChild(state, command, policy) {
-    const { callerCallId, childCallId, outcome, summary } = command;
+export function returnChild(state, command, policy, admittedHeadRevision) {
+    const { callerCallId, childCallId, outcome, summary, receipt } = command;
     if (state.phase === "empty") {
         return reject(state, "root_missing");
     }
@@ -105,12 +106,26 @@ export function returnChild(state, command, policy) {
         return reject(state, "invalid_command");
     }
     const resultRef = nextResultRef(state);
+    const receiptResolution = resolveCanonicalResultReceiptForReturn({
+        state,
+        caller,
+        child,
+        resultRef,
+        outcome,
+        policy,
+        admittedHeadRevision,
+        ...(receipt ? { suppliedReceipt: receipt } : {}),
+    });
+    if (!receiptResolution.ok)
+        return reject(state, "invalid_command");
     const result = {
         resultRef,
         producerCallId: childCallId,
         roleId: child.roleId,
         outcome,
         summary: summary.trim(),
+        ...(receiptResolution.receipt
+            ? { receipt: receiptResolution.receipt } : {}),
     };
     if (hasIncompleteCompletedPlannerPlan(state, child, outcome)) {
         return reject(state, "planner_plan_incomplete");

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

@@ -0,0 +1,4 @@
+import type { RoleCallState, RoleCallTransitionResult } from "../contracts.js";
+import type { BeginRoleMemoryRecallCommand, SettleRoleMemoryRecallCommand } from "../memory-recall-contract.js";
+export declare function beginMemoryRecall(state: RoleCallState, command: BeginRoleMemoryRecallCommand): RoleCallTransitionResult;
+export declare function settleMemoryRecall(state: RoleCallState, command: SettleRoleMemoryRecallCommand): RoleCallTransitionResult;

package/dist/src/runtime/orchestration/role-calls/command-dispatch/memory-recall-transitions.js

@@ -0,0 +1,89 @@
+import { RUNTIME_ROOT_ROLE_ID } from "../../roles.js";
+import { commit, reject } from "../reducer-primitives.js";
+import { replaceCall } from "./call-frame-state.js";
+export function beginMemoryRecall(state, command) {
+    const call = findMemoryRecallRoot(state, command.callId);
+    if (!call || call.status !== "active")
+        return reject(state, "memory_recall_caller_invalid");
+    if (call.activationCount !== command.invocationAttempt)
+        return reject(state, "memory_recall_invocation_mismatch");
+    const previous = state.memoryRecalls.at(-1);
+    if (previous && command.steeringVersion < previous.steeringVersion)
+        return reject(state, "memory_recall_invocation_mismatch");
+    const recall = {
+        recallId: `recall-${state.memoryRecalls.length + 1}`,
+        completedChildCount: call.childCallIds.length,
+        callId: call.callId,
+        invocationAttempt: command.invocationAttempt,
+        steeringVersion: command.steeringVersion,
+        query: command.query,
+        status: "pending",
+    };
+    return commit({
+        ...state,
+        calls: replaceCall(state.calls, {
+            ...call,
+            status: "waiting_for_memory",
+        }),
+        memoryRecalls: [...state.memoryRecalls, recall],
+    }, {
+        type: "memory_recall_begun",
+        callId: call.callId,
+        recallId: recall.recallId,
+        invocationAttempt: recall.invocationAttempt,
+        steeringVersion: recall.steeringVersion,
+    });
+}
+export function settleMemoryRecall(state, command) {
+    const call = findMemoryRecallRoot(state, command.callId);
+    if (!call || call.status !== "waiting_for_memory")
+        return reject(state, "memory_recall_caller_invalid");
+    const pending = state.memoryRecalls.at(-1);
+    if (!matchesPendingMemoryRecall(pending, call, command))
+        return reject(state, "memory_recall_settlement_mismatch");
+    const settled = {
+        ...pending,
+        status: "settled",
+        result: command.result,
+    };
+    return commit({
+        ...state,
+        calls: replaceCall(state.calls, {
+            ...call,
+            status: "active",
+            activationCount: call.activationCount + 1,
+        }),
+        memoryRecalls: [...state.memoryRecalls.slice(0, -1), settled],
+    }, {
+        type: "memory_recall_settled",
+        callId: call.callId,
+        recallId: settled.recallId,
+        invocationAttempt: settled.invocationAttempt,
+        steeringVersion: settled.steeringVersion,
+    });
+}
+function findMemoryRecallRoot(state, callId) {
+    if (state.phase !== "running")
+        return undefined;
+    if (state.rootCallId !== callId || state.activeCallId !== callId)
+        return undefined;
+    const call = state.calls.find((candidate) => candidate.callId === callId);
+    if (call?.parentCallId !== null)
+        return undefined;
+    if (call.roleId !== RUNTIME_ROOT_ROLE_ID)
+        return undefined;
+    return call;
+}
+function matchesPendingMemoryRecall(pending, call, command) {
+    if (pending?.status !== "pending")
+        return false;
+    if (pending.recallId !== command.recallId)
+        return false;
+    if (pending.callId !== command.callId)
+        return false;
+    if (pending.invocationAttempt !== command.invocationAttempt)
+        return false;
+    if (call.activationCount !== command.invocationAttempt)
+        return false;
+    return pending.steeringVersion === command.steeringVersion;
+}

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

@@ -1,2 +1,2 @@
 import type { RoleCallLedgerCommand, RoleCallPolicy, RoleCallState, RoleCallTransitionResult } from "./contracts.js";
-export declare function dispatchRoleCallCommand(state: RoleCallState, command: RoleCallLedgerCommand, policy: RoleCallPolicy): RoleCallTransitionResult;
+export declare function dispatchRoleCallCommand(state: RoleCallState, command: RoleCallLedgerCommand, policy: RoleCallPolicy, admittedHeadRevision?: number): RoleCallTransitionResult;

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

@@ -1,11 +1,16 @@
 import { beginCapabilityBatch, settleCapabilityBatch, } from "./command-dispatch/capability-batch-transitions.js";
 import { beginCapabilityExecution, settleCapabilityExecution, } from "./command-dispatch/capability-execution-transitions.js";
 import { reconsiderCapabilitySelection } from "./command-dispatch/capability-selection-transition.js";
+import { beginMemoryRecall, settleMemoryRecall } from "./command-dispatch/memory-recall-transitions.js";
 import { establishWorkingDirectory, updateCapabilityScope, } from "./command-dispatch/call-scope-transitions.js";
 import { openChild, returnChild, } from "./command-dispatch/child-transitions.js";
 import { completeRootResponse, createRoot, } from "./command-dispatch/root-transitions.js";
-export function dispatchRoleCallCommand(state, command, policy) {
+export function dispatchRoleCallCommand(state, command, policy, admittedHeadRevision) {
     switch (command.type) {
+        case "begin_memory_recall":
+            return beginMemoryRecall(state, command);
+        case "settle_memory_recall":
+            return settleMemoryRecall(state, command);
         case "create_root":
             return createRoot(state);
         case "complete_root_response":
@@ -13,7 +18,7 @@ export function dispatchRoleCallCommand(state, command, policy) {
         case "open_child":
             return openChild(state, command, policy);
         case "return_child":
-            return returnChild(state, command, policy);
+            return returnChild(state, command, policy, admittedHeadRevision);
         case "begin_capability_execution":
             return beginCapabilityExecution(state, command, policy);
         case "settle_capability_execution":

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

@@ -4,8 +4,10 @@ import type { RuntimeDelegateRoleId, RuntimeRoleId } from "../roles.js";
 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";
+import type { RoleCallResultReceipt } from "./result-receipt.js";
+import type { RoleMemoryRecall, RoleMemoryRecallCommand, RoleMemoryRecallCommitEffect, RoleMemoryRecallTransactions } from "./memory-recall-contract.js";
+export declare const ROLE_CALL_LEDGER_CONTRACT_VERSION = 18;
+export declare const ROLE_CALL_LEDGER_HEAD_KIND: "runtime_role_call_ledger_v18";
 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;
@@ -52,7 +54,7 @@ export type RoleCallPolicyInput = Readonly<{
     authority?: ExecutionPolicyAuthoritySnapshot;
     limits: RoleCallPolicy["limits"];
 }>;
-export type RoleCallFrameStatus = "active" | "waiting_for_child" | "waiting_for_capability" | "completed";
+export type RoleCallFrameStatus = "active" | "waiting_for_child" | "waiting_for_capability" | "waiting_for_memory" | "completed";
 export type RoleCallWorkerCapabilityScope = Readonly<{
     catalogGroupIds: readonly string[];
 }>;
@@ -95,6 +97,7 @@ export type RoleCallResult = Readonly<{
     roleId: RuntimeDelegateRoleId;
     outcome: "completed" | "failed";
     summary: string;
+    receipt?: RoleCallResultReceipt;
 }>;
 export type RoleCallPlanItemStatus = "pending" | "in_progress" | "done" | "blocked";
 export type RoleCallPlanProposal = Readonly<{
@@ -181,6 +184,7 @@ export type RoleCallState = Readonly<{
     results: readonly RoleCallResult[];
     plans: readonly RoleCallPlanState[];
     capabilityExecutions: readonly RoleCapabilityExecution[];
+    memoryRecalls: readonly RoleMemoryRecall[];
     operationSupervision: RoleOperationSupervisionState;
     capabilitySelectionSupervision: RoleCapabilitySelectionSupervisionState;
     rootResponse: string | null;
@@ -214,6 +218,7 @@ export type ReturnChildRoleCallCommand = Readonly<{
     childCallId: string;
     outcome: "completed" | "failed";
     summary: string;
+    receipt?: RoleCallResultReceipt;
 }>;
 export type BeginRoleCapabilityExecutionCommand = Readonly<{
     authority: "active_role";
@@ -293,8 +298,8 @@ export type ReconsiderRoleCapabilitySelectionCommand = Readonly<{
     selection: RoleCapabilitySelectionProjection;
     cause: RoleCapabilitySelectionReconsiderationCause;
 }>;
-export type RoleCallLedgerCommand = CreateRootRoleCallCommand | CompleteRootResponseCommand | OpenChildRoleCallCommand | ReturnChildRoleCallCommand | BeginRoleCapabilityExecutionCommand | SettleRoleCapabilityExecutionCommand | BeginRoleCapabilityBatchCommand | SettleRoleCapabilityBatchCommand | UpdateRoleCapabilityScopeCommand | EstablishRoleCallWorkingDirectoryCommand | ReconsiderRoleCapabilitySelectionCommand;
-export type RoleCallCommitEffect = Readonly<{
+export type RoleCallLedgerCommand = RoleMemoryRecallCommand | CreateRootRoleCallCommand | CompleteRootResponseCommand | OpenChildRoleCallCommand | ReturnChildRoleCallCommand | BeginRoleCapabilityExecutionCommand | SettleRoleCapabilityExecutionCommand | BeginRoleCapabilityBatchCommand | SettleRoleCapabilityBatchCommand | UpdateRoleCapabilityScopeCommand | EstablishRoleCallWorkingDirectoryCommand | ReconsiderRoleCapabilitySelectionCommand;
+export type RoleCallCommitEffect = RoleMemoryRecallCommitEffect | Readonly<{
     type: "root_created";
     callId: string;
 }> | Readonly<{
@@ -361,7 +366,7 @@ 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" | "capability_selection_supervision_limit_exceeded" | "operation_supervision_limit_exceeded" | "role_activation_limit_exceeded";
+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" | "memory_recall_caller_invalid" | "memory_recall_invocation_mismatch" | "memory_recall_settlement_mismatch" | "role_activation_limit_exceeded";
 export type RoleCallTransitionResult = Readonly<{
     ok: true;
     state: RoleCallState;
@@ -430,7 +435,7 @@ export type RoleCallTransactionFailure<TTransitionIssueCode extends string> = Re
     commit: RoleCallLedgerCommitResult;
 }>;
 export type RoleCallTransactionResult<TEffectType extends RoleCallCommitEffect["type"], TTransitionIssueCode extends string> = RoleCallTransactionSuccess<TEffectType> | RoleCallTransactionFailure<TTransitionIssueCode>;
-export type RoleCallTransactions = Readonly<{
+export type RoleCallTransactions = RoleMemoryRecallTransactions & Readonly<{
     createRoot(input: Readonly<{
         expectedHead: unknown;
     }>): Promise<RoleCallTransactionResult<"root_created", "root_create_transition_invalid">>;