@abot-ai/runtime 1.0.0 → 1.2.0

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,13 +36,17 @@ 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);
         },
         async beginCapabilityExecution(input) {
-            return requireEffect(await apply({
+            return requireCapabilityExecutionAttemptEffect(await apply({
                 expectedHead: input.expectedHead,
+                ...(input.admission
+                    ? { capabilityExecutionAdmission: input.admission }
+                    : {}),
                 command: {
                     authority: "active_role",
                     type: "begin_capability_execution",
@@ -52,8 +56,11 @@ export function createRoleCallTransactions(apply) {
                     declaredEffect: input.declaredEffect,
                     intent: input.intent,
                     controlsJson: input.controlsJson,
+                    ...(input.actionFingerprint
+                        ? { actionFingerprint: input.actionFingerprint }
+                        : {}),
                 },
-            }), "capability_execution_begun", "commit_effect_invalid", (effect) => effect.callId === input.callId);
+            }), input);
         },
         async settleCapabilityExecution(input) {
             return requireEffect(await apply({
@@ -63,8 +70,11 @@ export function createRoleCallTransactions(apply) {
                 effect.executionId === input.executionId);
         },
         async beginCapabilityBatch(input) {
-            return requireEffect(await apply({
+            return requireCapabilityBatchAttemptEffect(await apply({
                 expectedHead: input.expectedHead,
+                ...(input.admission
+                    ? { capabilityExecutionAdmission: input.admission }
+                    : {}),
                 command: {
                     authority: "active_role",
                     type: "begin_capability_batch",
@@ -72,8 +82,7 @@ export function createRoleCallTransactions(apply) {
                     invocationAttempt: input.invocationAttempt,
                     entries: input.entries,
                 },
-            }), "capability_batch_begun", "commit_effect_invalid", (effect) => effect.callId === input.callId &&
-                effect.executionIds.length === input.entries.length);
+            }), input);
         },
         async settleCapabilityBatch(input) {
             return requireEffect(await apply({
@@ -122,12 +131,58 @@ export function createRoleCallTransactions(apply) {
                     invocationAttempt: input.invocationAttempt,
                     steeringVersion: input.steeringVersion,
                     selection: input.selection,
+                    cause: input.cause,
                 },
             }), "capability_selection_reconsidered", "capability_selection_reconsideration_transition_invalid", (effect) => effect.callId === input.callId &&
                 effect.invocationAttempt === input.invocationAttempt);
         },
     });
 }
+function requireCapabilityExecutionAttemptEffect(commit, input) {
+    if (!commit.ok) {
+        return Object.freeze({
+            ok: false,
+            issueCode: commit.code,
+            commit,
+        });
+    }
+    const effect = commit.effect;
+    const isExpectedExecution = effect.type === "capability_execution_begun" &&
+        effect.callId === input.callId;
+    const isExpectedIntervention = effect.type === "operation_supervision_intervened" &&
+        effect.callId === input.callId &&
+        effect.invocationAttempt === input.invocationAttempt &&
+        effect.capabilityId === input.capabilityId &&
+        effect.actionFingerprint === input.actionFingerprint;
+    if (!isExpectedExecution && !isExpectedIntervention) {
+        return invalidEffect(commit, "commit_effect_invalid");
+    }
+    const typedCommit = commit;
+    return Object.freeze({ ok: true, commit: typedCommit });
+}
+function requireCapabilityBatchAttemptEffect(commit, input) {
+    if (!commit.ok) {
+        return Object.freeze({
+            ok: false,
+            issueCode: commit.code,
+            commit,
+        });
+    }
+    const effect = commit.effect;
+    const isExpectedBatch = effect.type === "capability_batch_begun" &&
+        effect.callId === input.callId &&
+        effect.executionIds.length === input.entries.length;
+    const isExpectedIntervention = effect.type === "operation_supervision_intervened" &&
+        effect.callId === input.callId &&
+        effect.invocationAttempt === input.invocationAttempt &&
+        input.entries.some((entry) => entry.capabilityId === effect.capabilityId &&
+            entry.actionFingerprint === effect.actionFingerprint);
+    if (!isExpectedBatch && !isExpectedIntervention) {
+        return invalidEffect(commit, "commit_effect_invalid");
+    }
+    const typedCommit = commit;
+    return Object.freeze({ ok: true, commit: typedCommit });
+}
 export function resolveRoleCallTransactions(ledger) {
     if (ledger.transactions) {
         return ledger.transactions;
@@ -158,6 +213,9 @@ function createSettleCapabilityExecutionCommand(input) {
         callId: input.callId,
         executionId: input.executionId,
         outcome: input.outcome,
+        ...(input.outcomeFingerprint
+            ? { outcomeFingerprint: input.outcomeFingerprint }
+            : {}),
         observedEffect: input.observedEffect,
         summary: input.summary,
         exactResult: input.exactResult,

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;