@abot-ai/runtime 1.1.0 → 1.3.0

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

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

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

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

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

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

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

@@ -1,6 +1,7 @@
 import { traceDebug } from "../../observability/debug-logger.js";
 import { resolveRoleActivationBudget } from "./activation-budget.js";
 import { isSuccessfulObservedMutation } from "./operation-supervision.js";
+import { traceMemoryRecallCommit } from "./memory-recall-diagnostics.js";
 const ROLE_CALL_LOG_SCOPE = "runtime.role_calls";
 export function traceRoleCallCommit(params) {
     const state = params.head.state;
@@ -25,6 +26,8 @@ export function traceRoleCallCommit(params) {
         effectType: params.effect.type,
     });
     traceCapabilitySelectionSupervisionReset(params, common);
+    if (traceMemoryRecallCommit(params, common))
+        return;
     switch (params.effect.type) {
         case "root_created": {
             traceDebug(ROLE_CALL_LOG_SCOPE, "root.created", {

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

@@ -6,12 +6,17 @@ export * from "./operation-supervision-state-validation.js";
 export * from "./capability-selection-reconsideration.js";
 export * from "./capability-selection-supervision.js";
 export * from "./reconsideration-cause.js";
+export * from "./result-receipt.js";
+export * from "./return-result-receipt.js";
+export * from "./work-result-lineage.js";
+export * from "./work-result-receipt.js";
 export * from "./assignment-scope.js";
 export * from "./child-return.js";
 export * from "./dependency-results.js";
-export * from "./ledger.js";
+export { createRoleCallLedger } from "./ledger.js";
 export * from "./plan.js";
 export * from "./reducer.js";
 export * from "./transactions.js";
 export * from "./worker-capability-scope.js";
 export * from "./working-directory.js";
+export * from "./memory-recall-contract.js";

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

@@ -6,12 +6,17 @@ export * from "./operation-supervision-state-validation.js";
 export * from "./capability-selection-reconsideration.js";
 export * from "./capability-selection-supervision.js";
 export * from "./reconsideration-cause.js";
+export * from "./result-receipt.js";
+export * from "./return-result-receipt.js";
+export * from "./work-result-lineage.js";
+export * from "./work-result-receipt.js";
 export * from "./assignment-scope.js";
 export * from "./child-return.js";
 export * from "./dependency-results.js";
-export * from "./ledger.js";
+export { createRoleCallLedger } from "./ledger.js";
 export * from "./plan.js";
 export * from "./reducer.js";
 export * from "./transactions.js";
 export * from "./worker-capability-scope.js";
 export * from "./working-directory.js";
+export * from "./memory-recall-contract.js";

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

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

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

@@ -10,6 +10,7 @@ import { isIssuedRoleCapabilitySelectionSupervisionState, issueCanonicalRoleCapa
 import { applyRoleCallCommand, createInitialRoleCallState, sealRoleCallPolicy, validateRoleCallCandidate, } from "./reducer.js";
 import { createRoleCallTransactions } from "./transactions.js";
 import { ROLE_CALL_WORKING_DIRECTORY_MAX_LENGTH } from "./working-directory.js";
+const issuedRoleCallLedgerHeads = new WeakMap();
 export function createRoleCallLedger(params) {
     const initialState = createInitialRoleCallState(params.requestId);
     const capabilitySelectionSupervisionIssuanceAuthority = resolveRoleCapabilitySelectionSupervisionIssuanceAuthority(initialState);
@@ -40,7 +41,7 @@ export function createRoleCallLedger(params) {
             expectedHead: input.expectedHead,
             run(transaction) {
                 const admittedCommand = projectAdmittedCapabilityExecutionCommand(commandType, capturedCommand, capabilityExecutionAdmission);
-                const transition = applyRoleCallCommand(transaction.head.state, admittedCommand, transaction.head.policy);
+                const transition = applyRoleCallCommand(transaction.head.state, admittedCommand, transaction.head.policy, transaction.head.revision);
                 if (!transition.ok) {
                     return {
                         kind: "transition_rejected",
@@ -129,7 +130,7 @@ export function createRoleCallLedger(params) {
         return committed;
     };
     const transactions = createRoleCallTransactions(apply);
-    return Object.freeze({
+    const ledger = Object.freeze({
         current() {
             return channel.reader.current();
         },
@@ -137,6 +138,12 @@ export function createRoleCallLedger(params) {
         transactions,
         apply,
     });
+    issuedRoleCallLedgerHeads.set(ledger, () => channel.reader.current());
+    return ledger;
+}
+/** Confirms exact current-head ownership without trusting structural ledgers. */
+export function isCurrentRoleCallLedgerHead(ledger, head) {
+    return issuedRoleCallLedgerHeads.get(ledger)?.() === head;
 }
 function createRoleCallStateHeadFactory(capabilitySelectionSupervisionIssuanceAuthority) {
     return createCanonicalStateHeadFactory({

package/dist/src/runtime/orchestration/role-calls/memory-recall-contract.d.ts

@@ -0,0 +1,51 @@
+import type { LongTermMemoryRecord } from "../../long-term-memory/contracts.js";
+import type { RoleCallTransactionInput, RoleCallTransactionResult } from "./contracts.js";
+export declare const ROLE_MEMORY_RECALL_QUERY_MAX_LENGTH = 1024;
+export declare const ROLE_MEMORY_RECALL_RECORD_LIMIT_MAX = 6;
+export declare const ROLE_MEMORY_RECALL_RESULT_MAX_LENGTH = 6000;
+export declare const ROLE_MEMORY_RECALL_REASON_MAX_LENGTH = 256;
+export type RoleMemoryRecallResult = Readonly<{
+    outcome: "found" | "empty" | "unavailable" | "superseded";
+    records: readonly LongTermMemoryRecord[];
+    omittedRecordCount: number;
+    reason?: string;
+}>;
+export type RoleMemoryRecallIdentity = Readonly<{
+    callId: string;
+    invocationAttempt: number;
+    steeringVersion: number;
+}>;
+export type RoleMemoryRecall = RoleMemoryRecallIdentity & Readonly<{
+    recallId: string;
+    completedChildCount: number;
+    query: string;
+}> & (Readonly<{
+    status: "pending";
+    result?: undefined;
+}> | Readonly<{
+    status: "settled";
+    result: RoleMemoryRecallResult;
+}>);
+export type BeginRoleMemoryRecallCommand = RoleMemoryRecallIdentity & Readonly<{
+    authority: "active_role";
+    type: "begin_memory_recall";
+    query: string;
+}>;
+export type SettleRoleMemoryRecallCommand = RoleMemoryRecallIdentity & Readonly<{
+    authority: "runtime";
+    type: "settle_memory_recall";
+    recallId: string;
+    result: RoleMemoryRecallResult;
+}>;
+export type RoleMemoryRecallCommand = BeginRoleMemoryRecallCommand | SettleRoleMemoryRecallCommand;
+export type RoleMemoryRecallCommitEffect = RoleMemoryRecallIdentity & Readonly<{
+    recallId: string;
+}> & (Readonly<{
+    type: "memory_recall_begun";
+}> | Readonly<{
+    type: "memory_recall_settled";
+}>);
+export type RoleMemoryRecallTransactions = Readonly<{
+    beginMemoryRecall(input: RoleCallTransactionInput<BeginRoleMemoryRecallCommand>): Promise<RoleCallTransactionResult<"memory_recall_begun", "memory_recall_transition_invalid">>;
+    settleMemoryRecall(input: RoleCallTransactionInput<SettleRoleMemoryRecallCommand>): Promise<RoleCallTransactionResult<"memory_recall_settled", "memory_recall_transition_invalid">>;
+}>;

package/dist/src/runtime/orchestration/role-calls/memory-recall-contract.js

@@ -0,0 +1,4 @@
+export const ROLE_MEMORY_RECALL_QUERY_MAX_LENGTH = 1_024;
+export const ROLE_MEMORY_RECALL_RECORD_LIMIT_MAX = 6;
+export const ROLE_MEMORY_RECALL_RESULT_MAX_LENGTH = 6_000;
+export const ROLE_MEMORY_RECALL_REASON_MAX_LENGTH = 256;

package/dist/src/runtime/orchestration/role-calls/memory-recall-decoder.d.ts

@@ -0,0 +1,6 @@
+import type { DecodedRoleCallCommand } from "./command-decoder.js";
+import { type RoleMemoryRecallIdentity, type RoleMemoryRecallResult } from "./memory-recall-contract.js";
+export declare function decodeMemoryRecallCommand(input: Record<string, unknown>): DecodedRoleCallCommand;
+export declare function hasMemoryRecallIdentity(input: Record<string, unknown>): input is Record<string, unknown> & RoleMemoryRecallIdentity;
+export declare function isBoundedMemoryRecallQuery(input: unknown): input is string;
+export declare function normalizeRoleMemoryRecallResult(input: unknown): RoleMemoryRecallResult | undefined;

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

@@ -0,0 +1,147 @@
+import { parseMemoryRecord } from "../../long-term-memory/repository-state.js";
+import { exactKeys, isRecord } from "../../validation/strict-record.js";
+import { ROLE_MEMORY_RECALL_QUERY_MAX_LENGTH, ROLE_MEMORY_RECALL_REASON_MAX_LENGTH, ROLE_MEMORY_RECALL_RECORD_LIMIT_MAX, ROLE_MEMORY_RECALL_RESULT_MAX_LENGTH, } from "./memory-recall-contract.js";
+export function decodeMemoryRecallCommand(input) {
+    const invalid = { ok: false, code: "invalid_command" };
+    if (!hasMemoryRecallIdentity(input))
+        return invalid;
+    if (input.type === "begin_memory_recall")
+        return decodeBeginMemoryRecall(input);
+    return decodeSettleMemoryRecall(input);
+}
+function decodeBeginMemoryRecall(input) {
+    const invalid = { ok: false, code: "invalid_command" };
+    if (input.authority !== "active_role")
+        return invalid;
+    if (!exactKeys(input, [
+        "authority",
+        "type",
+        "callId",
+        "invocationAttempt",
+        "steeringVersion",
+        "query",
+    ]))
+        return invalid;
+    if (!isBoundedMemoryRecallQuery(input.query))
+        return invalid;
+    return {
+        ok: true,
+        value: {
+            authority: "active_role",
+            type: "begin_memory_recall",
+            callId: input.callId,
+            invocationAttempt: input.invocationAttempt,
+            steeringVersion: input.steeringVersion,
+            query: input.query.trim(),
+        },
+    };
+}
+function decodeSettleMemoryRecall(input) {
+    const invalid = { ok: false, code: "invalid_command" };
+    if (input.type !== "settle_memory_recall")
+        return invalid;
+    if (input.authority !== "runtime")
+        return invalid;
+    if (!exactKeys(input, [
+        "authority",
+        "type",
+        "callId",
+        "invocationAttempt",
+        "steeringVersion",
+        "recallId",
+        "result",
+    ]))
+        return invalid;
+    if (typeof input.recallId !== "string")
+        return invalid;
+    const result = normalizeRoleMemoryRecallResult(input.result);
+    if (!result)
+        return invalid;
+    return {
+        ok: true,
+        value: {
+            authority: "runtime",
+            type: "settle_memory_recall",
+            callId: input.callId,
+            invocationAttempt: input.invocationAttempt,
+            steeringVersion: input.steeringVersion,
+            recallId: input.recallId,
+            result,
+        },
+    };
+}
+export function hasMemoryRecallIdentity(input) {
+    if (typeof input.callId !== "string" || input.callId.length === 0)
+        return false;
+    if (!Number.isSafeInteger(input.invocationAttempt))
+        return false;
+    if (input.invocationAttempt < 1)
+        return false;
+    if (!Number.isSafeInteger(input.steeringVersion))
+        return false;
+    return input.steeringVersion >= 0;
+}
+export function isBoundedMemoryRecallQuery(input) {
+    if (typeof input !== "string")
+        return false;
+    if (input.trim().length === 0)
+        return false;
+    return input.length <= ROLE_MEMORY_RECALL_QUERY_MAX_LENGTH;
+}
+export function normalizeRoleMemoryRecallResult(input) {
+    if (!isRecord(input))
+        return undefined;
+    if (!exactKeys(input, ["outcome", "records", "omittedRecordCount"], ["reason"]))
+        return undefined;
+    const outcome = input.outcome;
+    if (!isMemoryRecallOutcome(outcome))
+        return undefined;
+    if (!Array.isArray(input.records))
+        return undefined;
+    if (input.records.length > ROLE_MEMORY_RECALL_RECORD_LIMIT_MAX)
+        return undefined;
+    if (!Number.isSafeInteger(input.omittedRecordCount))
+        return undefined;
+    if (input.omittedRecordCount < 0)
+        return undefined;
+    if (!isMemoryRecallReason(input.reason))
+        return undefined;
+    if (!hasRecordsForMemoryRecallOutcome(outcome, input.records.length))
+        return undefined;
+    try {
+        if (JSON.stringify(input).length > ROLE_MEMORY_RECALL_RESULT_MAX_LENGTH)
+            return undefined;
+        const records = Object.freeze(input.records.map(parseMemoryRecord));
+        if (new Set(records.map((record) => record.id)).size !== records.length)
+            return undefined;
+        return Object.freeze({
+            outcome,
+            records,
+            omittedRecordCount: input.omittedRecordCount,
+            ...(input.reason !== undefined ? { reason: input.reason } : {}),
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function isMemoryRecallOutcome(input) {
+    return (input === "found" ||
+        input === "empty" ||
+        input === "unavailable" ||
+        input === "superseded");
+}
+function isMemoryRecallReason(input) {
+    if (input === undefined)
+        return true;
+    if (typeof input !== "string")
+        return false;
+    if (input.trim().length === 0)
+        return false;
+    return input.length <= ROLE_MEMORY_RECALL_REASON_MAX_LENGTH;
+}
+function hasRecordsForMemoryRecallOutcome(outcome, count) {
+    if (outcome === "found")
+        return count > 0;
+    return count === 0;
+}

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

@@ -0,0 +1,5 @@
+import type { RoleCallCommitEffect, RoleCallLedgerHead } from "./contracts.js";
+export declare function traceMemoryRecallCommit(params: Readonly<{
+    head: RoleCallLedgerHead;
+    effect: RoleCallCommitEffect;
+}>, common: Readonly<Record<string, unknown>>): boolean;

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

@@ -0,0 +1,27 @@
+import { traceDebug } from "../../observability/debug-logger.js";
+export function traceMemoryRecallCommit(params, common) {
+    const effect = params.effect;
+    if (!isMemoryRecallEffect(effect))
+        return false;
+    const recall = params.head.state.memoryRecalls.find((entry) => entry.recallId === effect.recallId);
+    const call = params.head.state.calls.find((entry) => entry.callId === effect.callId);
+    traceDebug("runtime.role_calls", effect.type === "memory_recall_begun"
+        ? "memory.recall_begun"
+        : "memory.recall_settled", {
+        ...common,
+        callId: effect.callId,
+        recallId: effect.recallId,
+        invocationAttempt: effect.invocationAttempt,
+        steeringVersion: effect.steeringVersion,
+        activationCount: call?.activationCount,
+        queryLength: recall?.query.length,
+        outcome: recall?.result?.outcome,
+        recordCount: recall?.result?.records.length,
+        omittedRecordCount: recall?.result?.omittedRecordCount,
+    });
+    return true;
+}
+function isMemoryRecallEffect(effect) {
+    return (effect.type === "memory_recall_begun" ||
+        effect.type === "memory_recall_settled");
+}

package/dist/src/runtime/orchestration/role-calls/memory-recall-state-validation.d.ts

@@ -0,0 +1,3 @@
+import type { RoleCallState, RoleCallValidationIssue } from "./contracts.js";
+export declare function validateRoleMemoryRecalls(state: RoleCallState): RoleCallValidationIssue[];
+export declare function hasSettledMemoryRecallActivationRange(state: RoleCallState, callId: string, fromActivation: number, toActivation: number): boolean;

package/dist/src/runtime/orchestration/role-calls/memory-recall-state-validation.js

@@ -0,0 +1,121 @@
+import { RUNTIME_ROOT_ROLE_ID } from "../roles.js";
+import { hasMemoryRecallIdentity, isBoundedMemoryRecallQuery, normalizeRoleMemoryRecallResult, } from "./memory-recall-decoder.js";
+import { exactKeys, isRecord } from "../../validation/strict-record.js";
+export function validateRoleMemoryRecalls(state) {
+    const invalid = [
+        { code: "invalid_role_memory_recalls", path: "state.memoryRecalls" },
+    ];
+    if (!Array.isArray(state.memoryRecalls))
+        return invalid;
+    const root = state.calls.find((call) => call.callId === state.rootCallId);
+    if (!root)
+        return state.memoryRecalls.length === 0 ? [] : invalid;
+    let previousAttempt = 0;
+    let previousSteeringVersion = 0;
+    let previousCompletedChildCount = 0;
+    let pendingCount = 0;
+    for (const [index, recall] of state.memoryRecalls.entries()) {
+        if (!isOrderedRootMemoryRecall(recall, root, index, previousAttempt, previousSteeringVersion, previousCompletedChildCount))
+            return invalid;
+        previousAttempt = recall.invocationAttempt;
+        previousSteeringVersion = recall.steeringVersion;
+        previousCompletedChildCount = recall.completedChildCount;
+        if (!isMemoryRecallSettlementBound(state, root, recall, index))
+            return invalid;
+        pendingCount += recall.status === "pending" ? 1 : 0;
+    }
+    if (hasUnboundMemoryWait(state, pendingCount))
+        return invalid;
+    return [];
+}
+function isOrderedRootMemoryRecall(recall, root, index, previousAttempt, previousSteeringVersion, previousCompletedChildCount) {
+    if (!isRecord(recall))
+        return false;
+    if (!hasMemoryRecallIdentity(recall))
+        return false;
+    if (!exactKeys(recall, [
+        "recallId",
+        "completedChildCount",
+        "callId",
+        "invocationAttempt",
+        "steeringVersion",
+        "query",
+        "status",
+    ], ["result"]))
+        return false;
+    if (recall.recallId !== `recall-${index + 1}`)
+        return false;
+    if (recall.callId !== root.callId)
+        return false;
+    if (root.roleId !== RUNTIME_ROOT_ROLE_ID)
+        return false;
+    if (root.parentCallId !== null)
+        return false;
+    if (recall.invocationAttempt <= previousAttempt)
+        return false;
+    if (recall.steeringVersion < previousSteeringVersion)
+        return false;
+    if (!hasOrderedMemoryRecallChildAnchor(recall.completedChildCount, root, previousCompletedChildCount))
+        return false;
+    if (!isBoundedMemoryRecallQuery(recall.query))
+        return false;
+    return recall.query === recall.query.trim();
+}
+function hasOrderedMemoryRecallChildAnchor(value, root, previousCompletedChildCount) {
+    if (typeof value !== "number")
+        return false;
+    if (!Number.isSafeInteger(value))
+        return false;
+    if (value < 0)
+        return false;
+    if (value < previousCompletedChildCount)
+        return false;
+    return value <= root.childCallIds.length;
+}
+function isMemoryRecallSettlementBound(state, root, recall, index) {
+    if (recall.status === "pending")
+        return isPendingMemoryRecallBound(state, root, recall, index);
+    if (recall.status !== "settled")
+        return false;
+    if (recall.invocationAttempt >= root.activationCount)
+        return false;
+    return normalizeRoleMemoryRecallResult(recall.result) !== undefined;
+}
+function isPendingMemoryRecallBound(state, root, recall, index) {
+    if (index !== state.memoryRecalls.length - 1)
+        return false;
+    if (recall.result !== undefined)
+        return false;
+    if (recall.invocationAttempt !== root.activationCount)
+        return false;
+    if (recall.completedChildCount !== root.childCallIds.length)
+        return false;
+    if (state.phase !== "running")
+        return false;
+    if (state.activeCallId !== root.callId)
+        return false;
+    return root.status === "waiting_for_memory";
+}
+export function hasSettledMemoryRecallActivationRange(state, callId, fromActivation, toActivation) {
+    if (toActivation < fromActivation)
+        return false;
+    const recalls = state.memoryRecalls.filter((recall) => isSettledMemoryRecallWithinRange(recall, callId, fromActivation, toActivation));
+    if (recalls.length !== toActivation - fromActivation)
+        return false;
+    return recalls.every((recall, index) => recall.invocationAttempt === fromActivation + index);
+}
+function isSettledMemoryRecallWithinRange(recall, callId, fromActivation, toActivation) {
+    if (recall.callId !== callId)
+        return false;
+    if (recall.status !== "settled")
+        return false;
+    if (recall.invocationAttempt < fromActivation)
+        return false;
+    return recall.invocationAttempt < toActivation;
+}
+function hasUnboundMemoryWait(state, pendingCount) {
+    const waitingCalls = state.calls.filter((call) => call.status === "waiting_for_memory");
+    if (waitingCalls.length !== pendingCount)
+        return true;
+    return waitingCalls.some((call) => call.callId !== state.rootCallId);
+}

package/dist/src/runtime/orchestration/role-calls/memory-recall-transactions.d.ts

@@ -0,0 +1,3 @@
+import type { RoleCallLedger } from "./contracts.js";
+import type { RoleMemoryRecallTransactions } from "./memory-recall-contract.js";
+export declare function createMemoryRecallTransactions(apply: RoleCallLedger["apply"]): RoleMemoryRecallTransactions;

package/dist/src/runtime/orchestration/role-calls/memory-recall-transactions.js

@@ -0,0 +1,44 @@
+import { requireEffect } from "./transaction-effect.js";
+export function createMemoryRecallTransactions(apply) {
+    return Object.freeze({
+        async beginMemoryRecall(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: {
+                    authority: "active_role",
+                    type: "begin_memory_recall",
+                    callId: input.callId,
+                    invocationAttempt: input.invocationAttempt,
+                    steeringVersion: input.steeringVersion,
+                    query: input.query,
+                },
+            }), "memory_recall_begun", "memory_recall_transition_invalid", (effect) => matchesMemoryRecallIdentity(effect, input));
+        },
+        async settleMemoryRecall(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: {
+                    authority: "runtime",
+                    type: "settle_memory_recall",
+                    callId: input.callId,
+                    invocationAttempt: input.invocationAttempt,
+                    steeringVersion: input.steeringVersion,
+                    recallId: input.recallId,
+                    result: input.result,
+                },
+            }), "memory_recall_settled", "memory_recall_transition_invalid", (effect) => matchesMemoryRecallSettlement(effect, input));
+        },
+    });
+}
+function matchesMemoryRecallIdentity(effect, input) {
+    if (effect.callId !== input.callId)
+        return false;
+    if (effect.invocationAttempt !== input.invocationAttempt)
+        return false;
+    return effect.steeringVersion === input.steeringVersion;
+}
+function matchesMemoryRecallSettlement(effect, input) {
+    if (!matchesMemoryRecallIdentity(effect, input))
+        return false;
+    return effect.recallId === input.recallId;
+}

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

@@ -1,7 +1,7 @@
 import { type RoleCallPolicy, type RoleCallPolicyInput, type RoleCallState, type RoleCallTransitionResult, type RoleCallValidationIssue } from "./contracts.js";
 export { hasRoleCallCapabilityAuthority } from "./candidate-validation.js";
 export declare function createInitialRoleCallState(requestId: string): RoleCallState;
-export declare function applyRoleCallCommand(state: RoleCallState, commandInput: unknown, policy: RoleCallPolicy): RoleCallTransitionResult;
+export declare function applyRoleCallCommand(state: RoleCallState, commandInput: unknown, policy: RoleCallPolicy, admittedHeadRevision?: number): RoleCallTransitionResult;
 export declare function validateRoleCallCandidate(params: {
     state: RoleCallState;
     policy: RoleCallPolicy;

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

@@ -22,6 +22,7 @@ export function createInitialRoleCallState(requestId) {
         results: [],
         plans: [],
         capabilityExecutions: [],
+        memoryRecalls: [],
         operationSupervision: createInitialRoleOperationSupervisionState(),
         capabilitySelectionSupervision: createInitialRoleCapabilitySelectionSupervisionState(),
         rootResponse: null,
@@ -31,7 +32,7 @@ export function createInitialRoleCallState(requestId) {
     }
     return state;
 }
-export function applyRoleCallCommand(state, commandInput, policy) {
+export function applyRoleCallCommand(state, commandInput, policy, admittedHeadRevision) {
     const policyIssues = validateRoleCallPolicy(policy);
     if (policyIssues.length > 0) {
         return reject(state, "invalid_policy", policyIssues);
@@ -44,7 +45,7 @@ export function applyRoleCallCommand(state, commandInput, policy) {
     if (!command.ok) {
         return reject(state, command.code);
     }
-    const transition = dispatchRoleCallCommand(state, command.value, policy);
+    const transition = dispatchRoleCallCommand(state, command.value, policy, admittedHeadRevision);
     if (!transition.ok)
         return transition;
     const reservationIssue = findRoleActivationReservationIssue(state, policy, command.value);

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

@@ -0,0 +1,49 @@
+import { type RoleCallFrame, type RoleCallPolicy, type RoleCallResult, type RoleCallState } from "./contracts.js";
+import { type RoleCallWorkResultReceipt } from "./work-result-receipt.js";
+export declare const ROLE_CALL_REVIEWER_VERDICT_RECEIPT_KIND: "reviewer_verdict_v1";
+export declare const ROLE_CALL_REVIEWER_VERDICT_MAX_GAPS = 5;
+export declare const ROLE_CALL_REVIEWER_VERDICT_MAX_REFS_PER_GAP = 1;
+export declare const ROLE_CALL_REVIEWER_VERDICT_REFERENCE_MAX_LENGTH = 256;
+export declare const ROLE_CALL_REVIEWER_VERDICT_KIND_MAX_LENGTH = 160;
+export declare const ROLE_CALL_REVIEWER_VERDICT_GAP_SUMMARY_MAX_LENGTH = 224;
+export type RoleCallReviewerVerdictGap = Readonly<{
+    kind: string;
+    subjectRefs: readonly string[];
+    factRefs: readonly string[];
+    evidenceRefs: readonly string[];
+    summary: string;
+}>;
+export type RoleCallReviewerVerdictReceipt = Readonly<{
+    kind: typeof ROLE_CALL_REVIEWER_VERDICT_RECEIPT_KIND;
+    reviewerCallId: string;
+    callerCallId: string;
+    reviewScopeId: string;
+    sourceRevision: number;
+    verdict: "pass" | "report_gaps";
+    gaps: readonly RoleCallReviewerVerdictGap[];
+}>;
+export type RoleCallResultReceipt = RoleCallReviewerVerdictReceipt | RoleCallWorkResultReceipt;
+export declare function createRoleCallReviewerVerdictReceipt(input: Omit<RoleCallReviewerVerdictReceipt, "kind">): RoleCallReviewerVerdictReceipt;
+export declare function normalizeRoleCallResultReceipt(input: unknown): RoleCallResultReceipt | undefined | null;
+export declare function isRoleCallResultReceiptValidForReturn(params: {
+    receipt: RoleCallResultReceipt | undefined;
+    caller: RoleCallFrame;
+    child: RoleCallFrame;
+    outcome: RoleCallResult["outcome"];
+    policy: RoleCallPolicy;
+    admittedHeadRevision: number | undefined;
+}): boolean;
+export declare function isRoleCallResultReceiptValidForStoredResult(params: {
+    receipt: RoleCallResultReceipt | undefined;
+    producer: RoleCallFrame;
+    result: RoleCallResult;
+    policy: RoleCallPolicy;
+    state?: RoleCallState;
+}): boolean;
+export declare function isRoleCallReviewerVerdictReceiptBoundToChild(params: {
+    receipt: RoleCallReviewerVerdictReceipt;
+    callerCallId: string;
+    childCallId: string;
+    childRoleId: RoleCallFrame["roleId"];
+    outcome: RoleCallResult["outcome"];
+}): boolean;