@abot-ai/runtime 1.0.0

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

@@ -0,0 +1,178 @@
+import { type RoleCallFrame, type RoleCallDependencyResult, type RoleCallLedger, type RoleCapabilityEffect, type RoleCapabilityDeclaredEffect, type RoleCapabilityExecutionOutcome, type RoleCapabilityObservedEffect, type RoleCapabilityResultReference } from "../role-calls/index.js";
+import type { ToolCatalogGroup } from "../../../capabilities/tool-types.js";
+import type { CapabilityAdapterResult } from "../capability-adapters/result.js";
+export declare const WORKER_CAPABILITY_ID_MAX_LENGTH = 128;
+/** Client-facing capability narration; never an execution objective or payload. */
+export declare const WORKER_CAPABILITY_INTENT_MAX_LENGTH = 500;
+export declare const WORKER_CAPABILITY_SUMMARY_MAX_LENGTH = 512;
+export declare const WORKER_CAPABILITY_COUNT_MAX = 64;
+export declare const WORKER_CAPABILITY_CONTROL_COUNT_MAX = 16;
+export declare const WORKER_CAPABILITY_CONTROL_ID_MAX_LENGTH = 64;
+export declare const WORKER_CAPABILITY_CONTROL_STRING_MAX_LENGTH = 4096;
+export declare const WORKER_CAPABILITY_CONTROL_ENUM_MAX_VALUES = 64;
+export declare const WORKER_CAPABILITY_CONTROL_ENUM_VALUE_MAX_LENGTH = 256;
+export declare const WORKER_CAPABILITY_CONTROL_ARRAY_MAX_ITEMS = 64;
+export type WorkerCapabilityEffect = RoleCapabilityDeclaredEffect;
+export type WorkerCapabilityObservedEffect = RoleCapabilityObservedEffect;
+export type WorkerCapabilityBoundedStringControl = Readonly<{
+    type: "string";
+    minLength: number;
+    maxLength: number;
+}>;
+export type WorkerCapabilityUnboundedStringControl = Readonly<{
+    type: "string";
+    minLength: number;
+}>;
+export type WorkerCapabilityEnumControl = Readonly<{
+    type: "string";
+    enum: readonly string[];
+}>;
+export type WorkerCapabilityNumberControl = Readonly<{
+    type: "number" | "integer";
+    minimum: number;
+    maximum: number;
+}>;
+export type WorkerCapabilityBooleanControl = Readonly<{
+    type: "boolean";
+}>;
+export type WorkerCapabilityScalarControl = WorkerCapabilityBoundedStringControl | WorkerCapabilityUnboundedStringControl | WorkerCapabilityEnumControl | WorkerCapabilityNumberControl | WorkerCapabilityBooleanControl;
+export type WorkerCapabilityArrayControl = Readonly<{
+    type: "array";
+    items: WorkerCapabilityScalarControl;
+    minItems: number;
+    maxItems: number;
+}>;
+export type WorkerCapabilityControl = WorkerCapabilityScalarControl | WorkerCapabilityArrayControl;
+export type WorkerCapabilityControlsSchema = Readonly<{
+    type: "object";
+    additionalProperties: false;
+    properties: Readonly<Record<string, WorkerCapabilityControl>>;
+    required: readonly string[];
+}>;
+export declare const EMPTY_WORKER_CAPABILITY_CONTROLS_SCHEMA: WorkerCapabilityControlsSchema;
+export type WorkerCapabilityDescriptor = Readonly<{
+    capabilityId: string;
+    summary: string;
+    effect: WorkerCapabilityEffect;
+    controls: WorkerCapabilityControlsSchema;
+    /** Manifest-declared controls whose values use runtime path semantics. */
+    runtimePathControlIds?: readonly string[];
+    /** Controls selected and frozen with capability identity before refinement. */
+    selectionControlIds?: readonly string[];
+    /** Allows mechanical execution only when selection owns every control. */
+    controlsRefinement?: "mechanical_when_complete";
+    /** Manifest-owned routing metadata projected only in capability selection. */
+    catalogGroups?: readonly ToolCatalogGroup[];
+}>;
+export type WorkerCapabilityControls = Readonly<Record<string, unknown>>;
+/**
+ * Optional root-owned admission fence carried through the shared capability
+ * engine. Worker bindings omit it, so their adapter and payload contracts stay
+ * byte-compatible.
+ */
+export type WorkerCapabilityExecutionFreshness = Readonly<{
+    token: Readonly<{
+        kind: "request_steering_v1";
+        version: number;
+        updates: readonly Readonly<{
+            sequence: number;
+            text: string;
+        }>[];
+    }>;
+    isCurrent(): boolean;
+}>;
+export type WorkerCapabilityAdapterResult = Readonly<{
+    outcome: "succeeded";
+    observedEffect: RoleCapabilityEffect;
+    summary: string;
+    referenceData?: string;
+    references?: readonly RoleCapabilityResultReference[];
+    /** Canonical adapter-owned result persisted for every settled execution. */
+    exactResult?: CapabilityAdapterResult;
+}> | Readonly<{
+    outcome: "failed";
+    observedEffect: WorkerCapabilityObservedEffect;
+    summary: string;
+    referenceData?: string;
+    references?: readonly RoleCapabilityResultReference[];
+    /** Canonical adapter-owned result persisted for every settled execution. */
+    exactResult?: CapabilityAdapterResult;
+}>;
+export type WorkerCapabilityExecutionReference = Readonly<{
+    executionId: string;
+}>;
+export type WorkerCapabilityBatchExecutionReference = Readonly<{
+    executionIds: readonly string[];
+}>;
+export type WorkerCapabilityInvocation = Readonly<{
+    capabilityId: string;
+    /** Client-facing presentation metadata; execution must not infer from it. */
+    intent: string;
+    controls: WorkerCapabilityControls;
+}>;
+export type WorkerSettledCapabilityResult = Readonly<{
+    executionId: string;
+    callId: string;
+    invocationAttempt: number;
+    capabilityId: string;
+    declaredEffect: RoleCapabilityDeclaredEffect;
+    outcome: RoleCapabilityExecutionOutcome;
+    observedEffect: RoleCapabilityObservedEffect;
+    summary: string;
+    referenceData?: string;
+    references?: readonly RoleCapabilityResultReference[];
+    /** Exact evidence owned by this producing call. */
+    adapterResult: CapabilityAdapterResult;
+}>;
+export type WorkerCapabilityAdapter<TContext> = Readonly<{
+    descriptor: WorkerCapabilityDescriptor;
+    execute(input: Readonly<{
+        context: TContext;
+        call: RoleCallFrame;
+        executionId: string;
+        /** Client-facing presentation metadata for lifecycle events only. */
+        intent: string;
+        controls: WorkerCapabilityControls;
+        settledCapabilityResults: readonly WorkerSettledCapabilityResult[];
+        dependencyResults?: readonly RoleCallDependencyResult[];
+        executionFreshness?: WorkerCapabilityExecutionFreshness;
+    }>): Promise<WorkerCapabilityAdapterResult>;
+}>;
+/**
+ * Lazy request-scoped source of neutral Worker capabilities. Implementations
+ * may resolve external adapters, but orchestration never imports or selects
+ * those external systems itself.
+ */
+export type WorkerCapabilityAdapterProvider<TContext> = Readonly<{
+    /**
+     * Returns the exact request-scoped public capability descriptors without
+     * constructing execution adapters or preparing tool execution state.
+     */
+    getDescriptors(): readonly WorkerCapabilityDescriptor[];
+    /**
+     * Resolves one-time model guidance only after a capability was selected and
+     * before its adapter is allowed to execute. The returned content is scoped
+     * to that pending invocation and must not be persisted into later turns.
+     */
+    getExecutionGuidance?(capabilityId: string): Promise<string>;
+    getAdapters(): readonly WorkerCapabilityAdapter<TContext>[];
+}>;
+export type WorkerCapabilityBinding<TContext> = Readonly<{
+    requestId: string;
+    ledger: RoleCallLedger;
+    callId: string;
+    invocationAttempt: number;
+    capabilities: readonly WorkerCapabilityDescriptor[];
+    execute(input: Readonly<{
+        capabilityId: string;
+        intent: unknown;
+        controls: unknown;
+    }>): Promise<WorkerCapabilityExecutionReference>;
+    executeBatch(input: Readonly<{
+        invocations: readonly Readonly<{
+            capabilityId: string;
+            intent: unknown;
+            controls: unknown;
+        }>[];
+    }>): Promise<WorkerCapabilityBatchExecutionReference>;
+}>;

package/dist/src/runtime/orchestration/worker-capabilities/contracts.js

@@ -0,0 +1,18 @@
+import { ROLE_CAPABILITY_ID_MAX_LENGTH, } from "../role-calls/index.js";
+export const WORKER_CAPABILITY_ID_MAX_LENGTH = ROLE_CAPABILITY_ID_MAX_LENGTH;
+/** Client-facing capability narration; never an execution objective or payload. */
+export const WORKER_CAPABILITY_INTENT_MAX_LENGTH = 500;
+export const WORKER_CAPABILITY_SUMMARY_MAX_LENGTH = 512;
+export const WORKER_CAPABILITY_COUNT_MAX = 64;
+export const WORKER_CAPABILITY_CONTROL_COUNT_MAX = 16;
+export const WORKER_CAPABILITY_CONTROL_ID_MAX_LENGTH = 64;
+export const WORKER_CAPABILITY_CONTROL_STRING_MAX_LENGTH = 4_096;
+export const WORKER_CAPABILITY_CONTROL_ENUM_MAX_VALUES = 64;
+export const WORKER_CAPABILITY_CONTROL_ENUM_VALUE_MAX_LENGTH = 256;
+export const WORKER_CAPABILITY_CONTROL_ARRAY_MAX_ITEMS = 64;
+export const EMPTY_WORKER_CAPABILITY_CONTROLS_SCHEMA = Object.freeze({
+    type: "object",
+    additionalProperties: false,
+    properties: Object.freeze({}),
+    required: Object.freeze([]),
+});

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

@@ -0,0 +1,18 @@
+import { type WorkerCapabilityControls, type WorkerCapabilityControlsSchema } from "./contracts.js";
+export type WorkerCapabilityControlsSchemaNormalization = Readonly<{
+    ok: true;
+    value: WorkerCapabilityControlsSchema;
+}> | Readonly<{
+    ok: false;
+    issueCode: string;
+}>;
+export type WorkerCapabilityControlsValidation = Readonly<{
+    ok: true;
+    value: WorkerCapabilityControls;
+}> | Readonly<{
+    ok: false;
+    issueCode: string;
+    controlId?: string;
+}>;
+export declare function normalizeWorkerCapabilityControlsSchema(input: unknown): WorkerCapabilityControlsSchemaNormalization;
+export declare function validateWorkerCapabilityControls(schema: WorkerCapabilityControlsSchema, input: unknown): WorkerCapabilityControlsValidation;

package/dist/src/runtime/orchestration/worker-capabilities/controls.js

@@ -0,0 +1,251 @@
+import { WORKER_CAPABILITY_CONTROL_ARRAY_MAX_ITEMS, WORKER_CAPABILITY_CONTROL_COUNT_MAX, WORKER_CAPABILITY_CONTROL_ENUM_MAX_VALUES, WORKER_CAPABILITY_CONTROL_ENUM_VALUE_MAX_LENGTH, WORKER_CAPABILITY_CONTROL_ID_MAX_LENGTH, WORKER_CAPABILITY_CONTROL_STRING_MAX_LENGTH, } from "./contracts.js";
+export function normalizeWorkerCapabilityControlsSchema(input) {
+    if (!isPlainRecord(input) ||
+        !hasExactKeys(input, [
+            "type",
+            "additionalProperties",
+            "properties",
+            "required",
+        ]) ||
+        input.type !== "object" ||
+        input.additionalProperties !== false ||
+        !isPlainRecord(input.properties) ||
+        !Array.isArray(input.required)) {
+        return failure("controls_schema_invalid");
+    }
+    const entries = Object.entries(input.properties);
+    if (entries.length > WORKER_CAPABILITY_CONTROL_COUNT_MAX) {
+        return failure("controls_schema_count_invalid");
+    }
+    const properties = {};
+    for (const [controlId, rawControl] of entries) {
+        if (!isControlId(controlId)) {
+            return failure("controls_schema_id_invalid");
+        }
+        const normalized = normalizeControl(rawControl);
+        if (!normalized.ok)
+            return normalized;
+        properties[controlId] = normalized.value;
+    }
+    if (input.required.some((controlId) => typeof controlId !== "string" || !Object.hasOwn(properties, controlId)) ||
+        new Set(input.required).size !== input.required.length) {
+        return failure("controls_schema_required_invalid");
+    }
+    return {
+        ok: true,
+        value: Object.freeze({
+            type: "object",
+            additionalProperties: false,
+            properties: Object.freeze(properties),
+            required: Object.freeze([...input.required]),
+        }),
+    };
+}
+export function validateWorkerCapabilityControls(schema, input) {
+    if (!isPlainRecord(input)) {
+        return failure("controls_not_object");
+    }
+    const suppliedIds = Object.keys(input);
+    const unknownId = suppliedIds.find((controlId) => !Object.hasOwn(schema.properties, controlId));
+    if (unknownId) {
+        return failure("controls_unknown", unknownId);
+    }
+    const missingId = schema.required.find((controlId) => !Object.hasOwn(input, controlId));
+    if (missingId) {
+        return failure("controls_required_missing", missingId);
+    }
+    const controls = {};
+    for (const controlId of suppliedIds) {
+        const control = schema.properties[controlId];
+        const value = normalizeControlValue(control, input[controlId]);
+        if (!value.ok) {
+            return failure(value.issueCode, controlId);
+        }
+        controls[controlId] = value.value;
+    }
+    return { ok: true, value: Object.freeze(controls) };
+}
+function normalizeControl(input) {
+    if (!isPlainRecord(input) || typeof input.type !== "string") {
+        return failure("controls_schema_property_invalid");
+    }
+    if (input.type === "array") {
+        if (!hasExactKeys(input, ["type", "items", "minItems", "maxItems"]) ||
+            !isBoundedInteger(input.minItems, 0, WORKER_CAPABILITY_CONTROL_ARRAY_MAX_ITEMS) ||
+            !isBoundedInteger(input.maxItems, 1, WORKER_CAPABILITY_CONTROL_ARRAY_MAX_ITEMS) ||
+            input.minItems > input.maxItems) {
+            return failure("controls_schema_array_invalid");
+        }
+        const items = normalizeScalarControl(input.items);
+        if (!items.ok)
+            return items;
+        return {
+            ok: true,
+            value: Object.freeze({
+                type: "array",
+                items: items.value,
+                minItems: input.minItems,
+                maxItems: input.maxItems,
+            }),
+        };
+    }
+    return normalizeScalarControl(input);
+}
+function normalizeScalarControl(input) {
+    if (!isPlainRecord(input)) {
+        return failure("controls_schema_scalar_invalid");
+    }
+    if (input.type === "string" && Object.hasOwn(input, "enum")) {
+        if (!hasExactKeys(input, ["type", "enum"]) ||
+            !Array.isArray(input.enum) ||
+            input.enum.length === 0 ||
+            input.enum.length > WORKER_CAPABILITY_CONTROL_ENUM_MAX_VALUES ||
+            input.enum.some((value) => typeof value !== "string" ||
+                value.length > WORKER_CAPABILITY_CONTROL_ENUM_VALUE_MAX_LENGTH) ||
+            new Set(input.enum).size !== input.enum.length) {
+            return failure("controls_schema_enum_invalid");
+        }
+        return {
+            ok: true,
+            value: Object.freeze({
+                type: "string",
+                enum: Object.freeze([...input.enum]),
+            }),
+        };
+    }
+    if (input.type === "string") {
+        if (hasExactKeys(input, ["type", "minLength"])) {
+            if (!isBoundedInteger(input.minLength, 0, WORKER_CAPABILITY_CONTROL_STRING_MAX_LENGTH)) {
+                return failure("controls_schema_string_invalid");
+            }
+            return {
+                ok: true,
+                value: Object.freeze({
+                    type: "string",
+                    minLength: input.minLength,
+                }),
+            };
+        }
+        if (!hasExactKeys(input, ["type", "minLength", "maxLength"]) ||
+            !isBoundedInteger(input.minLength, 0, WORKER_CAPABILITY_CONTROL_STRING_MAX_LENGTH) ||
+            !isBoundedInteger(input.maxLength, 1, WORKER_CAPABILITY_CONTROL_STRING_MAX_LENGTH) ||
+            input.minLength > input.maxLength) {
+            return failure("controls_schema_string_invalid");
+        }
+        return {
+            ok: true,
+            value: Object.freeze({
+                type: "string",
+                minLength: input.minLength,
+                maxLength: input.maxLength,
+            }),
+        };
+    }
+    if (input.type === "number" || input.type === "integer") {
+        if (!hasExactKeys(input, ["type", "minimum", "maximum"]) ||
+            typeof input.minimum !== "number" ||
+            !Number.isFinite(input.minimum) ||
+            typeof input.maximum !== "number" ||
+            !Number.isFinite(input.maximum) ||
+            input.minimum > input.maximum ||
+            (input.type === "integer" &&
+                (!Number.isSafeInteger(input.minimum) ||
+                    !Number.isSafeInteger(input.maximum)))) {
+            return failure("controls_schema_number_invalid");
+        }
+        return {
+            ok: true,
+            value: Object.freeze({
+                type: input.type,
+                minimum: input.minimum,
+                maximum: input.maximum,
+            }),
+        };
+    }
+    if (input.type === "boolean") {
+        return hasExactKeys(input, ["type"])
+            ? {
+                ok: true,
+                value: Object.freeze({ type: "boolean" }),
+            }
+            : failure("controls_schema_boolean_invalid");
+    }
+    return failure("controls_schema_scalar_invalid");
+}
+function normalizeControlValue(control, input) {
+    if (control.type === "array") {
+        if (!Array.isArray(input) ||
+            input.length < control.minItems ||
+            input.length > control.maxItems) {
+            return failure("controls_array_invalid");
+        }
+        const values = [];
+        for (const item of input) {
+            const value = normalizeScalarValue(control.items, item);
+            if (!value.ok)
+                return value;
+            values.push(value.value);
+        }
+        return { ok: true, value: Object.freeze(values) };
+    }
+    return normalizeScalarValue(control, input);
+}
+function normalizeScalarValue(control, input) {
+    if (control.type === "string") {
+        if (typeof input !== "string") {
+            return failure("controls_string_invalid");
+        }
+        if ("enum" in control) {
+            return control.enum.includes(input)
+                ? { ok: true, value: input }
+                : failure("controls_enum_invalid");
+        }
+        return input.length >= control.minLength &&
+            (!("maxLength" in control) || input.length <= control.maxLength)
+            ? { ok: true, value: input }
+            : failure("controls_string_invalid");
+    }
+    if (control.type === "boolean") {
+        return typeof input === "boolean"
+            ? { ok: true, value: input }
+            : failure("controls_boolean_invalid");
+    }
+    if (typeof input !== "number" ||
+        !Number.isFinite(input) ||
+        input < control.minimum ||
+        input > control.maximum ||
+        (control.type === "integer" && !Number.isSafeInteger(input))) {
+        return failure("controls_number_invalid");
+    }
+    return { ok: true, value: input };
+}
+function isControlId(input) {
+    return (input.length > 0 &&
+        input.length <= WORKER_CAPABILITY_CONTROL_ID_MAX_LENGTH &&
+        /^[\p{L}\p{N}][\p{L}\p{N}._:-]*$/u.test(input));
+}
+function isBoundedInteger(input, minimum, maximum) {
+    return (typeof input === "number" &&
+        Number.isSafeInteger(input) &&
+        input >= minimum &&
+        input <= maximum);
+}
+function isPlainRecord(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(input);
+    return prototype === Object.prototype || prototype === null;
+}
+function hasExactKeys(input, keys) {
+    const allowed = new Set(keys);
+    const actual = Object.keys(input);
+    return (actual.length === allowed.size && actual.every((key) => allowed.has(key)));
+}
+function failure(issueCode, controlId) {
+    return Object.freeze({
+        ok: false,
+        issueCode,
+        ...(controlId ? { controlId } : {}),
+    });
+}

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

@@ -0,0 +1,33 @@
+import type { RoleCallFrame } from "../role-calls/index.js";
+import type { WorkerCapabilityAdapterResult, WorkerCapabilityDescriptor, WorkerSettledCapabilityResult } from "./contracts.js";
+export type WorkerCapabilityDiagnosticContext = Readonly<{
+    requestId: string;
+    call: RoleCallFrame;
+    capabilityIds: readonly string[];
+    scopeMode: "full" | "catalog_groups";
+    scopeCatalogGroupIds: readonly string[];
+    knownCatalogGroupCount: number;
+    fullCapabilityCount: number;
+    filteredCapabilityCount: number;
+}>;
+export declare function traceWorkerCapabilityBindingCreated(context: WorkerCapabilityDiagnosticContext): void;
+export declare function traceWorkerCapabilityBindingRejected(context: WorkerCapabilityDiagnosticContext, issueCode: string): void;
+export declare function traceWorkerCapabilitySelectionResolved(context: WorkerCapabilityDiagnosticContext, descriptor: WorkerCapabilityDescriptor, intentLength: number, controlCount: number): void;
+export declare function traceWorkerCapabilitySelectionRejected(context: WorkerCapabilityDiagnosticContext, params: Readonly<{
+    issueCode: string;
+    capabilityId?: string;
+    errorType?: string;
+    attemptedCallId?: string;
+    attemptedInvocationAttempt?: number;
+}>): void;
+export declare function traceWorkerCapabilityContextProjected(context: WorkerCapabilityDiagnosticContext, descriptor: WorkerCapabilityDescriptor, settledResults: readonly WorkerSettledCapabilityResult[]): void;
+export declare function traceWorkerCapabilityContextRejected(context: WorkerCapabilityDiagnosticContext, descriptor: WorkerCapabilityDescriptor, issueCode: string): void;
+export declare function traceWorkerCapabilityExecutionStarted(context: WorkerCapabilityDiagnosticContext, descriptor: WorkerCapabilityDescriptor, executionId: string, intentLength: number, controlCount: number): void;
+export declare function traceWorkerCapabilityExecutionCompleted(context: WorkerCapabilityDiagnosticContext, descriptor: WorkerCapabilityDescriptor, result: WorkerCapabilityAdapterResult, executionId: string): void;
+export declare function traceWorkerCapabilityResultRejected(context: WorkerCapabilityDiagnosticContext, descriptor: WorkerCapabilityDescriptor, issueCode: string, executionId: string): void;
+export declare function traceWorkerCapabilityExecutionFailed(context: WorkerCapabilityDiagnosticContext, descriptor: WorkerCapabilityDescriptor, error: unknown, executionId: string): void;
+export declare function traceWorkerCapabilityStateRejected(context: WorkerCapabilityDiagnosticContext, descriptor: WorkerCapabilityDescriptor, params: Readonly<{
+    phase: "begin" | "settle";
+    issueCode: string;
+    executionId?: string;
+}>): void;

package/dist/src/runtime/orchestration/worker-capabilities/diagnostics.js

@@ -0,0 +1,117 @@
+import { traceDebug } from "../../observability/debug-logger.js";
+import { classifyRuntimeErrorType } from "../../observability/error-type.js";
+const WORKER_CAPABILITY_LOG_SCOPE = "runtime.worker_capabilities";
+export function traceWorkerCapabilityBindingCreated(context) {
+    traceDebug(WORKER_CAPABILITY_LOG_SCOPE, "binding.created", {
+        ...projectBinding(context),
+    });
+}
+export function traceWorkerCapabilityBindingRejected(context, issueCode) {
+    traceDebug(WORKER_CAPABILITY_LOG_SCOPE, "binding.rejected", {
+        ...projectBinding(context),
+        issueCode,
+    });
+}
+export function traceWorkerCapabilitySelectionResolved(context, descriptor, intentLength, controlCount) {
+    traceDebug(WORKER_CAPABILITY_LOG_SCOPE, "selection.resolved", {
+        ...projectSelection(context, descriptor),
+        intentLength,
+        controlCount,
+    });
+}
+export function traceWorkerCapabilitySelectionRejected(context, params) {
+    traceDebug(WORKER_CAPABILITY_LOG_SCOPE, "selection.rejected", {
+        ...projectBinding(context),
+        ...(params.capabilityId ? { capabilityId: params.capabilityId } : {}),
+        issueCode: params.issueCode,
+        ...(params.errorType ? { errorType: params.errorType } : {}),
+        ...(params.attemptedCallId
+            ? { attemptedCallId: params.attemptedCallId }
+            : {}),
+        ...(params.attemptedInvocationAttempt !== undefined
+            ? { attemptedInvocationAttempt: params.attemptedInvocationAttempt }
+            : {}),
+    });
+}
+export function traceWorkerCapabilityContextProjected(context, descriptor, settledResults) {
+    traceDebug(WORKER_CAPABILITY_LOG_SCOPE, "context.projected", {
+        ...projectSelection(context, descriptor),
+        settledCapabilityResultCount: settledResults.length,
+        settledCapabilityExecutionIds: settledResults.map((result) => result.executionId),
+        settledCapabilityIds: settledResults.map((result) => result.capabilityId),
+        settledCapabilitySummaryLength: settledResults.reduce((total, result) => total + result.summary.length, 0),
+        settledCapabilityReferenceDataLength: settledResults.reduce((total, result) => total + (result.referenceData?.length ?? 0), 0),
+        settledCapabilityReferenceCount: settledResults.reduce((total, result) => total + (result.references?.length ?? 0), 0),
+    });
+}
+export function traceWorkerCapabilityContextRejected(context, descriptor, issueCode) {
+    traceDebug(WORKER_CAPABILITY_LOG_SCOPE, "context.rejected", {
+        ...projectSelection(context, descriptor),
+        issueCode,
+    });
+}
+export function traceWorkerCapabilityExecutionStarted(context, descriptor, executionId, intentLength, controlCount) {
+    traceDebug(WORKER_CAPABILITY_LOG_SCOPE, "execution.started", {
+        ...projectSelection(context, descriptor),
+        executionId,
+        intentLength,
+        controlCount,
+    });
+}
+export function traceWorkerCapabilityExecutionCompleted(context, descriptor, result, executionId) {
+    traceDebug(WORKER_CAPABILITY_LOG_SCOPE, "execution.completed", {
+        ...projectSelection(context, descriptor),
+        executionId,
+        outcome: result.outcome,
+        observedEffect: result.observedEffect,
+        summaryLength: result.summary.length,
+        resultReferenceCount: result.references?.length ?? 0,
+    });
+}
+export function traceWorkerCapabilityResultRejected(context, descriptor, issueCode, executionId) {
+    traceDebug(WORKER_CAPABILITY_LOG_SCOPE, "result.rejected", {
+        ...projectSelection(context, descriptor),
+        executionId,
+        validationStage: "adapter_result",
+        issueCode,
+    });
+}
+export function traceWorkerCapabilityExecutionFailed(context, descriptor, error, executionId) {
+    traceDebug(WORKER_CAPABILITY_LOG_SCOPE, "execution.failed", {
+        ...projectSelection(context, descriptor),
+        executionId,
+        errorType: classifyRuntimeErrorType(error),
+    });
+}
+export function traceWorkerCapabilityStateRejected(context, descriptor, params) {
+    traceDebug(WORKER_CAPABILITY_LOG_SCOPE, "execution.state_rejected", {
+        ...projectSelection(context, descriptor),
+        statePhase: params.phase,
+        issueCode: params.issueCode,
+        ...(params.executionId ? { executionId: params.executionId } : {}),
+    });
+}
+function projectBinding(context) {
+    return {
+        requestId: context.requestId,
+        callId: context.call.callId,
+        parentCallId: context.call.parentCallId,
+        roleId: context.call.roleId,
+        depth: context.call.depth,
+        invocationAttempt: context.call.activationCount,
+        availableCapabilityCount: context.capabilityIds.length,
+        capabilityIds: context.capabilityIds,
+        workerCapabilityScopeMode: context.scopeMode,
+        workerCapabilityScopeCatalogGroupIds: context.scopeCatalogGroupIds,
+        workerCapabilityKnownCatalogGroupCount: context.knownCatalogGroupCount,
+        workerCapabilityFullCount: context.fullCapabilityCount,
+        workerCapabilityFilteredCount: context.filteredCapabilityCount,
+    };
+}
+function projectSelection(context, descriptor) {
+    return {
+        ...projectBinding(context),
+        capabilityId: descriptor.capabilityId,
+        declaredEffect: descriptor.effect,
+    };
+}

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

@@ -0,0 +1,38 @@
+import { type RoleCallFrame, type RoleCallLedger, type RoleCallLedgerHead, type RoleCallDependencyResult } from "../role-calls/index.js";
+import type { WorkerCapabilityAdapter, WorkerCapabilityBatchExecutionReference, WorkerCapabilityExecutionReference, WorkerCapabilityExecutionFreshness, WorkerCapabilityControls, WorkerCapabilityDescriptor } from "./contracts.js";
+import { type WorkerCapabilityDiagnosticContext } from "./diagnostics.js";
+import { type WorkerCapabilityScopeProjection } from "./scope.js";
+export declare function executeBoundWorkerCapability<TContext>(params: {
+    context: TContext;
+    call: RoleCallFrame;
+    currentHead: RoleCallLedgerHead;
+    ledger: RoleCallLedger;
+    adapter: Readonly<{
+        descriptor: WorkerCapabilityDescriptor;
+        execute: WorkerCapabilityAdapter<TContext>["execute"];
+    }>;
+    intent: string;
+    controls: WorkerCapabilityControls;
+    diagnostic: WorkerCapabilityDiagnosticContext;
+    capabilityScope: WorkerCapabilityScopeProjection<unknown>;
+    dependencyResults?: readonly RoleCallDependencyResult[];
+    executionFreshness?: WorkerCapabilityExecutionFreshness;
+}): Promise<WorkerCapabilityExecutionReference>;
+export declare function executeBoundWorkerCapabilityBatch<TContext>(params: {
+    context: TContext;
+    call: RoleCallFrame;
+    currentHead: RoleCallLedgerHead;
+    ledger: RoleCallLedger;
+    invocations: readonly Readonly<{
+        adapter: Readonly<{
+            descriptor: WorkerCapabilityDescriptor;
+            execute: WorkerCapabilityAdapter<TContext>["execute"];
+        }>;
+        intent: string;
+        controls: WorkerCapabilityControls;
+    }>[];
+    diagnostic: WorkerCapabilityDiagnosticContext;
+    capabilityScope: WorkerCapabilityScopeProjection<unknown>;
+    dependencyResults?: readonly RoleCallDependencyResult[];
+    executionFreshness?: WorkerCapabilityExecutionFreshness;
+}): Promise<WorkerCapabilityBatchExecutionReference>;