@abot-ai/runtime 1.0.0 → 1.1.0

package/dist/src/runtime/adapters/registered-tool-normal-invocations/executor.js

@@ -1,8 +1,9 @@
 import { deriveRegisteredToolPayloadContextPlan, deriveRegisteredToolStagedPayloadPlan, } from "../registered-tool-payload-plan.js";
 import { captureNormalInvocationRegistrations } from "./catalog/registrations.js";
 import { projectRuntimePathBindings } from "./catalog/runtime-path-bindings.js";
-import { executeNormalInvocation } from "./execution/run.js";
+import { executeNormalInvocation, prepareNormalInvocation, } from "./execution/run.js";
 import { emitNormalInvocationPayloadLifecycle } from "./payload/lifecycle.js";
+import { prepareNormalInvocationPayloadLifecycle } from "./payload/lifecycle.js";
 /**
  * Captures one selected ToolRegistry snapshot and executes its ordinary
  * invocation contracts. Normalization may only resolve another operation from
@@ -21,9 +22,7 @@ export function createRegisteredToolNormalInvocationExecutor(params) {
         operationByHandle.set(handle, Object.freeze({
             registration,
             operation,
-            ...(runtimePathBindings.length > 0
-                ? { runtimePathBindings }
-                : {}),
+            ...(runtimePathBindings.length > 0 ? { runtimePathBindings } : {}),
             ...(payloadContextPlan ? { payloadContextPlan } : {}),
             ...(stagedPayloadPlan ? { stagedPayloadPlan } : {}),
         }));
@@ -44,6 +43,21 @@ export function createRegisteredToolNormalInvocationExecutor(params) {
                 ...(params.onEvent ? { onEvent: params.onEvent } : {}),
             });
         },
+        preparePayloadLifecycle(input) {
+            return prepareNormalInvocationPayloadLifecycle({
+                operationByHandle,
+                input,
+                ...(params.onEvent ? { onEvent: params.onEvent } : {}),
+            });
+        },
+        prepare(input) {
+            return prepareNormalInvocation({
+                executor: params,
+                registrations,
+                operationByHandle,
+                input,
+            });
+        },
         execute(input) {
             return executeNormalInvocation({
                 executor: params,

package/dist/src/runtime/adapters/registered-tool-normal-invocations/payload/lifecycle.d.ts

@@ -1,6 +1,11 @@
-import type { BoundOperation, RegisteredToolNormalInvocationPayloadLifecycleInput, RegisteredToolNormalInvocationPayloadLifecycleResult } from "../shared/contracts.js";
+import type { BoundOperation, RegisteredToolNormalInvocationPayloadLifecycleInput, RegisteredToolNormalInvocationPayloadLifecyclePreparation, RegisteredToolNormalInvocationPayloadLifecycleResult } from "../shared/contracts.js";
 export declare function emitNormalInvocationPayloadLifecycle(params: {
     operationByHandle: WeakMap<object, BoundOperation>;
     input: RegisteredToolNormalInvocationPayloadLifecycleInput;
     onEvent?(name: string, payload: Record<string, unknown>): void;
 }): RegisteredToolNormalInvocationPayloadLifecycleResult;
+export declare function prepareNormalInvocationPayloadLifecycle(params: {
+    operationByHandle: WeakMap<object, BoundOperation>;
+    input: RegisteredToolNormalInvocationPayloadLifecycleInput;
+    onEvent?(name: string, payload: Record<string, unknown>): void;
+}): RegisteredToolNormalInvocationPayloadLifecyclePreparation;

package/dist/src/runtime/adapters/registered-tool-normal-invocations/payload/lifecycle.js

@@ -3,6 +3,10 @@ import { buildToolIntentEventMetadata } from "../shared/event-metadata.js";
 import { rejectNormalInvocation } from "../shared/rejection.js";
 import { validatePublicInput } from "./input-preparation.js";
 export function emitNormalInvocationPayloadLifecycle(params) {
+    const prepared = prepareNormalInvocationPayloadLifecycle(params);
+    return prepared.status === "prepared" ? prepared.emit() : prepared;
+}
+export function prepareNormalInvocationPayloadLifecycle(params) {
     const source = params.operationByHandle.get(params.input.handle);
     if (!source) {
         return rejectNormalInvocation("normal_invocation_handle_invalid", "The selected ordinary capability is not registered for this request.");
@@ -28,24 +32,33 @@ export function emitNormalInvocationPayloadLifecycle(params) {
         payloadStageCount: lifecycleStage.stage.count,
         ...(eventMeta ? { meta: eventMeta } : {}),
     };
-    switch (params.input.phase) {
+    const event = materializePayloadLifecycleEvent(params.input, base);
+    return Object.freeze({
+        status: "prepared",
+        emit: () => {
+            params.onEvent?.(event.name, event.payload);
+            return Object.freeze({ status: "emitted" });
+        },
+    });
+}
+function materializePayloadLifecycleEvent(input, base) {
+    switch (input.phase) {
         case "started":
-            params.onEvent?.("tool.payload.started", base);
-            break;
+            return Object.freeze({ name: "tool.payload.started", payload: base });
         case "completed":
-            params.onEvent?.("tool.payload.completed", {
-                ...base,
-                ok: true,
+            return Object.freeze({
+                name: "tool.payload.completed",
+                payload: { ...base, ok: true },
             });
-            break;
         case "failed":
-            params.onEvent?.("tool.payload.failed", {
-                ...base,
-                ...(params.input.errorCode ? { error: params.input.errorCode } : {}),
+            return Object.freeze({
+                name: "tool.payload.failed",
+                payload: {
+                    ...base,
+                    ...(input.errorCode ? { error: input.errorCode } : {}),
+                },
             });
-            break;
     }
-    return Object.freeze({ status: "emitted" });
 }
 function resolvePayloadLifecycleStage(source, input) {
     const plan = source.stagedPayloadPlan;

package/dist/src/runtime/adapters/registered-tool-normal-invocations/shared/action-fingerprint.d.ts

@@ -0,0 +1,22 @@
+import type { ToolCall } from "../../../../capabilities/tool-types.js";
+/**
+ * Hashes the exact normalized tool call. The runtime core receives only this
+ * opaque identity and remains independent of tools, controls, and payloads.
+ */
+export declare function createRegisteredToolActionFingerprint(input: {
+    contractVersion: number;
+    operationId: string;
+    call: ToolCall;
+}): string;
+/**
+ * Identifies a fully bounded preparation attempt that could not become a
+ * normalized tool call. The stable rejection code keeps it disjoint from a
+ * later successful materialization of the same public controls.
+ */
+export declare function createRegisteredToolPreparationAttemptFingerprint(input: {
+    operationId: string;
+    controls: Readonly<Record<string, unknown>>;
+    rejectionCode: string;
+    payload?: string;
+    materializedParams?: Readonly<Record<string, string>>;
+}): string;

package/dist/src/runtime/adapters/registered-tool-normal-invocations/shared/action-fingerprint.js

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+/**
+ * Hashes the exact normalized tool call. The runtime core receives only this
+ * opaque identity and remains independent of tools, controls, and payloads.
+ */
+export function createRegisteredToolActionFingerprint(input) {
+    const canonical = JSON.stringify([
+        "registered_tool_normal_invocation_v1",
+        input.contractVersion,
+        input.operationId,
+        input.call.tool,
+        canonicalEntries(input.call.params),
+    ]);
+    return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+/**
+ * Identifies a fully bounded preparation attempt that could not become a
+ * normalized tool call. The stable rejection code keeps it disjoint from a
+ * later successful materialization of the same public controls.
+ */
+export function createRegisteredToolPreparationAttemptFingerprint(input) {
+    const canonical = JSON.stringify([
+        "operation_preparation_attempt_v1",
+        input.operationId,
+        canonicalEntries(input.controls),
+        input.rejectionCode,
+        input.payload === undefined ? null : digestText(input.payload),
+        input.materializedParams === undefined
+            ? null
+            : Object.freeze(Object.entries(input.materializedParams)
+                .sort(([left], [right]) => compareText(left, right))
+                .map(([key, value]) => Object.freeze([key, digestText(value)]))),
+    ]);
+    return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+function digestText(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+function canonicalEntries(input) {
+    return Object.freeze(Object.entries(input)
+        .sort(([left], [right]) => compareText(left, right))
+        .map(([key, value]) => Object.freeze([key, canonicalValue(value)])));
+}
+function canonicalValue(value) {
+    if (Array.isArray(value)) {
+        return Object.freeze(value.map((entry) => canonicalValue(entry)));
+    }
+    if (isPlainRecord(value))
+        return canonicalEntries(value);
+    return value;
+}
+function isPlainRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function compareText(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}

package/dist/src/runtime/adapters/registered-tool-normal-invocations/shared/contracts.d.ts

@@ -31,10 +31,26 @@ export type RegisteredToolNormalInvocationExecution = Readonly<{
     completionActions: readonly ToolActionSummary[];
 }>;
 export type RegisteredToolNormalInvocationResult = RegisteredToolNormalInvocationExecution | RegisteredToolNormalInvocationRejection;
+export type RegisteredToolPreparedNormalInvocation = Readonly<{
+    status: "prepared";
+    /** Opaque identity of the exact normalized call that would be executed. */
+    actionFingerprint: string;
+    /** Exact validated non-payload controls accepted for this invocation. */
+    acceptedControls: Readonly<Record<string, unknown>>;
+    execute(): Promise<RegisteredToolNormalInvocationResult>;
+}>;
+export type RegisteredToolNormalInvocationPreparation = RegisteredToolPreparedNormalInvocation | RegisteredToolNormalInvocationRejection;
 export type RegisteredToolNormalInvocationPayloadLifecyclePhase = "started" | "completed" | "failed";
 export type RegisteredToolNormalInvocationPayloadLifecycleResult = Readonly<{
     status: "emitted";
 }> | RegisteredToolNormalInvocationRejection;
+export type RegisteredToolPreparedNormalInvocationPayloadLifecycle = Readonly<{
+    status: "prepared";
+    emit(): Readonly<{
+        status: "emitted";
+    }>;
+}>;
+export type RegisteredToolNormalInvocationPayloadLifecyclePreparation = RegisteredToolPreparedNormalInvocationPayloadLifecycle | RegisteredToolNormalInvocationRejection;
 export type RegisteredToolNormalInvocationExecutor = Readonly<{
     operations: readonly RegisteredToolNormalInvocationProjection[];
     /**
@@ -52,6 +68,33 @@ export type RegisteredToolNormalInvocationExecutor = Readonly<{
         payloadStageCount?: number;
         outputParam?: string;
     }>): RegisteredToolNormalInvocationPayloadLifecycleResult;
+    /**
+     * Validates and materializes one payload lifecycle event without publishing
+     * it. The prepared event can be released only after canonical admission.
+     */
+    preparePayloadLifecycle(input: Readonly<{
+        handle: RegisteredToolNormalInvocationHandle;
+        controls: Readonly<Record<string, unknown>>;
+        /** Client-facing lifecycle metadata; never part of tool parameters. */
+        intent?: string;
+        phase: RegisteredToolNormalInvocationPayloadLifecyclePhase;
+        errorCode?: string;
+        payloadStage?: number;
+        payloadStageCount?: number;
+        outputParam?: string;
+    }>): RegisteredToolNormalInvocationPayloadLifecyclePreparation;
+    /**
+     * Fully validates and normalizes an invocation without approval or tool
+     * execution. The returned action fingerprint is safe for generic admission.
+     */
+    prepare(input: Readonly<{
+        handle: RegisteredToolNormalInvocationHandle;
+        controls: Readonly<Record<string, unknown>>;
+        payload?: string;
+        materializedParams?: Readonly<Record<string, string>>;
+        /** Client-facing lifecycle metadata; never part of tool parameters. */
+        intent?: string;
+    }>): RegisteredToolNormalInvocationPreparation;
     execute(input: Readonly<{
         handle: RegisteredToolNormalInvocationHandle;
         controls: Readonly<Record<string, unknown>>;
@@ -84,3 +127,4 @@ export type RegisteredToolNormalInvocationExecutorParams = Readonly<{
 }>;
 export type RegisteredToolNormalInvocationPayloadLifecycleInput = Parameters<RegisteredToolNormalInvocationExecutor["emitPayloadLifecycle"]>[0];
 export type RegisteredToolNormalInvocationExecutionInput = Parameters<RegisteredToolNormalInvocationExecutor["execute"]>[0];
+export type RegisteredToolNormalInvocationPreparationInput = Parameters<RegisteredToolNormalInvocationExecutor["prepare"]>[0];

package/dist/src/runtime/adapters/registered-tool-normal-invocations.d.ts

@@ -1,3 +1,3 @@
 export { createRegisteredToolNormalInvocationExecutor } from "./registered-tool-normal-invocations/executor.js";
 export { projectRuntimePathBindings } from "./registered-tool-normal-invocations/catalog/runtime-path-bindings.js";
-export type { RegisteredToolNormalInvocationExecution, RegisteredToolNormalInvocationExecutor, RegisteredToolNormalInvocationHandle, RegisteredToolNormalInvocationPayloadLifecyclePhase, RegisteredToolNormalInvocationPayloadLifecycleResult, RegisteredToolNormalInvocationProjection, RegisteredToolNormalInvocationRejection, RegisteredToolNormalInvocationResult, } from "./registered-tool-normal-invocations/shared/contracts.js";
+export type { RegisteredToolNormalInvocationExecution, RegisteredToolNormalInvocationExecutor, RegisteredToolNormalInvocationHandle, RegisteredToolNormalInvocationPayloadLifecyclePhase, RegisteredToolNormalInvocationPayloadLifecyclePreparation, RegisteredToolNormalInvocationPayloadLifecycleResult, RegisteredToolNormalInvocationPreparation, RegisteredToolNormalInvocationProjection, RegisteredToolPreparedNormalInvocation, RegisteredToolPreparedNormalInvocationPayloadLifecycle, RegisteredToolNormalInvocationRejection, RegisteredToolNormalInvocationResult, } from "./registered-tool-normal-invocations/shared/contracts.js";

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/catalog.js

@@ -71,11 +71,18 @@ function projectWorkerDescriptor(definition, operation, stagedPayloadPlan) {
     if (!controls.ok) {
         throw new RegisteredToolWorkerCapabilityCompositionError("operation_controls_unsupported", operation.operationId);
     }
-    const selectionControlIds = definition.payloadChannelSpec?.targetRole === "operation_target"
+    const payloadTargetControlId = definition.payloadChannelSpec?.targetRole === "operation_target"
         ? definition.payloadChannelSpec.targetParam
-            ? [definition.payloadChannelSpec.targetParam]
-            : undefined
-        : [];
+        : undefined;
+    const selectionControlIds = definition.payloadChannelSpec?.targetRole === "operation_target" &&
+        !payloadTargetControlId
+        ? undefined
+        : Object.freeze([
+            ...new Set([
+                ...(operation.selectionControlIds ?? []),
+                ...(payloadTargetControlId ? [payloadTargetControlId] : []),
+            ]),
+        ]);
     const controlsPartition = partitionWorkerCapabilityControlsSchema(controls.value, selectionControlIds);
     if (!controlsPartition.ok || selectionControlIds === undefined) {
         throw new RegisteredToolWorkerCapabilityCompositionError("operation_target_control_invalid", operation.operationId);
@@ -101,6 +108,9 @@ function projectWorkerDescriptor(definition, operation, stagedPayloadPlan) {
         ...(definition.controlsRefinement
             ? { controlsRefinement: definition.controlsRefinement }
             : {}),
+        ...(operation.payload
+            ? { requiresPayloadAuthoringObjective: true }
+            : {}),
         catalogGroups,
     });
 }

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/execution.js

@@ -1,9 +1,12 @@
 import { assertWorkerCapabilityWithinScope, projectWorkerCapabilityScope, WorkerCapabilityScopeError, } from "../../orchestration/worker-capabilities/index.js";
 import { traceRegisteredToolWorkerCapabilityExecutionCompleted, traceRegisteredToolWorkerCapabilityExecutionFailed, traceRegisteredToolWorkerCapabilityExecutionStarted, } from "../registered-tool-worker-capability-diagnostics.js";
 import { RegisteredToolWorkerCapabilityCompositionError, RegisteredToolWorkerCapabilityExecutionError, } from "./errors.js";
-import { executionFreshnessRejection, prepareOperationPayload, } from "./payload-lifecycle.js";
+import { executionFreshnessRejection, payloadRejection, prepareOperationPayload, } from "./payload-lifecycle.js";
 import { attachTargetReferences, observeExternalResult, projectSelectedTargetReferences, } from "./result-observer.js";
 import { resolveEffectiveOperationTargetControls } from "./runtime-path-controls.js";
+import { createRegisteredToolPreparationAttemptFingerprint } from "../registered-tool-normal-invocations/shared/action-fingerprint.js";
+import { createWorkerCapabilityPreparationFailureFingerprint } from "../../orchestration/worker-capabilities/preparation-fingerprint.js";
+import { createDeferredPayloadObservability } from "./payload-observability.js";
 export function projectWorkerAdapters(params) {
     const projections = new Map();
     for (const projection of params.executor.operations) {
@@ -37,97 +40,159 @@ export function projectWorkerAdapters(params) {
     }));
 }
 function createWorkerAdapter(params) {
-    const operationId = params.projection.operation.operationId;
-    const operationEffect = params.projection.operation.effect;
     return Object.freeze({
         descriptor: params.descriptor,
+        async prepare(input) {
+            return prepareRegisteredToolWorkerAdapter(params, input);
+        },
         async execute(input) {
-            try {
-                const capabilityScope = projectWorkerCapabilityScope({
-                    entries: params.scopeDescriptors,
-                    scope: input.call.workerCapabilityScope,
-                    descriptorOf: (descriptor) => descriptor,
-                });
-                assertWorkerCapabilityWithinScope(capabilityScope, params.descriptor);
-            }
-            catch (error) {
-                const scopedError = error instanceof WorkerCapabilityScopeError
-                    ? new RegisteredToolWorkerCapabilityCompositionError(error.issueCode, operationId)
-                    : error;
-                traceRegisteredToolWorkerCapabilityExecutionFailed(params.diagnostic, operationId, input.call, input.executionId, scopedError, error instanceof WorkerCapabilityScopeError
-                    ? error.issueCode
-                    : "capability_scope_validation_failed");
-                throw scopedError;
-            }
-            traceRegisteredToolWorkerCapabilityExecutionStarted(params.diagnostic, operationId, input.call, input.executionId, input.intent.length, Object.keys(input.controls).length);
-            try {
-                const effectiveControls = resolveEffectiveOperationTargetControls({
-                    descriptor: params.descriptor,
-                    controls: input.controls,
-                    runtimePathBindings: params.projection.runtimePathBindings ?? Object.freeze([]),
-                    workingDirectory: input.call.workingDirectory,
-                    sharedState: params.sharedState,
-                });
-                const selectedTargetReferences = projectSelectedTargetReferences(params.projection, effectiveControls, input.call.parentCallId === null
-                    ? params.descriptor.selectionControlIds
-                    : undefined);
-                const preparedPayload = await prepareOperationPayload({
-                    projection: params.projection,
-                    executor: params.executor,
-                    sharedState: params.sharedState,
-                    ...(params.payloadAuthor
-                        ? { payloadAuthor: params.payloadAuthor }
-                        : {}),
-                    call: input.call,
-                    executionId: input.executionId,
-                    descriptor: params.descriptor,
-                    intent: input.intent,
-                    controls: effectiveControls,
-                    ...(input.dependencyResults
-                        ? { dependencyResults: input.dependencyResults }
-                        : {}),
-                    settledCapabilityResults: input.settledCapabilityResults,
-                    diagnostic: params.diagnostic,
-                    ...(input.executionFreshness
-                        ? { executionFreshness: input.executionFreshness }
-                        : {}),
-                });
-                const completeRejectedExecution = (rejectedExecution) => {
-                    const canonicalResult = Object.freeze({
-                        ...rejectedExecution.result,
-                        exactResult: rejectedExecution.exactResult,
-                    });
-                    const preparedResult = attachTargetReferences(canonicalResult, selectedTargetReferences);
-                    traceRegisteredToolWorkerCapabilityExecutionCompleted(params.diagnostic, operationId, input.call, input.executionId, preparedResult, "rejected", {
-                        sourceIssueCode: rejectedExecution.sourceIssueCode,
-                        summaryProjection: "runtime_rejection",
-                        completionActions: Object.freeze([]),
-                    });
-                    return preparedResult;
-                };
-                if (preparedPayload.status === "rejected") {
-                    return completeRejectedExecution(preparedPayload);
+            const preparationInput = Object.freeze({
+                ...input,
+                preparationId: input.executionId,
+            });
+            const prepared = await prepareRegisteredToolWorkerAdapter(params, preparationInput);
+            return prepared.execute(input.executionId);
+        },
+    });
+}
+async function prepareRegisteredToolWorkerAdapter(params, input) {
+    const operationId = params.projection.operation.operationId;
+    const payloadObservability = createDeferredPayloadObservability({
+        executor: params.executor,
+        diagnostic: params.diagnostic,
+        operationId,
+        call: input.call,
+    });
+    try {
+        return await prepareRegisteredToolWorkerCapability(params, input, payloadObservability);
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError")
+            throw error;
+        const actionFingerprint = createWorkerCapabilityPreparationFailureFingerprint({
+            capabilityId: params.descriptor.capabilityId,
+            controls: input.controls,
+            ...(input.call.workingDirectory
+                ? { workingDirectory: input.call.workingDirectory }
+                : {}),
+            error,
+        });
+        return Object.freeze({
+            ...(actionFingerprint ? { actionFingerprint } : {}),
+            acceptedControls: input.controls,
+            execute: async (executionId) => {
+                try {
+                    payloadObservability.release(executionId);
+                }
+                catch (releaseError) {
+                    tracePreparedExecutionFailed(params, input, operationId, executionId, releaseError);
+                    throw releaseError;
                 }
+                tracePreparedExecutionFailed(params, input, operationId, executionId, error, registeredPreparationFailureIssueCode(error));
+                throw error;
+            },
+        });
+    }
+}
+async function prepareRegisteredToolWorkerCapability(params, input, payloadObservability) {
+    const operationId = params.projection.operation.operationId;
+    assertPreparedCapabilityScope(params, input, operationId);
+    const effectiveControls = resolveEffectiveOperationTargetControls({
+        descriptor: params.descriptor,
+        controls: input.controls,
+        runtimePathBindings: params.projection.runtimePathBindings ?? Object.freeze([]),
+        workingDirectory: input.call.workingDirectory,
+        sharedState: params.sharedState,
+    });
+    const selectedTargetReferences = projectSelectedTargetReferences(params.projection, effectiveControls, input.call.parentCallId === null
+        ? params.descriptor.selectionControlIds
+        : undefined);
+    const preparedPayload = await prepareOperationPayload({
+        projection: params.projection,
+        executor: payloadObservability.lifecycleEmitter,
+        sharedState: params.sharedState,
+        ...(params.payloadAuthor ? { payloadAuthor: params.payloadAuthor } : {}),
+        call: input.call,
+        // The payload contract still names this correlation executionId. During
+        // prepare it is deliberately non-canonical and never enters the ledger.
+        executionId: input.preparationId,
+        descriptor: params.descriptor,
+        intent: input.intent,
+        ...(input.authoringObjective
+            ? { authoringObjective: input.authoringObjective }
+            : {}),
+        controls: effectiveControls,
+        ...(input.dependencyResults
+            ? { dependencyResults: input.dependencyResults }
+            : {}),
+        settledCapabilityResults: input.settledCapabilityResults,
+        deferPayloadStageMaterialized: payloadObservability.deferPayloadStageMaterialized,
+        ...(input.executionFreshness
+            ? { executionFreshness: input.executionFreshness }
+            : {}),
+    });
+    if (preparedPayload.status === "rejected") {
+        return preparedRuntimeRejection({
+            params,
+            input,
+            operationId,
+            effectiveControls,
+            selectedTargetReferences,
+            rejectedExecution: preparedPayload,
+            payloadObservability,
+        });
+    }
+    const normalPreparation = params.executor.prepare({
+        handle: params.projection.handle,
+        controls: effectiveControls,
+        ...(preparedPayload.body === undefined
+            ? {}
+            : { payload: preparedPayload.body }),
+        ...(preparedPayload.materializedParams === undefined
+            ? {}
+            : { materializedParams: preparedPayload.materializedParams }),
+        intent: input.intent,
+    });
+    if (normalPreparation.status === "rejected") {
+        const canonicalRejection = payloadRejection(normalPreparation.code, normalPreparation.message);
+        return preparedRuntimeRejection({
+            params,
+            input,
+            operationId,
+            effectiveControls,
+            selectedTargetReferences,
+            rejectedExecution: canonicalRejection,
+            payloadObservability,
+            ...(preparedPayload.body === undefined
+                ? {}
+                : { payload: preparedPayload.body }),
+            ...(preparedPayload.materializedParams === undefined
+                ? {}
+                : { materializedParams: preparedPayload.materializedParams }),
+        });
+    }
+    return Object.freeze({
+        actionFingerprint: normalPreparation.actionFingerprint,
+        acceptedControls: normalPreparation.acceptedControls,
+        execute: async (executionId) => {
+            try {
+                payloadObservability.release(executionId);
+                tracePreparedExecutionStarted(params, input, operationId, executionId);
                 const rejectedExecution = executionFreshnessRejection(input.executionFreshness);
                 if (rejectedExecution) {
-                    return completeRejectedExecution(rejectedExecution);
+                    return completeRuntimeRejection({
+                        params,
+                        input,
+                        operationId,
+                        executionId,
+                        selectedTargetReferences,
+                        rejectedExecution,
+                    });
                 }
-                const externalResult = await params.executor.execute({
-                    handle: params.projection.handle,
-                    controls: effectiveControls,
-                    ...(preparedPayload.body === undefined
-                        ? {}
-                        : { payload: preparedPayload.body }),
-                    ...(preparedPayload.materializedParams === undefined
-                        ? {}
-                        : {
-                            materializedParams: preparedPayload.materializedParams,
-                        }),
-                    intent: input.intent,
-                });
-                const observed = observeExternalResult(externalResult, operationEffect, input.call.parentCallId === null);
+                const externalResult = await normalPreparation.execute();
+                const observed = observeExternalResult(externalResult, params.projection.operation.effect, input.call.parentCallId === null);
                 const observedResult = attachTargetReferences(observed.result, selectedTargetReferences);
-                traceRegisteredToolWorkerCapabilityExecutionCompleted(params.diagnostic, operationId, input.call, input.executionId, observedResult, externalResult.status, {
+                traceRegisteredToolWorkerCapabilityExecutionCompleted(params.diagnostic, operationId, input.call, executionId, observedResult, externalResult.status, {
                     ...(observed.sourceIssueCode
                         ? { sourceIssueCode: observed.sourceIssueCode }
                         : {}),
@@ -145,11 +210,77 @@ function createWorkerAdapter(params) {
                 return observedResult;
             }
             catch (error) {
-                traceRegisteredToolWorkerCapabilityExecutionFailed(params.diagnostic, operationId, input.call, input.executionId, error, error instanceof RegisteredToolWorkerCapabilityExecutionError
-                    ? error.issueCode
-                    : "execution_failed");
+                tracePreparedExecutionFailed(params, input, operationId, executionId, error);
+                throw error;
+            }
+        },
+    });
+}
+function preparedRuntimeRejection(input) {
+    return Object.freeze({
+        actionFingerprint: createRegisteredToolPreparationAttemptFingerprint({
+            operationId: input.operationId,
+            controls: input.effectiveControls,
+            rejectionCode: input.rejectedExecution.sourceIssueCode,
+            ...(input.payload === undefined ? {} : { payload: input.payload }),
+            ...(input.materializedParams === undefined
+                ? {}
+                : { materializedParams: input.materializedParams }),
+        }),
+        acceptedControls: input.effectiveControls,
+        execute: async (executionId) => {
+            try {
+                input.payloadObservability.release(executionId);
+                tracePreparedExecutionStarted(input.params, input.input, input.operationId, executionId);
+                return completeRuntimeRejection({ ...input, executionId });
+            }
+            catch (error) {
+                tracePreparedExecutionFailed(input.params, input.input, input.operationId, executionId, error);
                 throw error;
             }
         },
     });
 }
+function completeRuntimeRejection(input) {
+    const canonicalResult = Object.freeze({
+        ...input.rejectedExecution.result,
+        exactResult: input.rejectedExecution.exactResult,
+    });
+    const preparedResult = attachTargetReferences(canonicalResult, input.selectedTargetReferences);
+    traceRegisteredToolWorkerCapabilityExecutionCompleted(input.params.diagnostic, input.operationId, input.input.call, input.executionId, preparedResult, "rejected", {
+        sourceIssueCode: input.rejectedExecution.sourceIssueCode,
+        summaryProjection: "runtime_rejection",
+        completionActions: Object.freeze([]),
+    });
+    return preparedResult;
+}
+function assertPreparedCapabilityScope(params, input, operationId) {
+    try {
+        const capabilityScope = projectWorkerCapabilityScope({
+            entries: params.scopeDescriptors,
+            scope: input.call.workerCapabilityScope,
+            descriptorOf: (descriptor) => descriptor,
+        });
+        assertWorkerCapabilityWithinScope(capabilityScope, params.descriptor);
+    }
+    catch (error) {
+        const scopedError = error instanceof WorkerCapabilityScopeError
+            ? new RegisteredToolWorkerCapabilityCompositionError(error.issueCode, operationId)
+            : error;
+        throw scopedError;
+    }
+}
+function tracePreparedExecutionStarted(params, input, operationId, executionId) {
+    traceRegisteredToolWorkerCapabilityExecutionStarted(params.diagnostic, operationId, input.call, executionId, input.intent.length, Object.keys(input.controls).length);
+}
+function tracePreparedExecutionFailed(params, input, operationId, executionId, error, issueCode = error instanceof RegisteredToolWorkerCapabilityExecutionError
+    ? error.issueCode
+    : "execution_failed") {
+    traceRegisteredToolWorkerCapabilityExecutionFailed(params.diagnostic, operationId, input.call, executionId, error, issueCode);
+}
+function registeredPreparationFailureIssueCode(error) {
+    return error instanceof RegisteredToolWorkerCapabilityExecutionError ||
+        error instanceof RegisteredToolWorkerCapabilityCompositionError
+        ? error.issueCode
+        : "execution_failed";
+}

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/failure-outcome-fingerprint.d.ts

@@ -0,0 +1,7 @@
+import type { CapabilityAdapterResult } from "../../orchestration/capability-adapters/index.js";
+import type { RoleOperationOutcomeFingerprint } from "../../orchestration/role-calls/index.js";
+/**
+ * Owns stable failure interpretation for the registered-tool adapter. The
+ * generic capability engine receives only the resulting opaque identity.
+ */
+export declare function createRegisteredToolWorkerFailureOutcomeFingerprint(exactResult: CapabilityAdapterResult): RoleOperationOutcomeFingerprint | null;