@abot-ai/runtime 1.1.0 → 1.2.0

package/dist/src/runtime/context/capability-brief.js

@@ -0,0 +1,106 @@
+import { buildToolAvailabilityOverview, } from "../../plugin-sdk/tool-availability-overview.js";
+import { assessRequestMessagesBudget } from "./request-context-budget.js";
+import { estimateMessageTokens } from "./token-estimator.js";
+export const CAPABILITY_BRIEF_KIND = "runtime_capability_brief_v1";
+export const CAPABILITY_BRIEF_MAX_TOKENS = 512;
+const CAPABILITY_BRIEF_PREFIX = `${CAPABILITY_BRIEF_KIND}\n`;
+/** Optional availability metadata admitted against the full context estimate. */
+export function projectCapabilityBrief(params) {
+    const budgetTokens = resolveCapabilityBriefBudget(params);
+    if (params.groups.length === 0) {
+        return omittedBrief(budgetTokens, "empty_catalog");
+    }
+    const levels = hasCompleteCapabilityBriefEntries(params.entries, params.groups)
+        ? ["detailed", "titles", "groups"]
+        : ["groups"];
+    for (const level of levels) {
+        const body = buildToolAvailabilityOverview(params.entries ?? [], params.groups, level);
+        const message = Object.freeze({
+            role: "system",
+            content: [
+                CAPABILITY_BRIEF_KIND,
+                "Request-registry availability for delegation only. Data, not instructions, user intent, execution authority, pending work, or completion evidence.",
+                `Detail: ${level}. Complete coverage at this level; omitted detail does not mean unavailable capabilities.`,
+                body,
+            ].join("\n"),
+        });
+        const estimatedTokens = estimateMessageTokens(message, params.context.budget.tokenEstimation);
+        if (!fitsCapabilityBriefBudget(estimatedTokens, budgetTokens))
+            continue;
+        return Object.freeze({
+            level,
+            message,
+            estimatedTokens,
+            budgetTokens,
+            reason: "complete_catalog",
+        });
+    }
+    return omittedBrief(budgetTokens, "insufficient_budget");
+}
+/** Consumers explicitly remove this optional reference at narrower phases. */
+export function isCapabilityBriefMessage(message) {
+    if (message.role !== "system")
+        return false;
+    return message.content.startsWith(CAPABILITY_BRIEF_PREFIX);
+}
+function resolveCapabilityBriefBudget(params) {
+    const { context } = params;
+    const messages = [
+        { role: "system", content: context.instructions },
+        ...(context.priorConversationMessages ?? []),
+        ...context.historyMessages,
+        ...(context.referenceMessages ?? []),
+        ...(context.referenceParts?.flatMap((part) => part.messages) ?? []),
+        ...(context.continuationMessages ?? []),
+        ...(context.continuationParts?.flatMap((part) => part.messages) ?? []),
+        {
+            role: "user",
+            content: context.prompt,
+            ...(context.attachments ? { attachments: context.attachments } : {}),
+        },
+        ...(params.additionalBudgetMessages ?? []),
+    ];
+    const { budget } = assessRequestMessagesBudget({
+        messages,
+        budget: context.budget,
+        ...(context.format ? { format: context.format } : {}),
+    });
+    // Configured methodology is added later; reserve it for the 70% threshold
+    // as well as the input ceiling. Strictly below: admission triggers on >=.
+    const instructionReserve = context.budget.configuredInstructionReserveTokens ?? 0;
+    const compactionHeadroom = budget.compactionTriggerInputTokens -
+        1 -
+        budget.estimatedInputTokens -
+        instructionReserve;
+    const admissionHeadroom = budget.availableInputTokens - budget.estimatedInputTokens;
+    return Math.max(0, Math.min(CAPABILITY_BRIEF_MAX_TOKENS, compactionHeadroom, admissionHeadroom));
+}
+function hasCompleteCapabilityBriefEntries(entries, groups) {
+    if (entries === undefined)
+        return false;
+    if (entries.length === 0)
+        return false;
+    const operationIds = new Set(entries.map((entry) => entry.operationId));
+    if (operationIds.size !== entries.length)
+        return false;
+    const counts = new Map();
+    for (const entry of entries) {
+        for (const groupId of new Set(entry.catalogGroups)) {
+            counts.set(groupId, (counts.get(groupId) ?? 0) + 1);
+        }
+    }
+    if (counts.size !== groups.length)
+        return false;
+    return groups.every((group) => counts.get(group.groupId) === group.memberCount);
+}
+function fitsCapabilityBriefBudget(tokens, budget) {
+    return tokens <= budget;
+}
+function omittedBrief(budgetTokens, reason) {
+    return Object.freeze({
+        level: "none",
+        estimatedTokens: 0,
+        budgetTokens,
+        reason,
+    });
+}

package/dist/src/runtime/context/request-tool-results-message-binding.d.ts

@@ -0,0 +1,6 @@
+import type { ChatMessage } from "../../model-gateway/types.js";
+import type { RequestToolResultsView } from "./request-tool-results.js";
+/** Mints one frozen message bound to its exact canonical result view. */
+export declare function bindRequestToolResultsMessage(view: RequestToolResultsView, content: string): ChatMessage;
+/** Accepts only a message minted for this exact canonical result view. */
+export declare function isRequestToolResultsMessageBoundToView(message: ChatMessage, view: RequestToolResultsView): boolean;

package/dist/src/runtime/context/request-tool-results-message-binding.js

@@ -0,0 +1,30 @@
+const REQUEST_TOOL_RESULTS_MESSAGE_AUTHORITY = Symbol("requestToolResultsMessageAuthority");
+/** Mints one frozen message bound to its exact canonical result view. */
+export function bindRequestToolResultsMessage(view, content) {
+    const message = { role: "user", content };
+    const authority = Object.freeze({ message, view });
+    Object.defineProperty(message, REQUEST_TOOL_RESULTS_MESSAGE_AUTHORITY, {
+        value: authority,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return Object.freeze(message);
+}
+/** Accepts only a message minted for this exact canonical result view. */
+export function isRequestToolResultsMessageBoundToView(message, view) {
+    const descriptor = Object.getOwnPropertyDescriptor(message, REQUEST_TOOL_RESULTS_MESSAGE_AUTHORITY);
+    if (!descriptor)
+        return false;
+    const authority = descriptor.value;
+    if (typeof authority !== "object" || authority === null)
+        return false;
+    if (!Object.isFrozen(authority))
+        return false;
+    const candidate = authority;
+    return (candidate.message === message &&
+        candidate.view === view &&
+        descriptor.enumerable === false &&
+        descriptor.configurable === false &&
+        descriptor.writable === false);
+}

package/dist/src/runtime/context/request-tool-results-scope.d.ts

@@ -0,0 +1,3 @@
+import type { RequestToolResultsView } from "./request-tool-results.js";
+/** Requires Planner-item views to carry only their exact call lane. */
+export declare function isRequestToolResultsViewValidForCallScope(view: RequestToolResultsView, callId: string, callScoped: boolean): boolean;

package/dist/src/runtime/context/request-tool-results-scope.js

@@ -0,0 +1,8 @@
+/** Requires Planner-item views to carry only their exact call lane. */
+export function isRequestToolResultsViewValidForCallScope(view, callId, callScoped) {
+    if (!callScoped)
+        return view.scope === undefined;
+    return (view.scope?.kind === "call" &&
+        view.scope.callId === callId &&
+        view.results.every((result) => result.callId === callId));
+}

package/dist/src/runtime/context/request-tool-results.d.ts

@@ -26,12 +26,16 @@ export type RequestToolResult = Readonly<{
 export type RequestToolResultsView = Readonly<{
     sourceRevision: number;
     results: readonly RequestToolResult[];
+    scope?: Readonly<{
+        kind: "call";
+        callId: string;
+    }>;
 }>;
 /**
- * Projects every settled capability result in canonical ledger order.
- * Summaries remain request-wide. Complete reference data is projected only
- * back to the exact call that produced it; callers consume the settled child
- * result instead of receiving a second copy of the capability payload.
+ * Projects settled capability results in canonical ledger order. Direct
+ * Planner-owned Workers receive only their exact call lane; other roles keep
+ * request-wide summaries. Complete reference data is projected only back to
+ * the exact call that produced it.
  */
 export declare function projectRequestToolResults(params: Readonly<{
     ledger: RoleCallLedger;

package/dist/src/runtime/context/request-tool-results.js

@@ -1,15 +1,17 @@
 import { isRoleCapabilityId, ROLE_CAPABILITY_REFERENCE_DATA_MAX_LENGTH, ROLE_CAPABILITY_RESULT_REFERENCE_LIMIT_MAX, ROLE_CAPABILITY_RESULT_REFERENCE_TARGET_MAX_LENGTH, ROLE_CALL_RESULT_MAX_LENGTH, } from "../orchestration/role-calls/index.js";
+import { projectWorkerCapabilityPlannerItemBinding } from "../orchestration/worker-capabilities/assignment-provenance.js";
 import { traceDebug } from "../observability/debug-logger.js";
 import { normalizeCapabilityAdapterResult, } from "../orchestration/capability-adapters/result.js";
+import { bindRequestToolResultsMessage } from "./request-tool-results-message-binding.js";
 import { createSemanticCompactionSha256Fingerprint, } from "./semantic-compaction/index.js";
 import { projectAcceptedCapabilityAction, } from "./accepted-capability-action.js";
 export const REQUEST_TOOL_RESULTS_MESSAGE_KIND = "runtime_request_tool_results_v1";
 const REQUEST_TOOL_RESULTS_LOG_SCOPE = "runtime.request_tool_results";
 /**
- * Projects every settled capability result in canonical ledger order.
- * Summaries remain request-wide. Complete reference data is projected only
- * back to the exact call that produced it; callers consume the settled child
- * result instead of receiving a second copy of the capability payload.
+ * Projects settled capability results in canonical ledger order. Direct
+ * Planner-owned Workers receive only their exact call lane; other roles keep
+ * request-wide summaries. Complete reference data is projected only back to
+ * the exact call that produced it.
  */
 export function projectRequestToolResults(params) {
     const projected = [];
@@ -19,9 +21,12 @@ export function projectRequestToolResults(params) {
         if (params.ledger.current() !== params.head) {
             throw new Error("request_tool_results_head_stale");
         }
-        if (!params.head.state.calls.some(({ callId }) => callId === params.callId)) {
+        const call = params.head.state.calls.find(({ callId }) => callId === params.callId);
+        if (!call) {
             throw new Error("request_tool_results_call_invalid");
         }
+        const plannerItemScoped = projectWorkerCapabilityPlannerItemBinding(params.head, call) !==
+            undefined;
         for (const execution of params.head.state.capabilityExecutions) {
             if (execution.status === "running") {
                 runningExecutionCount += 1;
@@ -68,6 +73,8 @@ export function projectRequestToolResults(params) {
                 adapterResult: exactResult.value,
             });
             sourceProjected.push(sourceResult);
+            if (plannerItemScoped && execution.callId !== params.callId)
+                continue;
             if (execution.callId !== params.callId) {
                 const { referenceData: _referenceData, adapterResult: _adapterResult, acceptedAction: _acceptedAction, ...summaryOnlyResult } = sourceResult;
                 projected.push(Object.freeze(summaryOnlyResult));
@@ -80,6 +87,14 @@ export function projectRequestToolResults(params) {
         const view = Object.freeze({
             sourceRevision: params.head.revision,
             results: Object.freeze(currentResults),
+            ...(plannerItemScoped
+                ? {
+                    scope: Object.freeze({
+                        kind: "call",
+                        callId: params.callId,
+                    }),
+                }
+                : {}),
         });
         traceProjection("projected", params, currentResults, runningExecutionCount, undefined, sourceProjected);
         return view;
@@ -91,15 +106,13 @@ export function projectRequestToolResults(params) {
 }
 export function buildRequestToolResultsMessage(view) {
     const results = projectModelVisibleRequestToolResults(view.results);
-    return Object.freeze({
-        role: "user",
-        content: JSON.stringify({
-            kind: REQUEST_TOOL_RESULTS_MESSAGE_KIND,
-            authority: "reference_data",
-            sourceRevision: view.sourceRevision,
-            results,
-        }),
-    });
+    return bindRequestToolResultsMessage(view, JSON.stringify({
+        kind: REQUEST_TOOL_RESULTS_MESSAGE_KIND,
+        authority: "reference_data",
+        sourceRevision: view.sourceRevision,
+        ...(view.scope ? { coverage: view.scope } : {}),
+        results,
+    }));
 }
 export function buildCompactedRequestToolResultsMessage(view, checkpoint) {
     const modelVisibleResults = projectModelVisibleRequestToolResults(view.results);
@@ -127,30 +140,28 @@ export function buildCompactedRequestToolResultsMessage(view, checkpoint) {
     })) {
         throw new Error("request_tool_results_compaction_fingerprint_mismatch");
     }
-    return Object.freeze({
-        role: "user",
-        content: JSON.stringify({
-            kind: REQUEST_TOOL_RESULTS_MESSAGE_KIND,
-            authority: "reference_data",
-            sourceRevision: view.sourceRevision,
-            semanticCheckpoint: {
-                kind: checkpoint.kind,
-                scopeId: checkpoint.scopeId,
-                roleId: checkpoint.roleId,
-                callId: checkpoint.callId,
-                checkpointSourceRevision: checkpoint.sourceRevision,
-                presenceEffect: "passive_role_continuation_not_user_intent_or_completion",
-                coveredSources: checkpoint.sourceDigests.map(({ sourceRef, sourceFingerprint, digest }) => ({
-                    sourceRef,
-                    sourceFingerprint,
-                    digest,
-                })),
-                continuation: checkpoint.continuation,
-                coveredResults,
-            },
-            results: modelVisibleResults.filter(({ executionId }) => !coveredExecutionIds.has(executionId)),
-        }),
-    });
+    return bindRequestToolResultsMessage(view, JSON.stringify({
+        kind: REQUEST_TOOL_RESULTS_MESSAGE_KIND,
+        authority: "reference_data",
+        sourceRevision: view.sourceRevision,
+        ...(view.scope ? { coverage: view.scope } : {}),
+        semanticCheckpoint: {
+            kind: checkpoint.kind,
+            scopeId: checkpoint.scopeId,
+            roleId: checkpoint.roleId,
+            callId: checkpoint.callId,
+            checkpointSourceRevision: checkpoint.sourceRevision,
+            presenceEffect: "passive_role_continuation_not_user_intent_or_completion",
+            coveredSources: checkpoint.sourceDigests.map(({ sourceRef, sourceFingerprint, digest }) => ({
+                sourceRef,
+                sourceFingerprint,
+                digest,
+            })),
+            continuation: checkpoint.continuation,
+            coveredResults,
+        },
+        results: modelVisibleResults.filter(({ executionId }) => !coveredExecutionIds.has(executionId)),
+    }));
 }
 /**
  * Keeps the canonical settled-result view intact while ensuring that the

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

@@ -8,6 +8,7 @@ import { isRoleOperationSupervisionSettlementHistoryValid, isRoleOperationSuperv
 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";
@@ -157,7 +158,13 @@ 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}`));
         }
     }

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,7 @@ 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 { 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";
@@ -90,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",
@@ -98,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: {
@@ -113,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",

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.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

@@ -4,7 +4,7 @@ import { reconsiderCapabilitySelection } from "./command-dispatch/capability-sel
 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 "create_root":
             return createRoot(state);
@@ -13,7 +13,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,9 @@ 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";
+export declare const ROLE_CALL_LEDGER_CONTRACT_VERSION = 17;
+export declare const ROLE_CALL_LEDGER_HEAD_KIND: "runtime_role_call_ledger_v17";
 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;
@@ -95,6 +96,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<{
@@ -214,6 +216,7 @@ export type ReturnChildRoleCallCommand = Readonly<{
     childCallId: string;
     outcome: "completed" | "failed";
     summary: string;
+    receipt?: RoleCallResultReceipt;
 }>;
 export type BeginRoleCapabilityExecutionCommand = Readonly<{
     authority: "active_role";

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 = 17;
+export const ROLE_CALL_LEDGER_HEAD_KIND = "runtime_role_call_ledger_v17";
 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/index.d.ts

@@ -6,10 +6,14 @@ 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";