@abot-ai/runtime 1.0.0 → 1.2.0

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/assignment-provenance.d.ts

@@ -0,0 +1,36 @@
+import type { RoleCallFrame, RoleCallLedgerHead } from "../role-calls/contracts.js";
+import type { WorkerCapabilityAssignmentProvenance } from "./contracts.js";
+type WorkerCapabilityAssignmentIdentity = RoleCallFrame | Readonly<{
+    callId: string;
+    parentCallId: string | null;
+    depth: number;
+    objective: string;
+    invocationAttempt: number;
+}>;
+export type WorkerCapabilityDependencyArtifactReceipt = Readonly<{
+    sourceExecutionId: string;
+    targetPath: string;
+}>;
+export type WorkerCapabilityPlannerItemBinding = Readonly<{
+    plannerCallId: string;
+    planId: string;
+    itemId: string;
+    workerCallId: string;
+}>;
+/** Resolves one direct Planner-item binding from the canonical ledger head. */
+export declare function projectWorkerCapabilityPlannerItemBinding(head: RoleCallLedgerHead, call: RoleCallFrame): WorkerCapabilityPlannerItemBinding | undefined;
+/** Projects the canonical proof that one Worker owns one bound Planner item. */
+export declare function projectWorkerCapabilityAssignmentProvenance(params: Readonly<{
+    head: RoleCallLedgerHead;
+    call: RoleCallFrame;
+}>): WorkerCapabilityAssignmentProvenance | undefined;
+/** Validates the canonical receipt against the exact consuming Worker call. */
+export declare function isWorkerCapabilityAssignmentProvenanceValid(provenance: WorkerCapabilityAssignmentProvenance | undefined, identity: WorkerCapabilityAssignmentIdentity, requestId: string): boolean;
+/** Resolves model-visible request scope only from a verified runtime receipt. */
+export declare function projectWorkerRequestSourceProjection(provenance: WorkerCapabilityAssignmentProvenance | undefined, identity: WorkerCapabilityAssignmentIdentity, requestId: string): "full_request" | "assignment_only";
+/**
+ * Resolves only successful artifact references produced by the exact direct
+ * sibling results canonically attached to one Planner-bound Worker.
+ */
+export declare function projectWorkerCapabilityDependencyArtifactReceipts(provenance: WorkerCapabilityAssignmentProvenance | undefined, call: RoleCallFrame): readonly WorkerCapabilityDependencyArtifactReceipt[];
+export {};

package/dist/src/runtime/orchestration/worker-capabilities/assignment-provenance.js

@@ -0,0 +1,171 @@
+import { projectRoleCallDependencyResults } from "../role-calls/dependency-results.js";
+const WORKER_ASSIGNMENT_AUTHORITY = Symbol("workerAssignmentAuthority");
+const EMPTY_DEPENDENCY_ARTIFACT_RECEIPTS = Object.freeze([]);
+/** Resolves one direct Planner-item binding from the canonical ledger head. */
+export function projectWorkerCapabilityPlannerItemBinding(head, call) {
+    const canonicalCall = head.state.calls.find(({ callId }) => callId === call.callId);
+    if (canonicalCall !== call) {
+        throw new Error("worker_assignment_provenance_authority_invalid");
+    }
+    if (call.roleId !== "worker" || call.parentCallId === null)
+        return undefined;
+    const parent = head.state.calls.find(({ callId }) => callId === call.parentCallId);
+    if (!parent || parent.depth !== call.depth - 1) {
+        throw new Error("worker_assignment_provenance_parent_invalid");
+    }
+    if (parent.roleId !== "planner")
+        return undefined;
+    const plan = head.state.plans.find(({ definition }) => definition.plannerCallId === parent.callId);
+    const boundItems = plan?.itemStates.filter(({ childCallId }) => childCallId === call.callId);
+    if (!plan || !boundItems) {
+        throw new Error("worker_assignment_provenance_plan_binding_invalid");
+    }
+    if (boundItems.length !== 1) {
+        throw new Error("worker_assignment_provenance_plan_binding_invalid");
+    }
+    return Object.freeze({
+        plannerCallId: parent.callId,
+        planId: plan.definition.planId,
+        itemId: boundItems[0].itemId,
+        workerCallId: call.callId,
+    });
+}
+/** Projects the canonical proof that one Worker owns one bound Planner item. */
+export function projectWorkerCapabilityAssignmentProvenance(params) {
+    const canonicalCall = params.head.state.calls.find(({ callId }) => callId === params.call.callId);
+    if (canonicalCall !== params.call || canonicalCall.roleId !== "worker") {
+        throw new Error("worker_assignment_provenance_authority_invalid");
+    }
+    const binding = projectWorkerCapabilityPlannerItemBinding(params.head, canonicalCall);
+    if (!binding)
+        return undefined;
+    assertPlannerItemIsActive(params.head, binding);
+    const provenance = {
+        kind: "planner_plan_item_v1",
+        requestId: params.head.state.requestId,
+        sourceRevision: params.head.revision,
+        ...binding,
+        invocationAttempt: canonicalCall.activationCount,
+    };
+    const authority = Object.freeze({
+        receipt: provenance,
+        requestId: params.head.state.requestId,
+        head: params.head,
+        call: canonicalCall,
+    });
+    Object.defineProperty(provenance, WORKER_ASSIGNMENT_AUTHORITY, {
+        value: authority,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return Object.freeze(provenance);
+}
+/** Validates the canonical receipt against the exact consuming Worker call. */
+export function isWorkerCapabilityAssignmentProvenanceValid(provenance, identity, requestId) {
+    if (provenance === undefined)
+        return true;
+    const authority = readWorkerAssignmentAuthority(provenance);
+    if (!authority)
+        return false;
+    if (authority.requestId !== requestId)
+        return false;
+    if (!Object.isFrozen(provenance))
+        return false;
+    if (provenance.kind !== "planner_plan_item_v1")
+        return false;
+    if (provenance.requestId !== requestId)
+        return false;
+    if (provenance.workerCallId !== identity.callId)
+        return false;
+    if (provenance.plannerCallId !== identity.parentCallId)
+        return false;
+    const invocationAttempt = "activationCount" in identity
+        ? identity.activationCount
+        : identity.invocationAttempt;
+    if (provenance.invocationAttempt !== invocationAttempt)
+        return false;
+    if ("activationCount" in identity) {
+        return identity.roleId === "worker" && authority.call === identity;
+    }
+    return (authority.call.depth === identity.depth &&
+        authority.call.objective === identity.objective);
+}
+/** Resolves model-visible request scope only from a verified runtime receipt. */
+export function projectWorkerRequestSourceProjection(provenance, identity, requestId) {
+    if (!isWorkerCapabilityAssignmentProvenanceValid(provenance, identity, requestId)) {
+        throw new Error("worker_assignment_provenance_receipt_invalid");
+    }
+    return provenance ? "assignment_only" : "full_request";
+}
+/**
+ * Resolves only successful artifact references produced by the exact direct
+ * sibling results canonically attached to one Planner-bound Worker.
+ */
+export function projectWorkerCapabilityDependencyArtifactReceipts(provenance, call) {
+    if (!provenance)
+        return EMPTY_DEPENDENCY_ARTIFACT_RECEIPTS;
+    if (!isWorkerCapabilityAssignmentProvenanceValid(provenance, call, provenance.requestId)) {
+        throw new Error("worker_assignment_provenance_receipt_invalid");
+    }
+    const authority = readWorkerAssignmentAuthority(provenance);
+    if (!authority || authority.head.revision !== provenance.sourceRevision) {
+        throw new Error("worker_assignment_provenance_receipt_invalid");
+    }
+    const dependencies = projectRoleCallDependencyResults(authority.head, call);
+    const receipts = dependencies.flatMap((dependency) => {
+        if (dependency.roleId !== "worker" || dependency.outcome !== "completed") {
+            return [];
+        }
+        return projectDependencyProducerArtifactReceipts(authority.head, dependency.producerCallId);
+    });
+    return Object.freeze(receipts);
+}
+function projectDependencyProducerArtifactReceipts(head, producerCallId) {
+    const receipts = [];
+    for (const execution of head.state.capabilityExecutions) {
+        if (execution.callId !== producerCallId)
+            continue;
+        if (execution.status !== "settled" || execution.outcome !== "succeeded") {
+            continue;
+        }
+        for (const reference of execution.references ?? []) {
+            receipts.push(Object.freeze({
+                sourceExecutionId: execution.executionId,
+                targetPath: reference.target,
+            }));
+        }
+    }
+    return receipts;
+}
+function assertPlannerItemIsActive(head, binding) {
+    const plan = head.state.plans.find(({ definition }) => definition.planId === binding.planId);
+    if (!plan) {
+        throw new Error("worker_assignment_provenance_plan_binding_invalid");
+    }
+    const item = plan?.itemStates.find(({ itemId }) => itemId === binding.itemId);
+    if (!item || item.childCallId !== binding.workerCallId) {
+        throw new Error("worker_assignment_provenance_plan_binding_invalid");
+    }
+    if (item.status !== "in_progress") {
+        throw new Error("worker_assignment_provenance_plan_binding_invalid");
+    }
+}
+function readWorkerAssignmentAuthority(provenance) {
+    if (typeof provenance !== "object" || provenance === null)
+        return undefined;
+    const descriptor = Object.getOwnPropertyDescriptor(provenance, WORKER_ASSIGNMENT_AUTHORITY);
+    if (!descriptor ||
+        descriptor.enumerable ||
+        descriptor.configurable ||
+        descriptor.writable) {
+        return undefined;
+    }
+    const authority = descriptor.value;
+    if (typeof authority !== "object" || authority === null)
+        return undefined;
+    if (!Object.isFrozen(authority))
+        return undefined;
+    const candidate = authority;
+    return candidate.receipt === provenance ? candidate : undefined;
+}

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 }
+                : {}),
+        });
+    }
+}