@abot-ai/runtime 1.0.0 → 1.1.0

package/dist/src/runtime/orchestration/role-executors/activation/state-validation.js

@@ -1,3 +1,4 @@
+import { isSameRoleOperationIdentity } from "../../role-calls/index.js";
 import { isRuntimeDelegateRoleId } from "../../roles.js";
 import { sameCallFrame, sameCallIdentity, } from "../shared/runtime-invariants.js";
 export function resolveCurrentCall(params) {
@@ -46,7 +47,9 @@ export function validateCapabilityContinuation(params) {
             afterState.capabilityExecutionSequence !==
                 beforeState.capabilityExecutionSequence + params.executionIds.length ||
             afterState.activeCallId !== params.currentCall.callId ||
-            afterState.results !== beforeState.results) {
+            afterState.results !== beforeState.results ||
+            afterState.capabilitySelectionSupervision.epoch !== null ||
+            afterState.capabilitySelectionSupervision.records.length !== 0) {
             return { ok: false, issueCode: "ledger_progress_invalid" };
         }
         if (afterState.calls.length !== beforeState.calls.length) {
@@ -105,6 +108,139 @@ export function validateCapabilityContinuation(params) {
         return { ok: false, issueCode: "continuation_state_invalid" };
     }
 }
+export function validateOperationSupervisionInterventionContinuation(params) {
+    try {
+        const commitIssue = validateOperationSupervisionInterventionCommit(params);
+        if (commitIssue)
+            return { ok: false, issueCode: commitIssue };
+        const progressIssue = validateOperationSupervisionInterventionProgress(params);
+        if (progressIssue)
+            return { ok: false, issueCode: progressIssue };
+        const nextCall = params.after.state.calls.find((candidate) => candidate.callId === params.currentCall.callId);
+        if (!nextCall)
+            return { ok: false, issueCode: "call_unavailable" };
+        const callIssue = validateIntervenedCall({
+            before: params.before,
+            after: params.after,
+            currentCall: params.currentCall,
+            nextCall,
+        });
+        if (callIssue)
+            return { ok: false, issueCode: callIssue };
+        const supervisionIssue = validateOperationSupervisionTransition(params);
+        if (supervisionIssue) {
+            return { ok: false, issueCode: supervisionIssue };
+        }
+        return { ok: true, call: nextCall };
+    }
+    catch {
+        return { ok: false, issueCode: "continuation_state_invalid" };
+    }
+}
+function validateOperationSupervisionInterventionCommit(params) {
+    const { commit } = params;
+    if (commit.previousHead !== params.before || commit.head !== params.after) {
+        return "continuation_commit_mismatch";
+    }
+    if (commit.effect.type !== "operation_supervision_intervened") {
+        return "continuation_effect_invalid";
+    }
+    if (commit.effect.callId !== params.currentCall.callId ||
+        commit.effect.invocationAttempt !== params.currentCall.activationCount ||
+        commit.effect.matchingOutcomeCount !== 2 ||
+        commit.effect.interventionCount !== 1) {
+        return "continuation_effect_mismatch";
+    }
+    return undefined;
+}
+function validateOperationSupervisionInterventionProgress(params) {
+    if (params.after === params.before)
+        return "ledger_not_advanced";
+    if (params.after.revision !== params.before.revision + 1) {
+        return "revision_advance_invalid";
+    }
+    if (params.after.kind !== params.before.kind)
+        return "ledger_kind_changed";
+    if (params.after.policy !== params.before.policy)
+        return "policy_changed";
+    const beforeState = params.before.state;
+    const afterState = params.after.state;
+    const unrelatedStateChanged = afterState.contractVersion !== beforeState.contractVersion ||
+        afterState.requestId !== beforeState.requestId ||
+        afterState.phase !== beforeState.phase ||
+        afterState.phase !== "running" ||
+        afterState.rootCallId !== beforeState.rootCallId ||
+        afterState.rootResponse !== beforeState.rootResponse ||
+        afterState.callSequence !== beforeState.callSequence ||
+        afterState.resultSequence !== beforeState.resultSequence ||
+        afterState.capabilityExecutionSequence !==
+            beforeState.capabilityExecutionSequence ||
+        afterState.activeCallId !== params.currentCall.callId ||
+        afterState.results !== beforeState.results ||
+        afterState.plans !== beforeState.plans ||
+        afterState.capabilityExecutions !== beforeState.capabilityExecutions ||
+        afterState.capabilitySelectionSupervision.epoch !== null ||
+        afterState.capabilitySelectionSupervision.records.length !== 0;
+    return unrelatedStateChanged ? "ledger_progress_invalid" : undefined;
+}
+function validateIntervenedCall(params) {
+    if (params.after.state.calls.length !== params.before.state.calls.length) {
+        return "call_set_changed";
+    }
+    const callDidNotAdvanceExactlyOnce = params.nextCall.status !== "active" ||
+        params.nextCall.activationCount !==
+            params.currentCall.activationCount + 1 ||
+        params.nextCall.lastCapabilitySelectionReconsideration !==
+            params.currentCall.lastCapabilitySelectionReconsideration ||
+        !sameCallIdentity(params.nextCall, params.currentCall);
+    if (callDidNotAdvanceExactlyOnce)
+        return "activation_advance_invalid";
+    const unrelatedCallChanged = params.before.state.calls.some((beforeCall) => beforeCall.callId !== params.currentCall.callId &&
+        params.after.state.calls.find((candidate) => candidate.callId === beforeCall.callId) !== beforeCall);
+    return unrelatedCallChanged ? "unrelated_call_changed" : undefined;
+}
+function validateOperationSupervisionTransition(params) {
+    const beforeSupervision = params.before.state.operationSupervision;
+    const afterSupervision = params.after.state.operationSupervision;
+    const effect = params.commit.effect;
+    const entryIndex = beforeSupervision.entries.findIndex((entry) => isSameRoleOperationIdentity(entry, effect));
+    const beforeEntry = beforeSupervision.entries[entryIndex];
+    const afterEntry = afterSupervision.entries[entryIndex];
+    const unrelatedEntryChanged = beforeSupervision.entries.some((entry, index) => index !== entryIndex && afterSupervision.entries[index] !== entry);
+    const interventionRecord = afterSupervision.interventions[afterSupervision.interventions.length - 1];
+    const interventionHistoryChangedAppendOnly = afterSupervision.interventions.length ===
+        beforeSupervision.interventions.length + 1 &&
+        beforeSupervision.interventions.every((intervention, index) => afterSupervision.interventions[index] === intervention);
+    const transitionDoesNotMatchEffect = afterSupervision === beforeSupervision ||
+        entryIndex < 0 ||
+        afterSupervision.entries.length !== beforeSupervision.entries.length ||
+        unrelatedEntryChanged ||
+        beforeEntry?.stage !== "warning" ||
+        !hasMatchingOperationSupervisionEvidence(beforeEntry, effect) ||
+        afterEntry === beforeEntry ||
+        afterEntry?.stage !== "intervened" ||
+        !hasMatchingOperationSupervisionEvidence(afterEntry, effect) ||
+        !hasMatchingOperationSupervisionIntervention(afterEntry, effect) ||
+        !interventionHistoryChangedAppendOnly ||
+        !interventionRecord ||
+        !hasMatchingOperationSupervisionEvidence(interventionRecord, effect) ||
+        !hasMatchingOperationSupervisionIntervention(interventionRecord, effect);
+    return transitionDoesNotMatchEffect
+        ? "operation_supervision_state_invalid"
+        : undefined;
+}
+function hasMatchingOperationSupervisionEvidence(evidence, effect) {
+    return (isSameRoleOperationIdentity(evidence, effect) &&
+        evidence.priorOutcome === effect.priorOutcome &&
+        evidence.outcomeFingerprint === effect.outcomeFingerprint &&
+        evidence.originExecutionId === effect.originExecutionId &&
+        evidence.matchingOutcomeCount === effect.matchingOutcomeCount);
+}
+function hasMatchingOperationSupervisionIntervention(intervention, effect) {
+    return (intervention.interventionCount === effect.interventionCount &&
+        intervention.interventionCallId === effect.callId &&
+        intervention.interventionInvocationAttempt === effect.invocationAttempt);
+}
 function validateSettledExecution(params) {
     const execution = params.execution;
     if (!execution)

package/dist/src/runtime/orchestration/role-executors/contracts.d.ts

@@ -1,4 +1,4 @@
-import type { RoleCallChildReturnCommit, RoleCallFrame, RoleCallLedger, RoleCallLedgerHead, RoleCallPlanBinding, RoleCallWorkerCapabilityScope } from "../role-calls/index.js";
+import type { RoleCallChildReturnCommit, RoleCallFrame, RoleCallLedger, RoleCallLedgerHead, RoleCallOperationSupervisionInterventionCommit, RoleCallPlanBinding, RoleCallWorkerCapabilityScope } from "../role-calls/index.js";
 import type { RuntimeDelegateRoleId } from "../roles.js";
 export type RoleExecutionOutcome = "completed" | "failed";
 export type RoleExecutionResult<TValue = unknown> = Readonly<{
@@ -19,14 +19,18 @@ export type RoleCapabilityBatchExecutionContinuationReference = Readonly<{
     kind: "capability_batch_execution";
     executionIds: readonly string[];
 }>;
+export type RoleOperationSupervisionInterventionContinuation = Readonly<{
+    kind: "operation_supervision_intervention";
+    commit: RoleCallOperationSupervisionInterventionCommit;
+}>;
 export type RoleChildContinuationReference = Readonly<{
     kind: "role_child";
     commit: RoleCallChildReturnCommit;
 }>;
-export type RoleExecutionContinuationReference = RoleCapabilityExecutionContinuationReference | RoleCapabilityBatchExecutionContinuationReference | RoleChildContinuationReference;
+export type RoleExecutionContinuationReference = RoleCapabilityExecutionContinuationReference | RoleCapabilityBatchExecutionContinuationReference | RoleOperationSupervisionInterventionContinuation | RoleChildContinuationReference;
 export type RoleExecutionContinuation = Readonly<{
     kind: "continue";
-    continuation: RoleCapabilityExecutionContinuationReference | RoleCapabilityBatchExecutionContinuationReference;
+    continuation: RoleCapabilityExecutionContinuationReference | RoleCapabilityBatchExecutionContinuationReference | RoleOperationSupervisionInterventionContinuation;
 }>;
 export type RoleExecutionChildInvocation = Readonly<{
     kind: "invoke_role";

package/dist/src/runtime/orchestration/role-executors/diagnostics.d.ts

@@ -26,6 +26,7 @@ export declare function traceRoleExecutorCompleted(context: RoleExecutorDiagnost
     turnCount: number;
 }>): void;
 export declare function traceRoleExecutorContinued(context: RoleExecutorDiagnosticContext, params: Readonly<{
+    continuationKind: "capability_execution" | "capability_batch_execution" | "operation_supervision_intervention";
     executionId?: string;
     executionIds?: readonly string[];
     fromActivation: number;
@@ -88,6 +89,7 @@ export declare function traceRoleExecutorChildRejected(context: RoleExecutorDiag
     turnCount: number;
 }>): void;
 export declare function traceRoleExecutorContinuationRejected(context: RoleExecutorDiagnosticContext, params: Readonly<{
+    continuationKind: "capability_execution" | "capability_batch_execution" | "operation_supervision_intervention";
     issueCode: string;
     executionId?: string;
     executionIds?: readonly string[];

package/dist/src/runtime/orchestration/role-executors/diagnostics.js

@@ -33,9 +33,6 @@ export function traceRoleExecutorCompleted(context, result) {
 export function traceRoleExecutorContinued(context, params) {
     traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "executor.continued", {
         ...projectCall(context),
-        continuationKind: params.executionIds
-            ? "capability_batch_execution"
-            : "capability_execution",
         ...params,
     });
 }
@@ -76,9 +73,7 @@ export function traceRoleExecutorChildRejected(context, params) {
 export function traceRoleExecutorContinuationRejected(context, params) {
     traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "continuation.rejected", {
         ...projectCall(context),
-        continuationKind: params.executionIds
-            ? "capability_batch_execution"
-            : "capability_execution",
+        continuationKind: params.continuationKind,
         issueCode: params.issueCode,
         ...(params.executionId ? { executionId: params.executionId } : {}),
         ...(params.executionIds ? { executionIds: params.executionIds } : {}),

package/dist/src/runtime/orchestration/worker-capabilities/batch-selection.d.ts

@@ -0,0 +1,10 @@
+type CapabilityBatchSelectionCandidate = Readonly<{
+    capabilityId: string;
+}>;
+/**
+ * Full invocation identity is available only after controls and payloads are
+ * materialized. Any offered observation capability can therefore participate
+ * in a batch; exact duplicates are coalesced at execution admission.
+ */
+export declare function canOfferWorkerCapabilityBatchSelection(capabilities: readonly CapabilityBatchSelectionCandidate[]): boolean;
+export {};

package/dist/src/runtime/orchestration/worker-capabilities/batch-selection.js

@@ -0,0 +1,8 @@
+/**
+ * Full invocation identity is available only after controls and payloads are
+ * materialized. Any offered observation capability can therefore participate
+ * in a batch; exact duplicates are coalesced at execution admission.
+ */
+export function canOfferWorkerCapabilityBatchSelection(capabilities) {
+    return capabilities.length > 0;
+}

package/dist/src/runtime/orchestration/worker-capabilities/binding/adapter-catalog.d.ts

@@ -0,0 +1,14 @@
+import type { RoleCallFrame } from "../../role-calls/index.js";
+import { type WorkerCapabilityAdapter, type WorkerCapabilityDescriptor } from "../contracts.js";
+import { type WorkerCapabilityDiagnosticContext } from "../diagnostics.js";
+import { type WorkerCapabilityScopeProjection } from "../scope.js";
+export type BoundCapabilityCatalog<TContext> = Readonly<{
+    capabilities: readonly WorkerCapabilityDescriptor[];
+    byCapabilityId: ReadonlyMap<string, WorkerCapabilityAdapter<TContext>>;
+    capabilityScope: WorkerCapabilityScopeProjection<WorkerCapabilityAdapter<TContext>>;
+}>;
+export declare function createBoundCapabilityCatalog<TContext>(params: {
+    adapters: readonly WorkerCapabilityAdapter<TContext>[];
+    boundCall: RoleCallFrame;
+    emptyDiagnostic: WorkerCapabilityDiagnosticContext;
+}): BoundCapabilityCatalog<TContext>;

package/dist/src/runtime/orchestration/worker-capabilities/binding/adapter-catalog.js

@@ -0,0 +1,76 @@
+import { WORKER_CAPABILITY_COUNT_MAX, } from "../contracts.js";
+import { traceWorkerCapabilityBindingRejected, } from "../diagnostics.js";
+import { projectWorkerCapabilityCatalogGroups, projectWorkerCapabilityScope, WorkerCapabilityScopeError, } from "../scope.js";
+import { normalizeCapabilityAdapter } from "./adapter-normalization.js";
+import { workerCapabilityBindingRejection } from "./binding-rejection.js";
+export function createBoundCapabilityCatalog(params) {
+    assertValidCapabilityCount(params.adapters, params.emptyDiagnostic);
+    const boundAdapters = normalizeCapabilityAdapters(params.adapters, params.emptyDiagnostic);
+    const capabilityScope = projectBoundCapabilityScope({
+        boundAdapters,
+        boundCall: params.boundCall,
+        emptyDiagnostic: params.emptyDiagnostic,
+    });
+    const scopedAdapters = capabilityScope.entries;
+    return Object.freeze({
+        capabilities: Object.freeze(scopedAdapters.map((adapter) => adapter.descriptor)),
+        byCapabilityId: new Map(scopedAdapters.map((adapter) => [
+            adapter.descriptor.capabilityId,
+            adapter,
+        ])),
+        capabilityScope,
+    });
+}
+function assertValidCapabilityCount(adapters, diagnostic) {
+    const hasInvalidCapabilityCount = !Array.isArray(adapters) || adapters.length > WORKER_CAPABILITY_COUNT_MAX;
+    if (!hasInvalidCapabilityCount)
+        return;
+    traceWorkerCapabilityBindingRejected(diagnostic, "capability_count_invalid");
+    throw workerCapabilityBindingRejection("capability_count_invalid");
+}
+function normalizeCapabilityAdapters(adapters, diagnostic) {
+    const normalizedAdapters = [];
+    const seenCapabilityIds = new Set();
+    for (const adapter of adapters) {
+        const normalized = normalizeCapabilityAdapter(adapter);
+        if (!normalized.ok) {
+            rejectAdapterCatalog(diagnostic, seenCapabilityIds, normalized.issueCode);
+        }
+        const capabilityId = normalized.value.descriptor.capabilityId;
+        if (seenCapabilityIds.has(capabilityId)) {
+            rejectAdapterCatalog(diagnostic, seenCapabilityIds, "duplicate_capability_id");
+        }
+        seenCapabilityIds.add(capabilityId);
+        normalizedAdapters.push(normalized.value);
+    }
+    return normalizedAdapters;
+}
+function projectBoundCapabilityScope(params) {
+    const knownCatalogGroups = projectWorkerCapabilityCatalogGroups(params.boundAdapters.map((adapter) => adapter.descriptor));
+    try {
+        return projectWorkerCapabilityScope({
+            entries: params.boundAdapters,
+            scope: params.boundCall.workerCapabilityScope,
+            descriptorOf: (adapter) => adapter.descriptor,
+        });
+    }
+    catch (error) {
+        const issueCode = error instanceof WorkerCapabilityScopeError
+            ? error.issueCode
+            : "capability_scope_projection_invalid";
+        traceWorkerCapabilityBindingRejected({
+            ...params.emptyDiagnostic,
+            capabilityIds: Object.freeze(params.boundAdapters.map((adapter) => adapter.descriptor.capabilityId)),
+            knownCatalogGroupCount: knownCatalogGroups.length,
+            fullCapabilityCount: params.boundAdapters.length,
+        }, issueCode);
+        throw workerCapabilityBindingRejection(issueCode);
+    }
+}
+function rejectAdapterCatalog(diagnostic, seenCapabilityIds, issueCode) {
+    traceWorkerCapabilityBindingRejected({
+        ...diagnostic,
+        capabilityIds: Object.freeze([...seenCapabilityIds]),
+    }, issueCode);
+    throw workerCapabilityBindingRejection(issueCode);
+}

package/dist/src/runtime/orchestration/worker-capabilities/binding/adapter-normalization.d.ts

@@ -0,0 +1,10 @@
+import { type WorkerCapabilityAdapter } from "../contracts.js";
+type AdapterNormalization<TContext> = Readonly<{
+    ok: true;
+    value: WorkerCapabilityAdapter<TContext>;
+}> | Readonly<{
+    ok: false;
+    issueCode: string;
+}>;
+export declare function normalizeCapabilityAdapter<TContext>(adapter: WorkerCapabilityAdapter<TContext>): AdapterNormalization<TContext>;
+export {};

package/dist/src/runtime/orchestration/worker-capabilities/binding/adapter-normalization.js

@@ -0,0 +1,160 @@
+import { isToolCatalogGroupId } from "../../../../capabilities/tool-types.js";
+import { isRoleCapabilityId } from "../../role-calls/index.js";
+import { WORKER_CAPABILITY_CONTROL_COUNT_MAX, WORKER_CAPABILITY_CONTROL_ID_MAX_LENGTH, WORKER_CAPABILITY_SUMMARY_MAX_LENGTH, } from "../contracts.js";
+import { normalizeWorkerCapabilityControlsSchema } from "../controls.js";
+import { partitionWorkerCapabilityControlsSchema } from "../selection-controls.js";
+export function normalizeCapabilityAdapter(adapter) {
+    if (!isRecordObject(adapter)) {
+        return { ok: false, issueCode: "adapter_invalid" };
+    }
+    const descriptor = normalizeCapabilityDescriptor(adapter.descriptor);
+    if (!descriptor.ok)
+        return descriptor;
+    if (typeof adapter.execute !== "function") {
+        return { ok: false, issueCode: "adapter_execute_missing" };
+    }
+    if (adapter.prepare !== undefined && typeof adapter.prepare !== "function") {
+        return { ok: false, issueCode: "adapter_prepare_invalid" };
+    }
+    return {
+        ok: true,
+        value: Object.freeze({
+            descriptor: descriptor.value,
+            ...(adapter.prepare ? { prepare: adapter.prepare } : {}),
+            execute: adapter.execute,
+        }),
+    };
+}
+function normalizeCapabilityDescriptor(descriptor) {
+    if (!isRecordObject(descriptor)) {
+        return { ok: false, issueCode: "descriptor_invalid" };
+    }
+    if (!isRoleCapabilityId(descriptor.capabilityId)) {
+        return { ok: false, issueCode: "descriptor_capability_id_invalid" };
+    }
+    if (!hasValidDescriptorSummary(descriptor.summary)) {
+        return { ok: false, issueCode: "descriptor_summary_invalid" };
+    }
+    if (!isWorkerCapabilityEffect(descriptor.effect)) {
+        return { ok: false, issueCode: "descriptor_effect_invalid" };
+    }
+    const controls = normalizeWorkerCapabilityControlsSchema(descriptor.controls);
+    if (!controls.ok) {
+        return { ok: false, issueCode: `descriptor_${controls.issueCode}` };
+    }
+    const runtimePathControlIds = normalizeRuntimePathControlIds(controls.value, descriptor.runtimePathControlIds);
+    if (!runtimePathControlIds.ok) {
+        return {
+            ok: false,
+            issueCode: `descriptor_${runtimePathControlIds.issueCode}`,
+        };
+    }
+    const controlsPartition = partitionWorkerCapabilityControlsSchema(controls.value, descriptor.selectionControlIds);
+    if (!controlsPartition.ok) {
+        return {
+            ok: false,
+            issueCode: `descriptor_${controlsPartition.issueCode}`,
+        };
+    }
+    if (!hasValidControlsRefinement(descriptor.controlsRefinement)) {
+        return { ok: false, issueCode: "descriptor_controls_refinement_invalid" };
+    }
+    if (!hasValidPayloadAuthoringRequirement(descriptor.requiresPayloadAuthoringObjective)) {
+        return {
+            ok: false,
+            issueCode: "descriptor_payload_authoring_objective_invalid",
+        };
+    }
+    const catalogGroups = descriptor.catalogGroups ?? ["other"];
+    if (!hasValidCatalogGroups(catalogGroups)) {
+        return { ok: false, issueCode: "descriptor_catalog_groups_invalid" };
+    }
+    return {
+        ok: true,
+        value: Object.freeze({
+            capabilityId: descriptor.capabilityId,
+            summary: descriptor.summary.trim(),
+            effect: descriptor.effect,
+            controls: controls.value,
+            ...(runtimePathControlIds.value.length > 0
+                ? { runtimePathControlIds: runtimePathControlIds.value }
+                : {}),
+            ...(controlsPartition.value.selectionControlIds.length > 0
+                ? { selectionControlIds: controlsPartition.value.selectionControlIds }
+                : {}),
+            ...(descriptor.controlsRefinement
+                ? { controlsRefinement: descriptor.controlsRefinement }
+                : {}),
+            ...(descriptor.requiresPayloadAuthoringObjective
+                ? { requiresPayloadAuthoringObjective: true }
+                : {}),
+            catalogGroups: Object.freeze([...catalogGroups]),
+        }),
+    };
+}
+function normalizeRuntimePathControlIds(controls, input) {
+    if (input === undefined) {
+        return { ok: true, value: Object.freeze([]) };
+    }
+    if (!hasValidRuntimePathControlIdCount(input)) {
+        return { ok: false, issueCode: "runtime_path_control_ids_invalid" };
+    }
+    const seen = new Set();
+    for (const controlId of input) {
+        if (!isValidRuntimePathControlId(controlId)) {
+            return { ok: false, issueCode: "runtime_path_control_ids_invalid" };
+        }
+        if (seen.has(controlId)) {
+            return { ok: false, issueCode: "runtime_path_control_ids_duplicate" };
+        }
+        if (!Object.hasOwn(controls.properties, controlId)) {
+            return { ok: false, issueCode: "runtime_path_control_unknown" };
+        }
+        seen.add(controlId);
+    }
+    return { ok: true, value: Object.freeze([...input]) };
+}
+function isRecordObject(input) {
+    return typeof input === "object" && input !== null && !Array.isArray(input);
+}
+function hasValidDescriptorSummary(summary) {
+    if (typeof summary !== "string")
+        return false;
+    if (summary.trim().length === 0)
+        return false;
+    return summary.length <= WORKER_CAPABILITY_SUMMARY_MAX_LENGTH;
+}
+function hasValidControlsRefinement(input) {
+    return input === undefined || input === "mechanical_when_complete";
+}
+function hasValidPayloadAuthoringRequirement(input) {
+    return input === undefined || input === true;
+}
+function hasValidCatalogGroups(input) {
+    if (!Array.isArray(input))
+        return false;
+    if (input.length === 0)
+        return false;
+    if (new Set(input).size !== input.length)
+        return false;
+    return input.every((catalogGroup) => isToolCatalogGroupId(catalogGroup));
+}
+function hasValidRuntimePathControlIdCount(input) {
+    if (!Array.isArray(input))
+        return false;
+    if (input.length === 0)
+        return false;
+    return input.length <= WORKER_CAPABILITY_CONTROL_COUNT_MAX;
+}
+function isValidRuntimePathControlId(controlId) {
+    if (typeof controlId !== "string")
+        return false;
+    if (controlId.length === 0)
+        return false;
+    if (controlId.length > WORKER_CAPABILITY_CONTROL_ID_MAX_LENGTH)
+        return false;
+    return controlId.trim() === controlId;
+}
+function isWorkerCapabilityEffect(input) {
+    return input === "observation" || input === "mutation" || input === "mixed";
+}

package/dist/src/runtime/orchestration/worker-capabilities/binding/binding-rejection.d.ts

@@ -0,0 +1,2 @@
+export declare function workerCapabilityBindingRejection(issueCode: string): Error;
+export declare function isWorkerCapabilityBindingRejection(error: unknown): error is Error;

package/dist/src/runtime/orchestration/worker-capabilities/binding/binding-rejection.js

@@ -0,0 +1,8 @@
+const WORKER_CAPABILITY_REJECTION_PREFIX = "worker_capability_rejected:";
+export function workerCapabilityBindingRejection(issueCode) {
+    return new Error(`${WORKER_CAPABILITY_REJECTION_PREFIX}${issueCode}`);
+}
+export function isWorkerCapabilityBindingRejection(error) {
+    return (error instanceof Error &&
+        error.message.startsWith(WORKER_CAPABILITY_REJECTION_PREFIX));
+}

package/dist/src/runtime/orchestration/worker-capabilities/binding/bound-capability-session.d.ts

@@ -0,0 +1,24 @@
+import { type RoleCallDependencyResult, type RoleCallFrame, type RoleCallLedger } from "../../role-calls/index.js";
+import type { WorkerCapabilityAdapter, WorkerCapabilityBinding, WorkerCapabilityDescriptor, WorkerCapabilityExecutionFreshness } from "../contracts.js";
+import type { WorkerCapabilityDiagnosticContext } from "../diagnostics.js";
+import type { WorkerCapabilityScopeProjection } from "../scope.js";
+/**
+ * Immutable request/call-scoped capability facade. Authoritative ledger state
+ * is deliberately resolved per invocation and is never stored on the session.
+ */
+export declare class BoundCapabilitySession<TContext> {
+    #private;
+    constructor(params: {
+        requestId: string;
+        context: TContext;
+        boundCall: RoleCallFrame;
+        ledger: RoleCallLedger;
+        capabilities: readonly WorkerCapabilityDescriptor[];
+        byCapabilityId: ReadonlyMap<string, WorkerCapabilityAdapter<TContext>>;
+        diagnostic: WorkerCapabilityDiagnosticContext;
+        capabilityScope: WorkerCapabilityScopeProjection<WorkerCapabilityAdapter<TContext>>;
+        dependencyResults: readonly RoleCallDependencyResult[];
+        executionFreshness?: WorkerCapabilityExecutionFreshness;
+    });
+    toBinding(): WorkerCapabilityBinding<TContext>;
+}

package/dist/src/runtime/orchestration/worker-capabilities/binding/bound-capability-session.js

@@ -0,0 +1,100 @@
+import { isRoleCapabilityId, } from "../../role-calls/index.js";
+import { executeBoundWorkerCapability, executeBoundWorkerCapabilityBatch, } from "../execution.js";
+import { resolveLiveCapabilityCall } from "./call-authority.js";
+import { CapabilityInvocationPreparer } from "./invocation-preparation.js";
+/**
+ * Immutable request/call-scoped capability facade. Authoritative ledger state
+ * is deliberately resolved per invocation and is never stored on the session.
+ */
+export class BoundCapabilitySession {
+    #requestId;
+    #context;
+    #boundCall;
+    #ledger;
+    #capabilities;
+    #diagnostic;
+    #capabilityScope;
+    #executionFreshness;
+    #dependencyResults;
+    #invocationPreparer;
+    constructor(params) {
+        this.#requestId = params.requestId;
+        this.#context = params.context;
+        this.#boundCall = params.boundCall;
+        this.#ledger = params.ledger;
+        this.#capabilities = params.capabilities;
+        this.#diagnostic = params.diagnostic;
+        this.#capabilityScope = params.capabilityScope;
+        this.#dependencyResults = params.dependencyResults;
+        this.#executionFreshness = params.executionFreshness;
+        this.#invocationPreparer = new CapabilityInvocationPreparer({
+            boundCall: params.boundCall,
+            byCapabilityId: params.byCapabilityId,
+            capabilityScope: params.capabilityScope,
+            diagnostic: params.diagnostic,
+        });
+    }
+    toBinding() {
+        return Object.freeze({
+            requestId: this.#requestId,
+            ledger: this.#ledger,
+            callId: this.#boundCall.callId,
+            invocationAttempt: this.#boundCall.activationCount,
+            capabilities: this.#capabilities,
+            execute: async (input) => this.#execute(input),
+            executeBatch: async (input) => this.#executeBatch(input),
+        });
+    }
+    async #execute(input) {
+        const attemptedCapabilityId = isRoleCapabilityId(input.capabilityId)
+            ? input.capabilityId
+            : undefined;
+        const { currentHead, currentCall } = resolveLiveCapabilityCall({
+            requestId: this.#requestId,
+            boundCall: this.#boundCall,
+            ledger: this.#ledger,
+            diagnostic: this.#diagnostic,
+            ...(attemptedCapabilityId ? { attemptedCapabilityId } : {}),
+        });
+        const invocation = this.#invocationPreparer.prepareSingle(input);
+        return executeBoundWorkerCapability({
+            context: this.#context,
+            call: currentCall,
+            currentHead,
+            ledger: this.#ledger,
+            ...invocation,
+            diagnostic: this.#diagnostic,
+            capabilityScope: this.#capabilityScope,
+            ...(this.#dependencyResults.length > 0
+                ? { dependencyResults: this.#dependencyResults }
+                : {}),
+            ...(this.#executionFreshness
+                ? { executionFreshness: this.#executionFreshness }
+                : {}),
+        });
+    }
+    async #executeBatch(input) {
+        const { currentHead, currentCall } = resolveLiveCapabilityCall({
+            requestId: this.#requestId,
+            boundCall: this.#boundCall,
+            ledger: this.#ledger,
+            diagnostic: this.#diagnostic,
+        });
+        const invocations = this.#invocationPreparer.prepareBatch(input.invocations);
+        return executeBoundWorkerCapabilityBatch({
+            context: this.#context,
+            call: currentCall,
+            currentHead,
+            ledger: this.#ledger,
+            invocations,
+            diagnostic: this.#diagnostic,
+            capabilityScope: this.#capabilityScope,
+            ...(this.#dependencyResults.length > 0
+                ? { dependencyResults: this.#dependencyResults }
+                : {}),
+            ...(this.#executionFreshness
+                ? { executionFreshness: this.#executionFreshness }
+                : {}),
+        });
+    }
+}