@abot-ai/runtime 1.0.0 → 1.1.0

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

@@ -0,0 +1,339 @@
+import { createHash } from "node:crypto";
+import { exactKeys, isRecord } from "../../validation/strict-record.js";
+import { isRoleCapabilityId, ROLE_CAPABILITY_INVOCATION_CONTROLS_JSON_MAX_LENGTH, ROLE_CAPABILITY_SELECTION_INVOCATION_LIMIT_MAX, } from "./contracts.js";
+import { normalizeEstablishedRoleCallWorkingDirectory } from "./working-directory.js";
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_FINGERPRINT_PATTERN = /^sha256:[a-f0-9]{64}$/;
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_REPEAT_WARNING_COUNT = 2;
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_REPEAT_INTERVENTION_COUNT = 3;
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_REPEAT_LIMIT = 4;
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_WARNING_COUNT = 6;
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_INTERVENTION_COUNT = 7;
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_LIMIT = 8;
+export const ROLE_CAPABILITY_SELECTION_SUPERVISION_RECORD_LIMIT = ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_LIMIT - 1;
+export function createInitialRoleCapabilitySelectionSupervisionState() {
+    return Object.freeze({
+        epoch: null,
+        records: Object.freeze([]),
+    });
+}
+export function createRoleCapabilitySelectionSupervisionFingerprint(input) {
+    if (!isNonNegativeSafeInteger(input.steeringVersion)) {
+        throw new Error("role_capability_selection_supervision_steering_version_invalid");
+    }
+    const canonicalSelection = canonicalizeSupervisedSelection(input.selection);
+    if (!canonicalSelection) {
+        throw new Error("role_capability_selection_supervision_selection_invalid");
+    }
+    const canonical = JSON.stringify({
+        steeringVersion: input.steeringVersion,
+        ...canonicalSelection,
+    });
+    return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+export function assessRoleCapabilitySelectionSupervisionReconsideration(input) {
+    if (!isRoleCapabilitySelectionSupervisionState(input.state)) {
+        throw new Error("role_capability_selection_supervision_state_invalid");
+    }
+    if (!isBoundedCallId(input.callId)) {
+        throw new Error("role_capability_selection_supervision_call_id_invalid");
+    }
+    if (!Number.isSafeInteger(input.invocationAttempt) ||
+        input.invocationAttempt < 1) {
+        throw new Error("role_capability_selection_supervision_invocation_attempt_invalid");
+    }
+    if (!isRoleCapabilitySelectionSupervisionFingerprint(input.receiptFingerprint)) {
+        throw new Error("role_capability_selection_supervision_receipt_fingerprint_invalid");
+    }
+    const epochState = resolveAssessmentEpoch(input);
+    const previousRecord = epochState.records.at(-1);
+    if (previousRecord &&
+        input.invocationAttempt <= previousRecord.invocationAttempt) {
+        throw new Error("role_capability_selection_supervision_invocation_order_invalid");
+    }
+    const supervisionFingerprint = createRoleCapabilitySelectionSupervisionFingerprint({
+        steeringVersion: input.steeringVersion,
+        selection: input.selection,
+    });
+    const identityCount = epochState.records.filter((record) => record.supervisionFingerprint === supervisionFingerprint).length + 1;
+    const totalCount = epochState.records.length + 1;
+    const stageDecision = strongestStageDecision(identityCount, totalCount);
+    const attemptedRecord = Object.freeze({
+        invocationAttempt: input.invocationAttempt,
+        receiptFingerprint: input.receiptFingerprint,
+        supervisionFingerprint,
+    });
+    if (stageDecision.stage === "reject") {
+        return Object.freeze({
+            disposition: "reject",
+            issueCode: "capability_selection_supervision_limit_exceeded",
+            attemptedRecord,
+            supervisionFingerprint,
+            identityCount,
+            totalCount,
+            trigger: stageDecision.trigger,
+        });
+    }
+    const record = Object.freeze({
+        ...attemptedRecord,
+        identityCount,
+        totalCount,
+        stage: stageDecision.stage,
+        trigger: stageDecision.trigger,
+    });
+    const state = Object.freeze({
+        epoch: epochState.epoch,
+        records: Object.freeze([...epochState.records, record]),
+    });
+    return Object.freeze({
+        disposition: stageDecision.stage,
+        state,
+        record,
+        supervisionFingerprint,
+        identityCount,
+        totalCount,
+        trigger: stageDecision.trigger,
+    });
+}
+export function resetRoleCapabilitySelectionSupervisionState() {
+    return createInitialRoleCapabilitySelectionSupervisionState();
+}
+export function replayRoleCapabilitySelectionSupervisionRecords(input) {
+    if (input.epoch === null) {
+        return input.records.length === 0
+            ? createInitialRoleCapabilitySelectionSupervisionState()
+            : undefined;
+    }
+    if (!isRoleCapabilitySelectionSupervisionEpoch(input.epoch))
+        return undefined;
+    if (input.records.length < 1 ||
+        input.records.length > ROLE_CAPABILITY_SELECTION_SUPERVISION_RECORD_LIMIT) {
+        return undefined;
+    }
+    const replayed = [];
+    for (const candidate of input.records) {
+        if (!isRoleCapabilitySelectionSupervisionRecord(candidate))
+            return undefined;
+        const previous = replayed.at(-1);
+        if (previous && candidate.invocationAttempt <= previous.invocationAttempt) {
+            return undefined;
+        }
+        const identityCount = replayed.filter((record) => record.supervisionFingerprint === candidate.supervisionFingerprint).length + 1;
+        const decision = strongestStageDecision(identityCount, replayed.length + 1);
+        if (decision.stage === "reject" ||
+            decision.stage !== candidate.stage ||
+            candidate.identityCount !== identityCount ||
+            candidate.totalCount !== replayed.length + 1 ||
+            candidate.trigger !== decision.trigger) {
+            return undefined;
+        }
+        replayed.push(Object.freeze({ ...candidate }));
+    }
+    return Object.freeze({
+        epoch: Object.freeze({ ...input.epoch }),
+        records: Object.freeze(replayed),
+    });
+}
+export function isRoleCapabilitySelectionSupervisionState(input) {
+    if (!isRecord(input) ||
+        !exactKeys(input, ["epoch", "records"]) ||
+        !Array.isArray(input.records)) {
+        return false;
+    }
+    return (replayRoleCapabilitySelectionSupervisionRecords({
+        epoch: input.epoch,
+        records: input.records,
+    }) !== undefined);
+}
+export function isRoleCapabilitySelectionSupervisionFingerprint(input) {
+    return (typeof input === "string" &&
+        ROLE_CAPABILITY_SELECTION_SUPERVISION_FINGERPRINT_PATTERN.test(input));
+}
+function resolveAssessmentEpoch(input) {
+    if (!isNonNegativeSafeInteger(input.steeringVersion)) {
+        throw new Error("role_capability_selection_supervision_steering_version_invalid");
+    }
+    const epoch = input.state.epoch;
+    if (!epoch) {
+        return createEpochState(input.callId, input.steeringVersion);
+    }
+    if (epoch.callId !== input.callId) {
+        throw new Error("role_capability_selection_supervision_epoch_call_invalid");
+    }
+    if (input.steeringVersion < epoch.steeringVersion) {
+        throw new Error("role_capability_selection_supervision_steering_stale");
+    }
+    return input.steeringVersion === epoch.steeringVersion
+        ? Object.freeze({ epoch, records: input.state.records })
+        : createEpochState(input.callId, input.steeringVersion);
+}
+function createEpochState(callId, steeringVersion) {
+    return Object.freeze({
+        epoch: Object.freeze({ callId, steeringVersion }),
+        records: Object.freeze([]),
+    });
+}
+function strongestStageDecision(identityCount, totalCount) {
+    const repeatStage = repeatStageForCount(identityCount);
+    const totalStage = totalStageForCount(totalCount);
+    const repeatRank = stageRank(repeatStage);
+    const totalRank = stageRank(totalStage);
+    const trigger = totalCount >= ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_WARNING_COUNT &&
+        repeatRank === totalRank
+        ? "repeat_and_total"
+        : totalRank > repeatRank
+            ? "total_budget"
+            : "repeat_identity";
+    return Object.freeze({
+        stage: repeatRank >= totalRank ? repeatStage : totalStage,
+        trigger,
+    });
+}
+function repeatStageForCount(count) {
+    if (count >= ROLE_CAPABILITY_SELECTION_SUPERVISION_REPEAT_LIMIT) {
+        return "reject";
+    }
+    if (count >= ROLE_CAPABILITY_SELECTION_SUPERVISION_REPEAT_INTERVENTION_COUNT) {
+        return "intervened";
+    }
+    return count >= ROLE_CAPABILITY_SELECTION_SUPERVISION_REPEAT_WARNING_COUNT
+        ? "warning"
+        : "tracking";
+}
+function totalStageForCount(count) {
+    if (count >= ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_LIMIT) {
+        return "reject";
+    }
+    if (count >= ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_INTERVENTION_COUNT) {
+        return "intervened";
+    }
+    return count >= ROLE_CAPABILITY_SELECTION_SUPERVISION_TOTAL_WARNING_COUNT
+        ? "warning"
+        : "tracking";
+}
+function stageRank(stage) {
+    return stage === "tracking"
+        ? 0
+        : stage === "warning"
+            ? 1
+            : stage === "intervened"
+                ? 2
+                : 3;
+}
+function canonicalizeSupervisedSelection(selection) {
+    if (!isRecord(selection) || !Array.isArray(selection.invocations)) {
+        return undefined;
+    }
+    const selectionKind = selection.action === "invoke_capability"
+        ? "single"
+        : selection.action === "invoke_capabilities"
+            ? "batch"
+            : undefined;
+    if (!selectionKind ||
+        selection.invocations.length < 1 ||
+        selection.invocations.length >
+            ROLE_CAPABILITY_SELECTION_INVOCATION_LIMIT_MAX ||
+        (selectionKind === "single"
+            ? selection.invocations.length !== 1
+            : selection.invocations.length < 2)) {
+        return undefined;
+    }
+    const workingDirectory = normalizeEffectiveWorkingDirectory(selection.workingDirectory);
+    if (!workingDirectory)
+        return undefined;
+    const invocations = selection.invocations.map((invocation) => {
+        if (!isRecord(invocation) || !isRoleCapabilityId(invocation.capabilityId)) {
+            return undefined;
+        }
+        const selectionControlsJson = canonicalizeControlsJson(invocation.selectionControlsJson);
+        return selectionControlsJson === undefined
+            ? undefined
+            : Object.freeze({
+                capabilityId: invocation.capabilityId,
+                selectionControlsJson,
+            });
+    });
+    if (invocations.some((invocation) => invocation === undefined)) {
+        return undefined;
+    }
+    const canonicalInvocations = invocations;
+    return Object.freeze({
+        selectionKind,
+        workingDirectory,
+        invocations: Object.freeze(selectionKind === "batch"
+            ? [...canonicalInvocations].sort(compareCanonicalInvocation)
+            : canonicalInvocations),
+    });
+}
+function normalizeEffectiveWorkingDirectory(input) {
+    return input === undefined || input === null
+        ? "."
+        : normalizeEstablishedRoleCallWorkingDirectory(input);
+}
+function canonicalizeControlsJson(input) {
+    if (typeof input !== "string" ||
+        input.length < 2 ||
+        input.length > ROLE_CAPABILITY_INVOCATION_CONTROLS_JSON_MAX_LENGTH) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(input);
+        return isRecord(parsed)
+            ? JSON.stringify(canonicalizeJsonValue(parsed))
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function canonicalizeJsonValue(input) {
+    if (Array.isArray(input))
+        return input.map(canonicalizeJsonValue);
+    if (!isRecord(input))
+        return input;
+    return Object.fromEntries(Object.keys(input)
+        .sort()
+        .map((key) => [key, canonicalizeJsonValue(input[key])]));
+}
+function compareCanonicalInvocation(left, right) {
+    const leftJson = JSON.stringify(left);
+    const rightJson = JSON.stringify(right);
+    return leftJson < rightJson ? -1 : leftJson > rightJson ? 1 : 0;
+}
+function isRoleCapabilitySelectionSupervisionEpoch(input) {
+    return (isRecord(input) &&
+        exactKeys(input, ["callId", "steeringVersion"]) &&
+        isBoundedCallId(input.callId) &&
+        isNonNegativeSafeInteger(input.steeringVersion));
+}
+function isRoleCapabilitySelectionSupervisionRecord(input) {
+    return (isRecord(input) &&
+        exactKeys(input, [
+            "invocationAttempt",
+            "receiptFingerprint",
+            "supervisionFingerprint",
+            "identityCount",
+            "totalCount",
+            "stage",
+            "trigger",
+        ]) &&
+        Number.isSafeInteger(input.invocationAttempt) &&
+        input.invocationAttempt >= 1 &&
+        isRoleCapabilitySelectionSupervisionFingerprint(input.receiptFingerprint) &&
+        isRoleCapabilitySelectionSupervisionFingerprint(input.supervisionFingerprint) &&
+        Number.isSafeInteger(input.identityCount) &&
+        input.identityCount >= 1 &&
+        Number.isSafeInteger(input.totalCount) &&
+        input.totalCount >= 1 &&
+        (input.stage === "tracking" ||
+            input.stage === "warning" ||
+            input.stage === "intervened") &&
+        (input.trigger === "repeat_identity" ||
+            input.trigger === "total_budget" ||
+            input.trigger === "repeat_and_total"));
+}
+function isBoundedCallId(input) {
+    return typeof input === "string" && input.length > 0 && input.length <= 256;
+}
+function isNonNegativeSafeInteger(input) {
+    return Number.isSafeInteger(input) && input >= 0;
+}

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

@@ -1,5 +1,7 @@
 import { isRuntimeDelegateRoleId, RUNTIME_ROOT_ROLE_ID } from "../roles.js";
 import { normalizeRoleCapabilitySelectionProjection } from "./capability-selection-reconsideration.js";
+import { isRoleOperationFingerprint, isRoleOperationOutcomeFingerprintForOutcome, } from "./operation-supervision.js";
+import { isReconsiderationCauseBoundToInvocationCount, normalizeRoleCapabilitySelectionReconsiderationCause, } from "./reconsideration-cause.js";
 import { isRoleCapabilityId, } from "./contracts.js";
 import { parseRoleCallPlanBinding } from "./plan.js";
 import { parseRoleCallWorkerCapabilityScope } from "./worker-capability-scope.js";
@@ -124,12 +126,13 @@ export function decodeRoleCallCommand(input) {
                 "declaredEffect",
                 "intent",
                 "controlsJson",
-            ]) &&
+            ], ["actionFingerprint"]) &&
                 input.authority === "active_role" &&
                 typeof input.callId === "string" &&
                 Number.isInteger(input.invocationAttempt) &&
                 typeof input.capabilityId === "string" &&
                 isRoleCapabilityDeclaredEffect(input.declaredEffect) &&
+                isEligibleActionFingerprintInput(input) &&
                 typeof input.intent === "string" &&
                 typeof input.controlsJson === "string"
                 ? {
@@ -143,6 +146,9 @@ export function decodeRoleCallCommand(input) {
                         declaredEffect: input.declaredEffect,
                         intent: input.intent,
                         controlsJson: input.controlsJson,
+                        ...(typeof input.actionFingerprint === "string"
+                            ? { actionFingerprint: input.actionFingerprint }
+                            : {}),
                     },
                 }
                 : { ok: false, code: "invalid_command" };
@@ -158,11 +164,13 @@ export function decodeRoleCallCommand(input) {
                 "observedEffect",
                 "summary",
                 "exactResult",
-            ], ["referenceData", "references"]) &&
+            ], ["outcomeFingerprint", "referenceData", "references"]) &&
                 input.authority === "runtime" &&
                 typeof input.callId === "string" &&
                 typeof input.executionId === "string" &&
                 (input.outcome === "succeeded" || input.outcome === "failed") &&
+                (input.outcomeFingerprint === undefined ||
+                    isRoleOperationOutcomeFingerprintForOutcome(input.outcomeFingerprint, input.outcome)) &&
                 isRoleCapabilityObservedEffect(input.observedEffect) &&
                 typeof input.summary === "string" &&
                 (input.referenceData === undefined ||
@@ -178,6 +186,9 @@ export function decodeRoleCallCommand(input) {
                         callId: input.callId,
                         executionId: input.executionId,
                         outcome: input.outcome,
+                        ...(typeof input.outcomeFingerprint === "string"
+                            ? { outcomeFingerprint: input.outcomeFingerprint }
+                            : {}),
                         observedEffect: input.observedEffect,
                         summary: input.summary,
                         ...(typeof input.referenceData === "string"
@@ -288,6 +299,7 @@ export function decodeRoleCallCommand(input) {
         }
         case "reconsider_capability_selection": {
             const selection = normalizeRoleCapabilitySelectionProjection(input.selection);
+            const cause = normalizeRoleCapabilitySelectionReconsiderationCause(input.cause);
             return exactKeys(input, [
                 "authority",
                 "type",
@@ -295,13 +307,16 @@ export function decodeRoleCallCommand(input) {
                 "invocationAttempt",
                 "steeringVersion",
                 "selection",
+                "cause",
             ]) &&
                 input.authority === "active_role" &&
                 typeof input.callId === "string" &&
                 Number.isInteger(input.invocationAttempt) &&
                 Number.isSafeInteger(input.steeringVersion) &&
                 input.steeringVersion >= 0 &&
-                selection
+                selection &&
+                cause &&
+                isReconsiderationCauseBoundToInvocationCount(cause, selection.invocations.length)
                 ? {
                     ok: true,
                     value: {
@@ -311,6 +326,7 @@ export function decodeRoleCallCommand(input) {
                         invocationAttempt: input.invocationAttempt,
                         steeringVersion: input.steeringVersion,
                         selection,
+                        cause,
                     },
                 }
                 : { ok: false, code: "invalid_command" };
@@ -319,19 +335,20 @@ export function decodeRoleCallCommand(input) {
             return { ok: false, code: "invalid_command" };
     }
 }
+function isEligibleActionFingerprintInput(input) {
+    return (input.actionFingerprint === undefined ||
+        isRoleOperationFingerprint(input.actionFingerprint));
+}
 function parseObservationBatchEntries(input) {
     if (!Array.isArray(input) || input.length < 2)
         return undefined;
     const entries = input.map((entry) => {
         if (!isRecord(entry) ||
-            !exactKeys(entry, [
-                "capabilityId",
-                "declaredEffect",
-                "intent",
-                "controlsJson",
-            ]) ||
+            !exactKeys(entry, ["capabilityId", "declaredEffect", "intent", "controlsJson"], ["actionFingerprint"]) ||
             !isRoleCapabilityId(entry.capabilityId) ||
             entry.declaredEffect !== "observation" ||
+            (entry.actionFingerprint !== undefined &&
+                !isRoleOperationFingerprint(entry.actionFingerprint)) ||
             typeof entry.intent !== "string" ||
             typeof entry.controlsJson !== "string") {
             return undefined;
@@ -341,6 +358,9 @@ function parseObservationBatchEntries(input) {
             declaredEffect: "observation",
             intent: entry.intent,
             controlsJson: entry.controlsJson,
+            ...(typeof entry.actionFingerprint === "string"
+                ? { actionFingerprint: entry.actionFingerprint }
+                : {}),
         });
     });
     return entries.some((entry) => entry === undefined)
@@ -356,11 +376,13 @@ function parseCapabilityBatchSettlements(input) {
             ? parseOptionalCapabilityAdapterResult(entry.exactResult)
             : null;
         if (!isRecord(entry) ||
-            !exactKeys(entry, ["executionId", "outcome", "observedEffect", "summary", "exactResult"], ["referenceData", "references"]) ||
+            !exactKeys(entry, ["executionId", "outcome", "observedEffect", "summary", "exactResult"], ["outcomeFingerprint", "referenceData", "references"]) ||
             typeof entry.executionId !== "string" ||
             entry.executionId.length === 0 ||
             seen.has(entry.executionId) ||
             (entry.outcome !== "succeeded" && entry.outcome !== "failed") ||
+            (entry.outcomeFingerprint !== undefined &&
+                !isRoleOperationOutcomeFingerprintForOutcome(entry.outcomeFingerprint, entry.outcome)) ||
             !isRoleCapabilityObservedEffect(entry.observedEffect) ||
             typeof entry.summary !== "string" ||
             (entry.referenceData !== undefined &&
@@ -375,6 +397,9 @@ function parseCapabilityBatchSettlements(input) {
         return Object.freeze({
             executionId: entry.executionId,
             outcome: entry.outcome,
+            ...(typeof entry.outcomeFingerprint === "string"
+                ? { outcomeFingerprint: entry.outcomeFingerprint }
+                : {}),
             observedEffect: entry.observedEffect,
             summary: entry.summary,
             ...(typeof entry.referenceData === "string"

package/dist/src/runtime/orchestration/role-calls/command-dispatch/active-capability-caller.d.ts

@@ -0,0 +1,6 @@
+import type { RoleCallFrame, RoleCallPolicy, RoleCallState } from "../contracts.js";
+export declare function findActiveCapabilityCaller(params: {
+    state: RoleCallState;
+    policy: RoleCallPolicy;
+    callId: string;
+}): RoleCallFrame | undefined;

package/dist/src/runtime/orchestration/role-calls/command-dispatch/active-capability-caller.js

@@ -0,0 +1,15 @@
+import { hasCapabilityAuthority } from "../candidate-validation.js";
+import { findCall } from "../reducer-primitives.js";
+export function findActiveCapabilityCaller(params) {
+    if (params.state.phase !== "running")
+        return undefined;
+    if (params.state.activeCallId !== params.callId)
+        return undefined;
+    const call = findCall(params.state, params.callId);
+    if (call?.status !== "active")
+        return undefined;
+    if (!hasCapabilityAuthority(params.policy.authority, params.state, call)) {
+        return undefined;
+    }
+    return call;
+}

package/dist/src/runtime/orchestration/role-calls/command-dispatch/call-frame-state.d.ts

@@ -0,0 +1,3 @@
+import type { RoleCallFrame, RoleCallState } from "../contracts.js";
+export declare function replaceCall(calls: readonly RoleCallFrame[], replacement: RoleCallFrame): RoleCallFrame[];
+export declare function nextCallId(state: RoleCallState): string;

package/dist/src/runtime/orchestration/role-calls/command-dispatch/call-frame-state.js

@@ -0,0 +1,6 @@
+export function replaceCall(calls, replacement) {
+    return calls.map((call) => call.callId === replacement.callId ? replacement : call);
+}
+export function nextCallId(state) {
+    return `call-${state.callSequence + 1}`;
+}

package/dist/src/runtime/orchestration/role-calls/command-dispatch/call-scope-transitions.d.ts

@@ -0,0 +1,3 @@
+import type { EstablishRoleCallWorkingDirectoryCommand, RoleCallPolicy, RoleCallState, RoleCallTransitionResult, UpdateRoleCapabilityScopeCommand } from "../contracts.js";
+export declare function establishWorkingDirectory(state: RoleCallState, command: EstablishRoleCallWorkingDirectoryCommand, policy: RoleCallPolicy): RoleCallTransitionResult;
+export declare function updateCapabilityScope(state: RoleCallState, command: UpdateRoleCapabilityScopeCommand, policy: RoleCallPolicy): RoleCallTransitionResult;

package/dist/src/runtime/orchestration/role-calls/command-dispatch/call-scope-transitions.js

@@ -0,0 +1,86 @@
+import { resetRoleCapabilitySelectionSupervisionState } from "../capability-selection-supervision.js";
+import { commit, reject } from "../reducer-primitives.js";
+import { parseRoleCallWorkerCapabilityScope } from "../worker-capability-scope.js";
+import { normalizeEstablishedRoleCallWorkingDirectory } from "../working-directory.js";
+import { findActiveCapabilityCaller } from "./active-capability-caller.js";
+import { replaceCall } from "./call-frame-state.js";
+export function establishWorkingDirectory(state, command, policy) {
+    const { callId, invocationAttempt, workingDirectory } = command;
+    const call = findActiveCapabilityCaller({ state, policy, callId });
+    if (!canEstablishWorkingDirectory(call, invocationAttempt)) {
+        return reject(state, "working_directory_establishment_invalid");
+    }
+    const normalized = normalizeEstablishedRoleCallWorkingDirectory(workingDirectory);
+    if (!normalized) {
+        return reject(state, "working_directory_establishment_invalid");
+    }
+    return commit({
+        ...state,
+        capabilitySelectionSupervision: resetRoleCapabilitySelectionSupervisionState(),
+        calls: replaceCall(state.calls, {
+            ...call,
+            workingDirectory: normalized,
+        }),
+    }, { type: "working_directory_established", callId });
+}
+export function updateCapabilityScope(state, command, policy) {
+    const { callId, invocationAttempt, mode, catalogGroupIds } = command;
+    const call = findActiveCapabilityCaller({ state, policy, callId });
+    if (!call) {
+        return reject(state, "capability_caller_invalid");
+    }
+    if (call.activationCount !== invocationAttempt) {
+        return reject(state, "capability_invocation_mismatch");
+    }
+    const requestedScope = parseRoleCallWorkerCapabilityScope({
+        catalogGroupIds,
+    });
+    if (!requestedScope) {
+        return reject(state, "invalid_command");
+    }
+    const nextScope = resolveCapabilityScopeUpdate(mode, call.workerCapabilityScope, requestedScope);
+    if (!nextScope) {
+        return reject(state, "capability_scope_update_invalid");
+    }
+    return commit({
+        ...state,
+        capabilitySelectionSupervision: resetRoleCapabilitySelectionSupervisionState(),
+        calls: replaceCall(state.calls, {
+            ...call,
+            workerCapabilityScope: nextScope,
+            activationCount: call.activationCount + 1,
+        }),
+    }, {
+        type: "capability_scope_updated",
+        callId,
+        mode,
+        catalogGroupIds: nextScope.catalogGroupIds,
+    });
+}
+function canEstablishWorkingDirectory(call, invocationAttempt) {
+    if (!call)
+        return false;
+    if (call.activationCount !== invocationAttempt)
+        return false;
+    return call.workingDirectory === undefined;
+}
+function resolveCapabilityScopeUpdate(mode, currentScope, requestedScope) {
+    if (mode === "open" && currentScope !== undefined)
+        return undefined;
+    if (mode === "open")
+        return requestedScope;
+    if (!currentScope)
+        return undefined;
+    if (hasOverlappingCapabilityCatalogGroups(currentScope, requestedScope)) {
+        return undefined;
+    }
+    return parseRoleCallWorkerCapabilityScope({
+        catalogGroupIds: [
+            ...currentScope.catalogGroupIds,
+            ...requestedScope.catalogGroupIds,
+        ],
+    });
+}
+function hasOverlappingCapabilityCatalogGroups(currentScope, requestedScope) {
+    return requestedScope.catalogGroupIds.some((groupId) => currentScope.catalogGroupIds.includes(groupId));
+}

package/dist/src/runtime/orchestration/role-calls/command-dispatch/capability-batch-transitions.d.ts

@@ -0,0 +1,3 @@
+import { type BeginRoleCapabilityBatchCommand, type RoleCallPolicy, type RoleCallState, type RoleCallTransitionResult, type SettleRoleCapabilityBatchCommand } from "../contracts.js";
+export declare function beginCapabilityBatch(state: RoleCallState, command: BeginRoleCapabilityBatchCommand, policy: RoleCallPolicy): RoleCallTransitionResult;
+export declare function settleCapabilityBatch(state: RoleCallState, command: SettleRoleCapabilityBatchCommand, policy: RoleCallPolicy): RoleCallTransitionResult;