@abot-ai/runtime 1.0.0

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

@@ -0,0 +1,328 @@
+import { isRuntimeDelegateRoleId, RUNTIME_ROOT_ROLE_ID, RUNTIME_ROLE_IDS, } from "../roles.js";
+import { createRoleCapabilitySelectionFingerprint, normalizeRoleCapabilitySelectionProjection, } from "./capability-selection-reconsideration.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 { isRoleCallWorkerCapabilityScope } from "./worker-capability-scope.js";
+import { isRoleCallWorkingDirectoryRoleId, normalizeEstablishedRoleCallWorkingDirectory, normalizeRoleCallWorkingDirectory, } from "./working-directory.js";
+import { areOwnedDependencyResults, exactKeys, findCall, isBoundedText, isCanonicalTerminalText, isExactJsonObjectString, isExactResultValidForCall, isOptionalBoundedText, isRecord, isRoleCapabilityDeclaredEffect, isSettledObservedEffectCompatible, isUniqueStringArray, isValidCapabilityResultReferences, issue, } from "./reducer-primitives.js";
+export function validateRoleCallPolicy(policy) {
+    if (!isExecutionPolicyAuthoritySnapshot(policy?.authority)) {
+        return [issue("invalid_execution_policy_authority", "policy.authority")];
+    }
+    const limits = policy?.limits;
+    return !limits ||
+        !Number.isInteger(limits.maxDepth) ||
+        limits.maxDepth < 0 ||
+        !Number.isInteger(limits.maxCalls) ||
+        limits.maxCalls < 1 ||
+        !Number.isInteger(limits.maxCapabilityExecutions) ||
+        limits.maxCapabilityExecutions < 1 ||
+        limits.maxCapabilityExecutions > ROLE_CAPABILITY_EXECUTION_LIMIT_MAX ||
+        !Number.isInteger(limits.maxObjectiveChars) ||
+        limits.maxObjectiveChars < 1 ||
+        !Number.isInteger(limits.maxResultChars) ||
+        limits.maxResultChars < 1 ||
+        !Number.isInteger(limits.maxResponseChars) ||
+        limits.maxResponseChars < 1
+        ? [issue("invalid_role_call_policy", "policy.limits")]
+        : [];
+}
+export function validateRoleCallState(state, policy) {
+    const issues = [];
+    if (state?.contractVersion !== ROLE_CALL_LEDGER_CONTRACT_VERSION ||
+        !isBoundedText(state?.requestId, 256) ||
+        !["empty", "running", "completed"].includes(state?.phase) ||
+        !Array.isArray(state?.calls) ||
+        !Array.isArray(state?.results) ||
+        !Array.isArray(state?.plans) ||
+        !Array.isArray(state?.capabilityExecutions) ||
+        !Number.isInteger(state?.callSequence) ||
+        !Number.isInteger(state?.resultSequence) ||
+        !Number.isInteger(state?.capabilityExecutionSequence) ||
+        state.callSequence !== state.calls.length ||
+        state.resultSequence !== state.results.length ||
+        state.capabilityExecutionSequence !== state.capabilityExecutions.length) {
+        return [issue("invalid_role_call_state_shape", "state")];
+    }
+    if (state.calls.length > policy.limits.maxCalls) {
+        issues.push(issue("role_call_count_exceeded", "state.calls"));
+    }
+    if (state.capabilityExecutions.length > policy.limits.maxCapabilityExecutions) {
+        issues.push(issue("role_capability_execution_count_exceeded", "state.capabilityExecutions"));
+    }
+    const ids = new Set(state.calls.map((call) => call.callId));
+    if (ids.size !== state.calls.length) {
+        issues.push(issue("duplicate_role_call_id", "state.calls"));
+    }
+    const root = state.rootCallId
+        ? state.calls.find((call) => call.callId === state.rootCallId)
+        : undefined;
+    const turnOwnerCalls = state.calls.filter((call) => call.status === "active" || call.status === "waiting_for_capability");
+    if (state.phase === "empty") {
+        if (state.rootCallId !== null ||
+            state.activeCallId !== null ||
+            state.calls.length > 0 ||
+            state.results.length > 0 ||
+            state.plans.length > 0 ||
+            state.capabilityExecutions.length > 0 ||
+            state.rootResponse !== null) {
+            issues.push(issue("invalid_empty_role_call_state", "state.phase"));
+        }
+    }
+    else if (!root ||
+        root.parentCallId !== null ||
+        root.roleId !== RUNTIME_ROOT_ROLE_ID ||
+        root.depth !== 0) {
+        issues.push(issue("invalid_role_call_root", "state.rootCallId"));
+    }
+    if (state.phase === "running") {
+        if (turnOwnerCalls.length !== 1 ||
+            turnOwnerCalls[0]?.callId !== state.activeCallId ||
+            state.rootResponse !== null) {
+            issues.push(issue("invalid_active_role_call", "state.activeCallId"));
+        }
+    }
+    if (state.phase === "completed" &&
+        (state.activeCallId !== null ||
+            root?.status !== "completed" ||
+            !isCanonicalTerminalText(state.rootResponse, policy.limits.maxResponseChars, policy.authority.terminalTextMode))) {
+        issues.push(issue("invalid_completed_role_call_state", "state.phase"));
+    }
+    for (const call of state.calls) {
+        if (!isAuthorizedCallFrame(policy.authority, state.rootCallId, call)) {
+            issues.push(issue("unauthorized_role_call_contract", `state.calls.${call.callId}.roleId`));
+        }
+        if (!RUNTIME_ROLE_IDS.includes(call.roleId) ||
+            ![
+                "active",
+                "waiting_for_child",
+                "waiting_for_capability",
+                "completed",
+            ].includes(call.status) ||
+            !Number.isInteger(call.depth) ||
+            call.depth < 0 ||
+            call.depth > policy.limits.maxDepth ||
+            !Number.isInteger(call.activationCount) ||
+            call.activationCount < 1 ||
+            !Array.isArray(call.childCallIds) ||
+            !isUniqueStringArray(call.dependencyResultRefs) ||
+            (call.workerCapabilityScope !== undefined &&
+                (!hasCapabilityAuthority(policy.authority, state, call) ||
+                    !isRoleCallWorkerCapabilityScope(call.workerCapabilityScope))) ||
+            (call.workingDirectory !== undefined &&
+                !isCanonicalRoleCallWorkingDirectory(state, call, policy.authority)) ||
+            (call.parentCallId === null
+                ? call.objective !== null || call.dependencyResultRefs.length !== 0
+                : !isBoundedText(call.objective, policy.limits.maxObjectiveChars)) ||
+            !isValidCapabilitySelectionReconsideration(call, policy, state)) {
+            issues.push(issue("invalid_role_call_frame", `state.calls.${call.callId}`));
+            continue;
+        }
+        if (call.parentCallId !== null) {
+            const parent = state.calls.find((candidate) => candidate.callId === call.parentCallId);
+            if (!parent ||
+                call.depth !== parent.depth + 1 ||
+                !parent.childCallIds.includes(call.callId)) {
+                issues.push(issue("invalid_role_call_parent", `state.calls.${call.callId}`));
+            }
+            if (!parent ||
+                !areOwnedDependencyResults(state, parent, call.dependencyResultRefs, state.calls.indexOf(call))) {
+                issues.push(issue("invalid_role_call_dependencies", `state.calls.${call.callId}.dependencyResultRefs`));
+            }
+        }
+    }
+    const resultRefs = new Set(state.results.map((result) => result.resultRef));
+    if (resultRefs.size !== state.results.length) {
+        issues.push(issue("duplicate_role_call_result", "state.results"));
+    }
+    for (const result of state.results) {
+        const producer = state.calls.find((call) => call.callId === result.producerCallId);
+        if (!producer ||
+            producer.resultRef !== result.resultRef ||
+            producer.status !== "completed" ||
+            producer.roleId !== result.roleId ||
+            (result.outcome !== "completed" && result.outcome !== "failed") ||
+            !isBoundedText(result.summary, policy.limits.maxResultChars)) {
+            issues.push(issue("invalid_role_call_result_owner", `state.results.${result.resultRef}`));
+        }
+    }
+    issues.push(...validateRoleCallPlans(state, policy));
+    validateCapabilityExecutions(state, policy, issues);
+    return issues;
+}
+function isValidCapabilitySelectionReconsideration(call, policy, state) {
+    const reconsideration = call.lastCapabilitySelectionReconsideration;
+    if (reconsideration === undefined)
+        return true;
+    if (!hasCapabilityAuthority(policy.authority, state, call) ||
+        !isRecord(reconsideration) ||
+        !exactKeys(reconsideration, [
+            "invocationAttempt",
+            "steeringVersion",
+            "fingerprint",
+            "selection",
+        ]) ||
+        !Number.isSafeInteger(reconsideration.invocationAttempt) ||
+        reconsideration.invocationAttempt < 1 ||
+        reconsideration.invocationAttempt >= call.activationCount ||
+        !Number.isSafeInteger(reconsideration.steeringVersion) ||
+        reconsideration.steeringVersion < 0 ||
+        typeof reconsideration.fingerprint !== "string" ||
+        !/^sha256:[a-f0-9]{64}$/.test(reconsideration.fingerprint)) {
+        return false;
+    }
+    const selection = normalizeRoleCapabilitySelectionProjection(reconsideration.selection);
+    return (selection !== undefined &&
+        createRoleCapabilitySelectionFingerprint({
+            steeringVersion: reconsideration.steeringVersion,
+            selection,
+        }) === reconsideration.fingerprint);
+}
+function validateCapabilityExecutions(state, policy, issues) {
+    const executionIds = new Set(state.capabilityExecutions.map((execution) => execution.executionId));
+    if (executionIds.size !== state.capabilityExecutions.length) {
+        issues.push(issue("duplicate_role_capability_execution_id", "state.capabilityExecutions"));
+    }
+    const running = state.capabilityExecutions.filter((execution) => execution.status === "running");
+    if (running.length > 1 &&
+        (new Set(running.map((execution) => execution.callId)).size !== 1 ||
+            new Set(running.map((execution) => execution.invocationAttempt)).size !==
+                1 ||
+            running.some((execution) => execution.declaredEffect !== "observation"))) {
+        issues.push(issue("invalid_running_role_capability_batch", "state.capabilityExecutions"));
+    }
+    for (const execution of state.capabilityExecutions) {
+        const call = findCall(state, execution.callId);
+        if (!call ||
+            !hasCapabilityAuthority(policy.authority, state, call) ||
+            !isBoundedText(execution.executionId, 128) ||
+            !Number.isInteger(execution.invocationAttempt) ||
+            execution.invocationAttempt < 1 ||
+            !isRoleCapabilityId(execution.capabilityId) ||
+            !isRoleCapabilityDeclaredEffect(execution.declaredEffect) ||
+            !isBoundedText(execution.intent, ROLE_CAPABILITY_INVOCATION_INTENT_MAX_LENGTH) ||
+            !isExactJsonObjectString(execution.controlsJson) ||
+            (execution.status !== "running" && execution.status !== "settled")) {
+            issues.push(issue("invalid_role_capability_execution", `state.capabilityExecutions.${execution.executionId}`));
+            continue;
+        }
+        if (execution.status === "running" &&
+            (state.phase !== "running" ||
+                state.activeCallId !== call.callId ||
+                call.status !== "waiting_for_capability" ||
+                call.activationCount !== execution.invocationAttempt ||
+                execution.outcome !== null ||
+                execution.observedEffect !== null ||
+                execution.summary !== null ||
+                execution.referenceData !== undefined ||
+                execution.references !== undefined ||
+                execution.exactResult !== undefined)) {
+            issues.push(issue("invalid_running_role_capability_execution", `state.capabilityExecutions.${execution.executionId}`));
+        }
+        if (execution.status === "settled" &&
+            (call.activationCount <= execution.invocationAttempt ||
+                !isBoundedText(execution.summary, policy.limits.maxResultChars) ||
+                !isOptionalBoundedText(execution.referenceData, ROLE_CAPABILITY_REFERENCE_DATA_MAX_LENGTH) ||
+                !isValidCapabilityResultReferences(execution.references) ||
+                !isExactResultValidForCall(call, execution.exactResult) ||
+                (execution.outcome !== "succeeded" && execution.outcome !== "failed") ||
+                !isSettledObservedEffectCompatible({
+                    declaredEffect: execution.declaredEffect,
+                    outcome: execution.outcome,
+                    observedEffect: execution.observedEffect,
+                }))) {
+            issues.push(issue("invalid_settled_role_capability_execution", `state.capabilityExecutions.${execution.executionId}`));
+        }
+    }
+    for (const call of state.calls) {
+        const ownedRunning = running.filter((execution) => execution.callId === call.callId);
+        if ((call.status === "waiting_for_capability" && ownedRunning.length < 1) ||
+            (call.status !== "waiting_for_capability" && ownedRunning.length !== 0)) {
+            issues.push(issue("invalid_role_capability_call_ownership", `state.calls.${call.callId}`));
+        }
+    }
+    const invocationGroups = new Map();
+    for (const execution of state.capabilityExecutions) {
+        const key = `${execution.callId}:${execution.invocationAttempt}`;
+        const group = invocationGroups.get(key) ?? [];
+        group.push(execution);
+        invocationGroups.set(key, group);
+    }
+    for (const group of invocationGroups.values()) {
+        if (group.length > 1 &&
+            (group.some((execution) => execution.declaredEffect !== "observation") ||
+                new Set(group.map((execution) => execution.status)).size !== 1)) {
+            issues.push(issue("invalid_role_capability_batch_group", "state.capabilityExecutions"));
+        }
+    }
+}
+export function hasCapabilityAuthority(authority, state, call) {
+    return hasRoleCallCapabilityAuthority(authority, state.rootCallId, call);
+}
+export function hasRoleCallCapabilityAuthority(authority, rootCallId, call) {
+    if (!call)
+        return false;
+    const principal = call.callId === rootCallId && call.parentCallId === null
+        ? "root"
+        : isRuntimeDelegateRoleId(call.roleId) && call.parentCallId !== null
+            ? call.roleId
+            : undefined;
+    return (principal !== undefined &&
+        authority.capabilityAuthorities.includes(principal));
+}
+function isAuthorizedCallFrame(authority, rootCallId, call) {
+    if (call.callId === rootCallId) {
+        return call.parentCallId === null && call.roleId === RUNTIME_ROOT_ROLE_ID;
+    }
+    return (call.parentCallId !== null &&
+        isRuntimeDelegateRoleId(call.roleId) &&
+        authority.availableSubordinateContractIds.includes(call.roleId));
+}
+function isExecutionPolicyAuthoritySnapshot(value) {
+    if (!isRecord(value) ||
+        !exactKeys(value, [
+            "id",
+            "version",
+            "definitionHash",
+            "rootContractId",
+            "availableSubordinateContractIds",
+            "capabilityAuthorities",
+        ], ["terminalTextMode"]) ||
+        typeof value.id !== "string" ||
+        !/^[a-z][a-z0-9-]*$/.test(value.id) ||
+        !Number.isInteger(value.version) ||
+        value.version < 1 ||
+        typeof value.definitionHash !== "string" ||
+        !/^sha256:[a-f0-9]{64}$/.test(value.definitionHash) ||
+        !isExecutionContractId(value.rootContractId) ||
+        !Array.isArray(value.availableSubordinateContractIds) ||
+        !Array.isArray(value.capabilityAuthorities) ||
+        (value.terminalTextMode !== undefined &&
+            value.terminalTextMode !== "normalized" &&
+            value.terminalTextMode !== "exact")) {
+        return false;
+    }
+    const subordinateIds = value.availableSubordinateContractIds;
+    const capabilityAuthorities = value.capabilityAuthorities;
+    return (new Set(subordinateIds).size === subordinateIds.length &&
+        subordinateIds.every(isRuntimeDelegateRoleId) &&
+        new Set(capabilityAuthorities).size === capabilityAuthorities.length &&
+        capabilityAuthorities.every((principal) => principal === "root" || isRuntimeDelegateRoleId(principal)) &&
+        capabilityAuthorities.every((principal) => principal === "root" || subordinateIds.includes(principal)));
+}
+function isExecutionContractId(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= 128 &&
+        /^[a-z][a-z0-9._-]*$/.test(value));
+}
+function isCanonicalRoleCallWorkingDirectory(state, call, authority) {
+    if (call.callId === state.rootCallId && call.parentCallId === null) {
+        return (hasRoleCallCapabilityAuthority(authority, state.rootCallId, call) &&
+            normalizeEstablishedRoleCallWorkingDirectory(call.workingDirectory) ===
+                call.workingDirectory);
+    }
+    return (isRoleCallWorkingDirectoryRoleId(call.roleId) &&
+        normalizeRoleCallWorkingDirectory(call.workingDirectory) ===
+            call.workingDirectory);
+}

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

@@ -0,0 +1,25 @@
+import { type RoleCallFrame, type RoleCapabilitySelectionProjection, type RoleCapabilitySelectionReconsideration } from "./contracts.js";
+export declare function normalizeRoleCapabilitySelectionProjection(input: unknown): RoleCapabilitySelectionProjection | undefined;
+export declare function createRoleCapabilitySelectionProjection(input: Readonly<{
+    action: "invoke_capability" | "invoke_capabilities";
+    invocations: readonly Readonly<{
+        capabilityId: string;
+        intent: string;
+        selectionControls?: Readonly<Record<string, unknown>>;
+    }>[];
+    workingDirectory: string | null;
+    activeCapabilityCatalogGroupIds: readonly string[];
+}>): RoleCapabilitySelectionProjection;
+export declare function createRoleCapabilitySelectionFingerprint(input: Readonly<{
+    steeringVersion: number;
+    selection: RoleCapabilitySelectionProjection;
+}>): string;
+export declare function isImmediateRoleCapabilitySelectionReconsideration(input: {
+    call: RoleCallFrame;
+    steeringVersion: number;
+}): input is {
+    call: RoleCallFrame & {
+        lastCapabilitySelectionReconsideration: RoleCapabilitySelectionReconsideration;
+    };
+    steeringVersion: number;
+};

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

@@ -0,0 +1,158 @@
+import { createHash } from "node:crypto";
+import { isRoleCapabilityId, ROLE_CAPABILITY_INVOCATION_CONTROLS_JSON_MAX_LENGTH, ROLE_CAPABILITY_INVOCATION_INTENT_MAX_LENGTH, ROLE_CAPABILITY_SELECTION_INVOCATION_LIMIT_MAX, } from "./contracts.js";
+import { parseRoleCallWorkerCapabilityScope } from "./worker-capability-scope.js";
+import { normalizeEstablishedRoleCallWorkingDirectory } from "./working-directory.js";
+export function normalizeRoleCapabilitySelectionProjection(input) {
+    if (!isRecord(input) ||
+        !exactKeys(input, [
+            "action",
+            "invocations",
+            "workingDirectory",
+            "activeCapabilityCatalogGroupIds",
+        ])) {
+        return undefined;
+    }
+    if ((input.action !== "invoke_capability" &&
+        input.action !== "invoke_capabilities") ||
+        !Array.isArray(input.invocations) ||
+        input.invocations.length < 1 ||
+        input.invocations.length > ROLE_CAPABILITY_SELECTION_INVOCATION_LIMIT_MAX ||
+        (input.action === "invoke_capability"
+            ? input.invocations.length !== 1
+            : input.invocations.length < 2)) {
+        return undefined;
+    }
+    const scope = parseRoleCallWorkerCapabilityScope({
+        catalogGroupIds: input.activeCapabilityCatalogGroupIds,
+    });
+    if (!scope)
+        return undefined;
+    const workingDirectory = input.workingDirectory === null
+        ? null
+        : normalizeEstablishedRoleCallWorkingDirectory(input.workingDirectory);
+    if (workingDirectory === undefined)
+        return undefined;
+    const invocations = input.invocations.map((entry) => {
+        if (!isRecord(entry) ||
+            !exactKeys(entry, ["capabilityId", "intent", "selectionControlsJson"]) ||
+            !isRoleCapabilityId(entry.capabilityId) ||
+            typeof entry.intent !== "string" ||
+            entry.intent.length === 0 ||
+            entry.intent.length > ROLE_CAPABILITY_INVOCATION_INTENT_MAX_LENGTH ||
+            entry.intent.trim() !== entry.intent ||
+            typeof entry.selectionControlsJson !== "string" ||
+            entry.selectionControlsJson.length < 2 ||
+            entry.selectionControlsJson.length >
+                ROLE_CAPABILITY_INVOCATION_CONTROLS_JSON_MAX_LENGTH ||
+            canonicalizeControlsJson(entry.selectionControlsJson) !==
+                entry.selectionControlsJson) {
+            return undefined;
+        }
+        return Object.freeze({
+            capabilityId: entry.capabilityId,
+            intent: entry.intent,
+            selectionControlsJson: entry.selectionControlsJson,
+        });
+    });
+    if (invocations.some((entry) => entry === undefined))
+        return undefined;
+    return Object.freeze({
+        action: input.action,
+        invocations: Object.freeze(invocations),
+        workingDirectory,
+        activeCapabilityCatalogGroupIds: scope.catalogGroupIds,
+    });
+}
+export function createRoleCapabilitySelectionProjection(input) {
+    const selection = normalizeRoleCapabilitySelectionProjection({
+        action: input.action,
+        invocations: input.invocations.map((invocation) => ({
+            capabilityId: invocation.capabilityId,
+            intent: invocation.intent,
+            selectionControlsJson: canonicalizeControls(invocation.selectionControls ?? {}),
+        })),
+        workingDirectory: input.workingDirectory,
+        activeCapabilityCatalogGroupIds: input.activeCapabilityCatalogGroupIds,
+    });
+    if (!selection) {
+        throw new Error("role_capability_selection_projection_invalid");
+    }
+    return selection;
+}
+export function createRoleCapabilitySelectionFingerprint(input) {
+    if (!Number.isSafeInteger(input.steeringVersion) ||
+        input.steeringVersion < 0) {
+        throw new Error("role_capability_selection_steering_version_invalid");
+    }
+    const selection = normalizeRoleCapabilitySelectionProjection(input.selection);
+    if (!selection) {
+        throw new Error("role_capability_selection_projection_invalid");
+    }
+    const canonical = JSON.stringify({
+        steeringVersion: input.steeringVersion,
+        selection,
+    });
+    return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+export function isImmediateRoleCapabilitySelectionReconsideration(input) {
+    const reconsideration = input.call.lastCapabilitySelectionReconsideration;
+    const activeScope = input.call.workerCapabilityScope?.catalogGroupIds;
+    return (reconsideration !== undefined &&
+        input.call.activationCount === reconsideration.invocationAttempt + 1 &&
+        input.steeringVersion === reconsideration.steeringVersion &&
+        activeScope !== undefined &&
+        sameStringArray(activeScope, reconsideration.selection.activeCapabilityCatalogGroupIds) &&
+        (input.call.workingDirectory === undefined ||
+            input.call.workingDirectory ===
+                reconsideration.selection.workingDirectory));
+}
+function canonicalizeControls(input) {
+    const canonical = canonicalizeJsonValue(input);
+    if (!isRecord(canonical)) {
+        throw new Error("role_capability_selection_controls_invalid");
+    }
+    return JSON.stringify(canonical);
+}
+function canonicalizeControlsJson(input) {
+    try {
+        const parsed = JSON.parse(input);
+        return isRecord(parsed) ? canonicalizeControls(parsed) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function canonicalizeJsonValue(input) {
+    if (input === null ||
+        typeof input === "string" ||
+        typeof input === "boolean") {
+        return input;
+    }
+    if (typeof input === "number") {
+        if (!Number.isFinite(input)) {
+            throw new Error("role_capability_selection_controls_invalid");
+        }
+        return input;
+    }
+    if (Array.isArray(input)) {
+        return input.map(canonicalizeJsonValue);
+    }
+    if (!isRecord(input)) {
+        throw new Error("role_capability_selection_controls_invalid");
+    }
+    return Object.fromEntries(Object.keys(input)
+        .sort()
+        .map((key) => [key, canonicalizeJsonValue(input[key])]));
+}
+function exactKeys(input, expectedKeys) {
+    const expected = new Set(expectedKeys);
+    const actual = Object.keys(input);
+    return (actual.length === expected.size && actual.every((key) => expected.has(key)));
+}
+function sameStringArray(left, right) {
+    return (left.length === right.length &&
+        left.every((value, index) => value === right[index]));
+}
+function isRecord(input) {
+    return input !== null && typeof input === "object" && !Array.isArray(input);
+}

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

@@ -0,0 +1,32 @@
+import { type RoleCallCommitEffect, type RoleCallLedger, type RoleCallLedgerCommitResult, type RoleCallLedgerHead, type RoleCallWorkerCapabilityScope } from "./contracts.js";
+import { type RuntimeDelegateRoleId } from "../roles.js";
+export type CompletedRoleChildResult = Readonly<{
+    callerCallId: string;
+    childCallId: string;
+    resultRef: string;
+    roleId: RuntimeDelegateRoleId;
+    objective: string;
+    workerCapabilityScope?: RoleCallWorkerCapabilityScope;
+    workingDirectory?: string;
+    dependencyResultRefs: readonly string[];
+    outcome: "completed" | "failed";
+    summary: string;
+}>;
+export type RoleChildReturnContext = Readonly<{
+    callerCallId: string;
+    invocationAttempt: number;
+    returnedChildCallId: string;
+    returnedResultRef: string;
+    completedChildren: readonly CompletedRoleChildResult[];
+}>;
+export type RoleCallChildReturnCommit = Readonly<{
+    ok: true;
+    status: "committed";
+    previousHead: RoleCallLedgerHead;
+    head: RoleCallLedgerHead;
+    effect: Extract<RoleCallCommitEffect, {
+        type: "child_returned";
+    }>;
+}>;
+export declare function requireRoleCallChildReturnCommit(commit: RoleCallLedgerCommitResult): RoleCallChildReturnCommit;
+export declare function projectRoleChildReturnContext(ledger: RoleCallLedger, commit: RoleCallLedgerCommitResult): RoleChildReturnContext;

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

@@ -0,0 +1,85 @@
+import { ROLE_CALL_OBJECTIVE_MAX_LENGTH, ROLE_CALL_RESULT_MAX_LENGTH, } from "./contracts.js";
+import { isRuntimeDelegateRoleId, } from "../roles.js";
+export function requireRoleCallChildReturnCommit(commit) {
+    if (!commit.ok || commit.effect.type !== "child_returned") {
+        throw new Error("role_child_return_commit_invalid");
+    }
+    return commit;
+}
+export function projectRoleChildReturnContext(ledger, commit) {
+    const returned = requireRoleCallChildReturnCommit(commit);
+    if (ledger.current() !== returned.head) {
+        throw new Error("role_child_return_commit_invalid");
+    }
+    const { callerCallId, childCallId, resultRef } = returned.effect;
+    const previousCaller = returned.previousHead.state.calls.find((call) => call.callId === callerCallId);
+    const previousChild = returned.previousHead.state.calls.find((call) => call.callId === childCallId);
+    const caller = returned.head.state.calls.find((call) => call.callId === callerCallId);
+    if (returned.previousHead.state.phase !== "running" ||
+        returned.previousHead.state.activeCallId !== childCallId ||
+        previousCaller?.status !== "waiting_for_child" ||
+        previousChild?.status !== "active" ||
+        previousChild.parentCallId !== callerCallId ||
+        returned.head.state.phase !== "running" ||
+        returned.head.state.activeCallId !== callerCallId ||
+        caller?.status !== "active" ||
+        caller.activationCount !== previousCaller.activationCount + 1 ||
+        !caller.childCallIds.includes(childCallId)) {
+        throw new Error("role_child_return_transition_invalid");
+    }
+    const completedChildren = projectCompletedChildren(returned.head.state, caller);
+    const returnedChild = completedChildren.find((child) => child.childCallId === childCallId && child.resultRef === resultRef);
+    if (returnedChild?.childCallId !== childCallId ||
+        returnedChild.resultRef !== resultRef) {
+        throw new Error("role_child_return_result_invalid");
+    }
+    return Object.freeze({
+        callerCallId,
+        invocationAttempt: caller.activationCount,
+        returnedChildCallId: childCallId,
+        returnedResultRef: resultRef,
+        completedChildren: Object.freeze(completedChildren),
+    });
+}
+function projectCompletedChildren(state, caller) {
+    return Object.freeze(caller.childCallIds.map((completedChildCallId) => projectCompletedChild(state, {
+        callerCallId: caller.callId,
+        childCallId: completedChildCallId,
+    })));
+}
+function projectCompletedChild(state, refs) {
+    const child = state.calls.find((call) => call.callId === refs.childCallId);
+    const result = state.results.find((candidate) => candidate.resultRef === child?.resultRef);
+    if (child?.status !== "completed" ||
+        child.parentCallId !== refs.callerCallId ||
+        !child.resultRef ||
+        !isRuntimeDelegateRoleId(child.roleId) ||
+        !isBoundedText(child.objective, ROLE_CALL_OBJECTIVE_MAX_LENGTH) ||
+        result?.producerCallId !== child.callId ||
+        result.roleId !== child.roleId ||
+        (result.outcome !== "completed" && result.outcome !== "failed") ||
+        !isBoundedText(result.summary, ROLE_CALL_RESULT_MAX_LENGTH)) {
+        throw new Error("role_completed_child_projection_invalid");
+    }
+    return Object.freeze({
+        callerCallId: refs.callerCallId,
+        childCallId: child.callId,
+        resultRef: result.resultRef,
+        roleId: result.roleId,
+        objective: child.objective,
+        ...(child.workerCapabilityScope
+            ? { workerCapabilityScope: child.workerCapabilityScope }
+            : {}),
+        ...(child.workingDirectory !== undefined
+            ? { workingDirectory: child.workingDirectory }
+            : {}),
+        dependencyResultRefs: child.dependencyResultRefs,
+        outcome: result.outcome,
+        summary: result.summary,
+    });
+}
+function isBoundedText(value, maximumLength) {
+    return (typeof value === "string" &&
+        value.trim().length > 0 &&
+        value.length <= maximumLength);
+}

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

@@ -0,0 +1,9 @@
+import { type RoleCallLedgerCommand } from "./contracts.js";
+export type DecodedRoleCallCommand = Readonly<{
+    ok: true;
+    value: RoleCallLedgerCommand;
+}> | Readonly<{
+    ok: false;
+    code: "invalid_command" | "supervisor_child_forbidden";
+}>;
+export declare function decodeRoleCallCommand(input: unknown): DecodedRoleCallCommand;