@abot-ai/runtime 1.1.0 → 1.2.0

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

@@ -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";

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

@@ -31,7 +31,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 +44,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;

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

@@ -0,0 +1,188 @@
+import { exactKeys, isRecord } from "../../validation/strict-record.js";
+import { ROLE_CALL_RESULT_MAX_LENGTH, SUPERVISOR_WORKER_V1_AUTHORITY_SNAPSHOT, } from "./contracts.js";
+import { isRoleCallWorkResultReceiptValidForStoredResult, mustIssueSupervisorWorkResultReceipt, normalizeRoleCallWorkResultReceipt, ROLE_CALL_WORK_RESULT_RECEIPT_KIND, } from "./work-result-receipt.js";
+export const ROLE_CALL_REVIEWER_VERDICT_RECEIPT_KIND = "reviewer_verdict_v1";
+export const ROLE_CALL_REVIEWER_VERDICT_MAX_GAPS = 5;
+export const ROLE_CALL_REVIEWER_VERDICT_MAX_REFS_PER_GAP = 1;
+export const ROLE_CALL_REVIEWER_VERDICT_REFERENCE_MAX_LENGTH = 256;
+export const ROLE_CALL_REVIEWER_VERDICT_KIND_MAX_LENGTH = 160;
+export const ROLE_CALL_REVIEWER_VERDICT_GAP_SUMMARY_MAX_LENGTH = 224;
+export function createRoleCallReviewerVerdictReceipt(input) {
+    const receipt = normalizeRoleCallReviewerVerdictReceipt({
+        kind: ROLE_CALL_REVIEWER_VERDICT_RECEIPT_KIND,
+        ...input,
+    });
+    if (!receipt)
+        throw new Error("reviewer_verdict_receipt_invalid");
+    return receipt;
+}
+export function normalizeRoleCallResultReceipt(input) {
+    if (input === undefined)
+        return undefined;
+    if (isRecord(input) && input.kind === ROLE_CALL_WORK_RESULT_RECEIPT_KIND) {
+        return normalizeRoleCallWorkResultReceipt(input);
+    }
+    return normalizeRoleCallReviewerVerdictReceipt(input);
+}
+function normalizeRoleCallReviewerVerdictReceipt(input) {
+    if (!isRecord(input) ||
+        !exactKeys(input, [
+            "kind",
+            "reviewerCallId",
+            "callerCallId",
+            "reviewScopeId",
+            "sourceRevision",
+            "verdict",
+            "gaps",
+        ]) ||
+        input.kind !== ROLE_CALL_REVIEWER_VERDICT_RECEIPT_KIND ||
+        !isBoundedText(input.reviewerCallId, ROLE_CALL_REVIEWER_VERDICT_REFERENCE_MAX_LENGTH) ||
+        !isBoundedText(input.callerCallId, ROLE_CALL_REVIEWER_VERDICT_REFERENCE_MAX_LENGTH) ||
+        !isBoundedText(input.reviewScopeId, ROLE_CALL_REVIEWER_VERDICT_REFERENCE_MAX_LENGTH) ||
+        !Number.isSafeInteger(input.sourceRevision) ||
+        input.sourceRevision < 0 ||
+        (input.verdict !== "pass" && input.verdict !== "report_gaps") ||
+        !Array.isArray(input.gaps) ||
+        input.gaps.length > ROLE_CALL_REVIEWER_VERDICT_MAX_GAPS ||
+        (input.verdict === "pass" && input.gaps.length !== 0) ||
+        (input.verdict === "report_gaps" && input.gaps.length === 0)) {
+        return null;
+    }
+    const gaps = input.gaps.map(normalizeGap);
+    if (gaps.some((gap) => gap === null))
+        return null;
+    const receipt = {
+        kind: ROLE_CALL_REVIEWER_VERDICT_RECEIPT_KIND,
+        reviewerCallId: input.reviewerCallId.trim(),
+        callerCallId: input.callerCallId.trim(),
+        reviewScopeId: input.reviewScopeId.trim(),
+        sourceRevision: input.sourceRevision,
+        verdict: input.verdict,
+        gaps: gaps,
+    };
+    if (JSON.stringify(receipt).length > ROLE_CALL_RESULT_MAX_LENGTH)
+        return null;
+    return deepFreeze(receipt);
+}
+export function isRoleCallResultReceiptValidForReturn(params) {
+    if (params.receipt === undefined)
+        return true;
+    if (params.receipt.kind === ROLE_CALL_WORK_RESULT_RECEIPT_KIND)
+        return false;
+    return (Number.isSafeInteger(params.admittedHeadRevision) &&
+        params.receipt.sourceRevision === params.admittedHeadRevision &&
+        isRoleCallResultReceiptBound({
+            receipt: params.receipt,
+            callerCallId: params.caller.callId,
+            childCallId: params.child.callId,
+            childRoleId: params.child.roleId,
+            outcome: params.outcome,
+            policy: params.policy,
+        }));
+}
+export function isRoleCallResultReceiptValidForStoredResult(params) {
+    if (params.receipt === undefined) {
+        return !mustIssueSupervisorWorkResultReceipt({
+            child: params.producer,
+            policy: params.policy,
+        });
+    }
+    if (params.receipt.kind === ROLE_CALL_WORK_RESULT_RECEIPT_KIND) {
+        if (!params.state)
+            return false;
+        return isRoleCallWorkResultReceiptValidForStoredResult({
+            state: params.state,
+            producer: params.producer,
+            result: params.result,
+            receipt: params.receipt,
+            policy: params.policy,
+        });
+    }
+    return (params.producer.parentCallId !== null &&
+        isRoleCallResultReceiptBound({
+            receipt: params.receipt,
+            callerCallId: params.producer.parentCallId,
+            childCallId: params.producer.callId,
+            childRoleId: params.producer.roleId,
+            outcome: params.result.outcome,
+            policy: params.policy,
+        }));
+}
+export function isRoleCallReviewerVerdictReceiptBoundToChild(params) {
+    const normalized = normalizeRoleCallReviewerVerdictReceipt(params.receipt);
+    return (normalized !== null &&
+        normalized !== undefined &&
+        params.childRoleId === "reviewer" &&
+        params.outcome === "completed" &&
+        normalized.reviewerCallId === params.childCallId &&
+        normalized.callerCallId === params.callerCallId &&
+        normalized.reviewScopeId ===
+            `review:${params.childCallId}:r${normalized.sourceRevision}`);
+}
+function isRoleCallResultReceiptBound(params) {
+    const normalized = normalizeRoleCallReviewerVerdictReceipt(params.receipt);
+    return (normalized !== null &&
+        normalized !== undefined &&
+        hasDelegatedReviewerReceiptAuthority(params.policy) &&
+        isRoleCallReviewerVerdictReceiptBoundToChild({
+            receipt: normalized,
+            callerCallId: params.callerCallId,
+            childCallId: params.childCallId,
+            childRoleId: params.childRoleId,
+            outcome: params.outcome,
+        }));
+}
+function hasDelegatedReviewerReceiptAuthority(policy) {
+    const expected = SUPERVISOR_WORKER_V1_AUTHORITY_SNAPSHOT;
+    return (policy.authority.id === expected.id &&
+        policy.authority.version === expected.version &&
+        policy.authority.definitionHash === expected.definitionHash);
+}
+function normalizeGap(value) {
+    if (!isRecord(value) ||
+        !exactKeys(value, [
+            "kind",
+            "subjectRefs",
+            "factRefs",
+            "evidenceRefs",
+            "summary",
+        ]) ||
+        !isBoundedText(value.kind, ROLE_CALL_REVIEWER_VERDICT_KIND_MAX_LENGTH) ||
+        !isBoundedText(value.summary, ROLE_CALL_REVIEWER_VERDICT_GAP_SUMMARY_MAX_LENGTH)) {
+        return null;
+    }
+    const subjectRefs = normalizeRefs(value.subjectRefs);
+    const factRefs = normalizeRefs(value.factRefs);
+    const evidenceRefs = normalizeRefs(value.evidenceRefs);
+    if (!subjectRefs || !factRefs || !evidenceRefs)
+        return null;
+    return Object.freeze({
+        kind: value.kind.trim(),
+        subjectRefs,
+        factRefs,
+        evidenceRefs,
+        summary: value.summary.trim(),
+    });
+}
+function normalizeRefs(value) {
+    if (!Array.isArray(value) ||
+        value.length > ROLE_CALL_REVIEWER_VERDICT_MAX_REFS_PER_GAP ||
+        value.some((entry) => !isBoundedText(entry, ROLE_CALL_REVIEWER_VERDICT_REFERENCE_MAX_LENGTH))) {
+        return null;
+    }
+    return Object.freeze(value.map((entry) => entry.trim()));
+}
+function isBoundedText(value, maximumLength) {
+    return (typeof value === "string" &&
+        value.trim().length > 0 &&
+        value.length <= maximumLength);
+}
+function deepFreeze(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value)) {
+        return value;
+    }
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return value;
+}

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

@@ -0,0 +1,19 @@
+import type { RoleCallFrame, RoleCallPolicy, RoleCallResult, RoleCallState } from "./contracts.js";
+import { type RoleCallResultReceipt } from "./result-receipt.js";
+export type CanonicalResultReceiptResolution = Readonly<{
+    ok: true;
+    receipt?: RoleCallResultReceipt;
+}> | Readonly<{
+    ok: false;
+    issueCode: "work_result_receipt_forged" | "work_result_lineage_invalid" | "result_receipt_invalid";
+}>;
+export declare function resolveCanonicalResultReceiptForReturn(params: Readonly<{
+    state: RoleCallState;
+    caller: RoleCallFrame;
+    child: RoleCallFrame;
+    resultRef: string;
+    outcome: RoleCallResult["outcome"];
+    suppliedReceipt?: RoleCallResultReceipt;
+    policy: RoleCallPolicy;
+    admittedHeadRevision?: number;
+}>): CanonicalResultReceiptResolution;

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

@@ -0,0 +1,52 @@
+import { isRoleCallResultReceiptValidForReturn, } from "./result-receipt.js";
+import { createCanonicalRoleCallWorkResultReceipt, mustIssueSupervisorWorkResultReceipt, ROLE_CALL_WORK_RESULT_RECEIPT_KIND, } from "./work-result-receipt.js";
+export function resolveCanonicalResultReceiptForReturn(params) {
+    if (params.suppliedReceipt?.kind === ROLE_CALL_WORK_RESULT_RECEIPT_KIND) {
+        return invalidResolution("work_result_receipt_forged");
+    }
+    if (mustIssueSupervisorWorkResultReceipt({
+        child: params.child,
+        policy: params.policy,
+    })) {
+        return resolveRuntimeOwnedWorkReceipt(params);
+    }
+    if (!isRoleCallResultReceiptValidForReturn({
+        receipt: params.suppliedReceipt,
+        caller: params.caller,
+        child: params.child,
+        outcome: params.outcome,
+        policy: params.policy,
+        admittedHeadRevision: params.admittedHeadRevision,
+    })) {
+        return invalidResolution("result_receipt_invalid");
+    }
+    return params.suppliedReceipt
+        ? Object.freeze({ ok: true, receipt: params.suppliedReceipt })
+        : Object.freeze({ ok: true });
+}
+function resolveRuntimeOwnedWorkReceipt(params) {
+    if (params.suppliedReceipt !== undefined) {
+        return invalidResolution("work_result_receipt_forged");
+    }
+    if (!isNonNegativeSafeInteger(params.admittedHeadRevision)) {
+        return invalidResolution("work_result_lineage_invalid");
+    }
+    const receipt = createCanonicalRoleCallWorkResultReceipt({
+        state: params.state,
+        caller: params.caller,
+        child: params.child,
+        resultRef: params.resultRef,
+        outcome: params.outcome,
+        admittedHeadRevision: params.admittedHeadRevision,
+        policy: params.policy,
+    });
+    return receipt
+        ? Object.freeze({ ok: true, receipt })
+        : invalidResolution("work_result_lineage_invalid");
+}
+function invalidResolution(issueCode) {
+    return Object.freeze({ ok: false, issueCode });
+}
+function isNonNegativeSafeInteger(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}

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

@@ -36,6 +36,7 @@ export function createRoleCallTransactions(apply) {
                     childCallId: input.childCallId,
                     outcome: input.outcome,
                     summary: input.summary,
+                    ...(input.receipt ? { receipt: input.receipt } : {}),
                 },
             }), "child_returned", "child_return_transition_invalid", (effect) => effect.callerCallId === input.callerCallId &&
                 effect.childCallId === input.childCallId);

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

@@ -0,0 +1,34 @@
+import type { RoleCallFrame, RoleCallPlanItemStatus, RoleCallResult, RoleCallState } from "./contracts.js";
+import type { RoleCallWorkResultReceipt } from "./work-result-receipt.js";
+export declare const ROLE_CALL_WORK_RESULT_LINEAGE_KIND: "work_result_lineage_v1";
+type TerminalPlanItemStatus = Exclude<RoleCallPlanItemStatus, "in_progress">;
+export type RoleCallWorkResultPlanItem = Readonly<{
+    itemId: string;
+    status: TerminalPlanItemStatus;
+    resultRef: string | null;
+}>;
+export type RoleCallWorkResultPlanSnapshot = Readonly<{
+    planId: string;
+    planVersion: number;
+    items: readonly RoleCallWorkResultPlanItem[];
+}>;
+export type RoleCallWorkResultLineage = Readonly<{
+    kind: typeof ROLE_CALL_WORK_RESULT_LINEAGE_KIND;
+    lineageFingerprint: string;
+    capabilityExecutionIds: readonly string[];
+    planner?: RoleCallWorkResultPlanSnapshot;
+}>;
+export type RoleCallWorkLineageProjection = RoleCallWorkResultLineage;
+export type CanonicalRoleCallWorkResultLineageInput = Readonly<{
+    state: RoleCallState;
+    producer: RoleCallFrame;
+    resultRef: string;
+    outcome: RoleCallResult["outcome"];
+    sourceRevision: number;
+}>;
+export declare function createCanonicalRoleCallWorkResultLineage(input: CanonicalRoleCallWorkResultLineageInput): RoleCallWorkResultLineage | null;
+export declare function projectRoleCallWorkResultLineage(input: {
+    state: RoleCallState;
+    receipt: RoleCallWorkResultReceipt;
+}): RoleCallWorkResultLineage | null;
+export {};

package/dist/src/runtime/orchestration/role-calls/work-result-lineage.js

@@ -0,0 +1,185 @@
+import { createHash } from "node:crypto";
+export const ROLE_CALL_WORK_RESULT_LINEAGE_KIND = "work_result_lineage_v1";
+export function createCanonicalRoleCallWorkResultLineage(input) {
+    if (!hasCanonicalWorkResultIdentity(input))
+        return null;
+    const capabilityExecutionIds = resolveSubtreeCapabilityExecutionIds(input.state, input.producer);
+    if (!capabilityExecutionIds)
+        return null;
+    const planner = resolvePlannerSnapshot(input.state, input.producer);
+    if (planner === null)
+        return null;
+    const callerCallId = input.producer.parentCallId;
+    if (!callerCallId)
+        return null;
+    const lineageFingerprint = createLineageFingerprint({
+        resultRef: input.resultRef,
+        producerCallId: input.producer.callId,
+        callerCallId,
+        roleId: input.producer.roleId,
+        outcome: input.outcome,
+        sourceRevision: input.sourceRevision,
+        dependencyResultRefs: input.producer.dependencyResultRefs,
+        capabilityExecutionIds,
+        ...(planner ? { planner } : {}),
+    });
+    return deepFreeze({
+        kind: ROLE_CALL_WORK_RESULT_LINEAGE_KIND,
+        lineageFingerprint,
+        capabilityExecutionIds,
+        ...(planner ? { planner } : {}),
+    });
+}
+export function projectRoleCallWorkResultLineage(input) {
+    const result = findUniqueProducerResult(input.state, input.receipt);
+    if (!result)
+        return null;
+    const producer = input.state.calls.find(({ callId }) => callId === input.receipt.producerCallId);
+    if (!producer || !isStoredResultBoundToProducer(producer, result)) {
+        return null;
+    }
+    if (producer.parentCallId !== input.receipt.callerCallId)
+        return null;
+    const lineage = createCanonicalRoleCallWorkResultLineage({
+        state: input.state,
+        producer,
+        resultRef: result.resultRef,
+        outcome: result.outcome,
+        sourceRevision: input.receipt.sourceRevision,
+    });
+    if (!lineage)
+        return null;
+    if (lineage.lineageFingerprint !== input.receipt.lineageFingerprint) {
+        return null;
+    }
+    if (!matchesPlannerPlanReference(lineage, input.receipt))
+        return null;
+    return lineage;
+}
+function hasCanonicalWorkResultIdentity(input) {
+    if (input.producer.roleId !== "planner" && input.producer.roleId !== "worker") {
+        return false;
+    }
+    if (!input.producer.parentCallId)
+        return false;
+    if (!input.resultRef.trim())
+        return false;
+    if (input.outcome !== "completed" && input.outcome !== "failed")
+        return false;
+    return Number.isSafeInteger(input.sourceRevision) && input.sourceRevision >= 0;
+}
+function resolveSubtreeCapabilityExecutionIds(state, producer) {
+    const subtreeCallIds = resolveSubtreeCallIds(state, producer);
+    if (!subtreeCallIds)
+        return null;
+    const executions = state.capabilityExecutions.filter(({ callId }) => subtreeCallIds.has(callId));
+    if (executions.some(({ status }) => status !== "settled"))
+        return null;
+    return Object.freeze(executions.map(({ executionId }) => executionId));
+}
+function resolveSubtreeCallIds(state, producer) {
+    const callById = new Map(state.calls.map((call) => [call.callId, call]));
+    if (callById.get(producer.callId) !== producer)
+        return null;
+    const visited = new Set();
+    const pending = [producer.callId];
+    while (pending.length > 0) {
+        const callId = pending.pop();
+        if (!callId || visited.has(callId))
+            return null;
+        const call = callById.get(callId);
+        if (!call)
+            return null;
+        visited.add(callId);
+        for (const childCallId of call.childCallIds) {
+            const child = callById.get(childCallId);
+            if (!child || child.parentCallId !== callId)
+                return null;
+            pending.push(childCallId);
+        }
+    }
+    return visited;
+}
+function resolvePlannerSnapshot(state, producer) {
+    if (producer.roleId !== "planner")
+        return undefined;
+    const plans = state.plans.filter(({ definition }) => definition.plannerCallId === producer.callId);
+    if (plans.length === 0)
+        return undefined;
+    if (plans.length !== 1)
+        return null;
+    const plan = plans[0];
+    if (plan.definition.items.length !== plan.itemStates.length)
+        return null;
+    const items = plan.definition.items.map(({ itemId }) => {
+        const itemState = plan.itemStates.find((item) => item.itemId === itemId);
+        return itemState
+            ? resolveTerminalPlanItem(state, producer, itemState)
+            : null;
+    });
+    if (items.some((item) => item === null))
+        return null;
+    return deepFreeze({
+        planId: plan.definition.planId,
+        planVersion: plan.definition.version,
+        items: items,
+    });
+}
+function resolveTerminalPlanItem(state, producer, item) {
+    if (item.status === "in_progress")
+        return null;
+    if (item.status === "pending") {
+        if (item.childCallId !== null)
+            return null;
+        return Object.freeze({
+            itemId: item.itemId,
+            status: item.status,
+            resultRef: null,
+        });
+    }
+    if (!item.childCallId)
+        return null;
+    const child = state.calls.find(({ callId }) => callId === item.childCallId);
+    if (!child || child.parentCallId !== producer.callId || !child.resultRef) {
+        return null;
+    }
+    const result = state.results.find(({ resultRef }) => resultRef === child.resultRef);
+    if (!result || result.producerCallId !== child.callId)
+        return null;
+    return Object.freeze({
+        itemId: item.itemId,
+        status: item.status,
+        resultRef: result.resultRef,
+    });
+}
+function findUniqueProducerResult(state, receipt) {
+    const results = state.results.filter(({ producerCallId }) => producerCallId === receipt.producerCallId);
+    return results.length === 1 ? results[0] : undefined;
+}
+function isStoredResultBoundToProducer(producer, result) {
+    return (producer.status === "completed" &&
+        producer.resultRef === result.resultRef &&
+        producer.roleId === result.roleId);
+}
+function matchesPlannerPlanReference(lineage, receipt) {
+    if (!lineage.planner)
+        return receipt.plannerPlanRef === undefined;
+    return (receipt.plannerPlanRef?.planId === lineage.planner.planId &&
+        receipt.plannerPlanRef.planVersion === lineage.planner.planVersion);
+}
+function createLineageFingerprint(input) {
+    const canonical = JSON.stringify({
+        kind: ROLE_CALL_WORK_RESULT_LINEAGE_KIND,
+        ...input,
+    });
+    return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+function deepFreeze(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value)) {
+        return value;
+    }
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return value;
+}

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

@@ -0,0 +1,36 @@
+import { type RoleCallFrame, type RoleCallPolicy, type RoleCallResult, type RoleCallState } from "./contracts.js";
+export declare const ROLE_CALL_WORK_RESULT_RECEIPT_KIND: "work_result_v1";
+export declare const ROLE_CALL_WORK_RESULT_FINGERPRINT_PATTERN: RegExp;
+export type RoleCallWorkResultReceipt = Readonly<{
+    kind: typeof ROLE_CALL_WORK_RESULT_RECEIPT_KIND;
+    producerCallId: string;
+    callerCallId: string;
+    sourceRevision: number;
+    lineageFingerprint: string;
+    plannerPlanRef?: Readonly<{
+        planId: string;
+        planVersion: number;
+    }>;
+}>;
+export type CanonicalRoleCallWorkResultReceiptInput = Readonly<{
+    state: RoleCallState;
+    caller: RoleCallFrame;
+    child: RoleCallFrame;
+    resultRef: string;
+    outcome: RoleCallResult["outcome"];
+    policy: RoleCallPolicy;
+    admittedHeadRevision: number | undefined;
+}>;
+export declare function normalizeRoleCallWorkResultReceipt(input: unknown): RoleCallWorkResultReceipt | undefined | null;
+export declare function mustIssueSupervisorWorkResultReceipt(input: {
+    child: RoleCallFrame;
+    policy: RoleCallPolicy;
+}): boolean;
+export declare function createCanonicalRoleCallWorkResultReceipt(input: CanonicalRoleCallWorkResultReceiptInput): RoleCallWorkResultReceipt | null;
+export declare function isRoleCallWorkResultReceiptValidForStoredResult(input: {
+    state: RoleCallState;
+    receipt: RoleCallWorkResultReceipt;
+    producer: RoleCallFrame;
+    result: RoleCallResult;
+    policy: RoleCallPolicy;
+}): boolean;