@abot-ai/runtime 1.0.0 → 1.1.0

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

@@ -1,9 +1,11 @@
-import { type RoleCallFrame, type RoleCallDependencyResult, type RoleCallLedger, type RoleCapabilityEffect, type RoleCapabilityDeclaredEffect, type RoleCapabilityExecutionOutcome, type RoleCapabilityObservedEffect, type RoleCapabilityResultReference } from "../role-calls/index.js";
+import { type RoleCallFrame, type RoleCallDependencyResult, type RoleCallLedger, type RoleCallOperationSupervisionInterventionCommit, 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;
+/** Immutable Worker-only assignment for authoring one capability payload. */
+export declare const WORKER_CAPABILITY_AUTHORING_OBJECTIVE_MAX_LENGTH = 8192;
 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;
@@ -63,6 +65,8 @@ export type WorkerCapabilityDescriptor = Readonly<{
     controlsRefinement?: "mechanical_when_complete";
     /** Manifest-owned routing metadata projected only in capability selection. */
     catalogGroups?: readonly ToolCatalogGroup[];
+    /** Canonical payload contract requires a Worker authoring receipt. */
+    requiresPayloadAuthoringObjective?: true;
 }>;
 export type WorkerCapabilityControls = Readonly<Record<string, unknown>>;
 /**
@@ -97,17 +101,57 @@ export type WorkerCapabilityAdapterResult = Readonly<{
     references?: readonly RoleCapabilityResultReference[];
     /** Canonical adapter-owned result persisted for every settled execution. */
     exactResult?: CapabilityAdapterResult;
+    /**
+     * Opaque adapter-owned stable failure identity. `null` explicitly opts
+     * this one failure out of supervision; omission is a contract violation.
+     */
+    failureOutcomeFingerprint: string | null;
+}>;
+export type WorkerCapabilityAdapterExecutionInput<TContext> = Readonly<{
+    context: TContext;
+    call: RoleCallFrame;
+    executionId: string;
+    /** Client-facing presentation metadata for lifecycle events only. */
+    intent: string;
+    /** Worker-only payload assignment; forbidden for root and non-payload calls. */
+    authoringObjective?: string;
+    controls: WorkerCapabilityControls;
+    settledCapabilityResults: readonly WorkerSettledCapabilityResult[];
+    dependencyResults?: readonly RoleCallDependencyResult[];
+    executionFreshness?: WorkerCapabilityExecutionFreshness;
+}>;
+export type WorkerCapabilityPreparedExecution = Readonly<{
+    /** Opaque exact-action identity required from every preparing adapter. */
+    actionFingerprint?: string;
+    /**
+     * Canonical non-payload controls accepted by the preparing adapter,
+     * including any adapter-validated staged controls hidden from selection.
+     */
+    acceptedControls: WorkerCapabilityControls;
+    execute(executionId: string): Promise<WorkerCapabilityAdapterResult>;
+}>;
+export type WorkerCapabilityAdapterPreparationInput<TContext> = Readonly<Omit<WorkerCapabilityAdapterExecutionInput<TContext>, "executionId"> & {
+    /** Non-canonical correlation for payload preparation and diagnostics only. */
+    preparationId: string;
 }>;
 export type WorkerCapabilityExecutionReference = Readonly<{
     executionId: string;
 }>;
+export type WorkerCapabilityOperationInterventionReference = Readonly<{
+    kind: "operation_supervision_intervened";
+    commit: RoleCallOperationSupervisionInterventionCommit;
+}>;
+export type WorkerCapabilityAttemptReference = WorkerCapabilityExecutionReference | WorkerCapabilityOperationInterventionReference;
 export type WorkerCapabilityBatchExecutionReference = Readonly<{
     executionIds: readonly string[];
 }>;
+export type WorkerCapabilityBatchAttemptReference = WorkerCapabilityBatchExecutionReference | WorkerCapabilityOperationInterventionReference;
 export type WorkerCapabilityInvocation = Readonly<{
     capabilityId: string;
     /** Client-facing presentation metadata; execution must not infer from it. */
     intent: string;
+    /** Present only when the selected descriptor requires payload authoring. */
+    authoringObjective?: string;
     controls: WorkerCapabilityControls;
 }>;
 export type WorkerSettledCapabilityResult = Readonly<{
@@ -126,17 +170,14 @@ export type WorkerSettledCapabilityResult = Readonly<{
 }>;
 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>;
+    /**
+     * Optional exact-action preparation seam. Production tool adapters use this
+     * to materialize and normalize the complete invocation before admission.
+     * It must not perform the capability's externally observable effect; only
+     * the returned execute closure may do that after canonical admission.
+     */
+    prepare?(input: WorkerCapabilityAdapterPreparationInput<TContext>): Promise<WorkerCapabilityPreparedExecution>;
+    execute(input: WorkerCapabilityAdapterExecutionInput<TContext>): Promise<WorkerCapabilityAdapterResult>;
 }>;
 /**
  * Lazy request-scoped source of neutral Worker capabilities. Implementations
@@ -166,13 +207,15 @@ export type WorkerCapabilityBinding<TContext> = Readonly<{
     execute(input: Readonly<{
         capabilityId: string;
         intent: unknown;
+        authoringObjective?: unknown;
         controls: unknown;
-    }>): Promise<WorkerCapabilityExecutionReference>;
+    }>): Promise<WorkerCapabilityAttemptReference>;
     executeBatch(input: Readonly<{
         invocations: readonly Readonly<{
             capabilityId: string;
             intent: unknown;
+            authoringObjective?: unknown;
             controls: unknown;
         }>[];
-    }>): Promise<WorkerCapabilityBatchExecutionReference>;
+    }>): Promise<WorkerCapabilityBatchAttemptReference>;
 }>;

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

@@ -1,7 +1,9 @@
-import { ROLE_CAPABILITY_ID_MAX_LENGTH, } from "../role-calls/index.js";
+import { ROLE_CAPABILITY_ID_MAX_LENGTH, ROLE_CALL_OBJECTIVE_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;
+/** Immutable Worker-only assignment for authoring one capability payload. */
+export const WORKER_CAPABILITY_AUTHORING_OBJECTIVE_MAX_LENGTH = ROLE_CALL_OBJECTIVE_MAX_LENGTH;
 export const WORKER_CAPABILITY_SUMMARY_MAX_LENGTH = 512;
 export const WORKER_CAPABILITY_COUNT_MAX = 64;
 export const WORKER_CAPABILITY_CONTROL_COUNT_MAX = 16;

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

@@ -16,3 +16,10 @@ export type WorkerCapabilityControlsValidation = Readonly<{
 }>;
 export declare function normalizeWorkerCapabilityControlsSchema(input: unknown): WorkerCapabilityControlsSchemaNormalization;
 export declare function validateWorkerCapabilityControls(schema: WorkerCapabilityControlsSchema, input: unknown): WorkerCapabilityControlsValidation;
+/**
+ * Captures the complete non-payload action already accepted by a preparing
+ * adapter. These controls may include staged values that are deliberately
+ * absent from the model-facing descriptor, so only the shared flat controls
+ * envelope is enforced here.
+ */
+export declare function validateWorkerCapabilityAcceptedControls(input: unknown): WorkerCapabilityControlsValidation;

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

@@ -65,6 +65,33 @@ export function validateWorkerCapabilityControls(schema, input) {
     }
     return { ok: true, value: Object.freeze(controls) };
 }
+/**
+ * Captures the complete non-payload action already accepted by a preparing
+ * adapter. These controls may include staged values that are deliberately
+ * absent from the model-facing descriptor, so only the shared flat controls
+ * envelope is enforced here.
+ */
+export function validateWorkerCapabilityAcceptedControls(input) {
+    if (!isPlainRecord(input)) {
+        return failure("accepted_controls_not_object");
+    }
+    const entries = Object.entries(input);
+    if (entries.length > WORKER_CAPABILITY_CONTROL_COUNT_MAX) {
+        return failure("accepted_controls_count_invalid");
+    }
+    const controls = {};
+    for (const [controlId, inputValue] of entries) {
+        if (!isControlId(controlId)) {
+            return failure("accepted_controls_id_invalid", controlId);
+        }
+        const value = normalizeAcceptedControlValue(inputValue);
+        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");
@@ -190,6 +217,29 @@ function normalizeControlValue(control, input) {
     }
     return normalizeScalarValue(control, input);
 }
+function normalizeAcceptedControlValue(input) {
+    if (!Array.isArray(input))
+        return normalizeAcceptedScalarValue(input);
+    if (input.length > WORKER_CAPABILITY_CONTROL_ARRAY_MAX_ITEMS) {
+        return failure("accepted_controls_array_invalid");
+    }
+    const values = [];
+    for (const item of input) {
+        const value = normalizeAcceptedScalarValue(item);
+        if (!value.ok)
+            return value;
+        values.push(value.value);
+    }
+    return { ok: true, value: Object.freeze(values) };
+}
+function normalizeAcceptedScalarValue(input) {
+    if (typeof input === "string" ||
+        typeof input === "boolean" ||
+        (typeof input === "number" && Number.isFinite(input))) {
+        return { ok: true, value: input };
+    }
+    return failure("accepted_controls_value_invalid");
+}
 function normalizeScalarValue(control, input) {
     if (control.type === "string") {
         if (typeof input !== "string") {

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

@@ -0,0 +1,5 @@
+/** Returns only an opaque digest; raw thrown values never cross this boundary. */
+export declare function createStableWorkerCapabilityErrorFingerprint(input: {
+    domain: "prepare" | "execute";
+    error: unknown;
+}): string | undefined;

package/dist/src/runtime/orchestration/worker-capabilities/error-fingerprint.js

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+const ERROR_NAME_MAX_LENGTH = 128;
+const ERROR_MESSAGE_MAX_LENGTH = 4_096;
+const ERROR_FIELD_MAX_LENGTH = 512;
+const STABLE_ERROR_FIELD_IDS = Object.freeze([
+    "stage",
+    "code",
+    "errorCode",
+    "issueCode",
+    "status",
+    "exitCode",
+]);
+/** Returns only an opaque digest; raw thrown values never cross this boundary. */
+export function createStableWorkerCapabilityErrorFingerprint(input) {
+    try {
+        const identity = stableErrorIdentity(input.error);
+        if (identity === undefined)
+            return undefined;
+        const canonical = JSON.stringify([
+            "worker_capability_error_v1",
+            input.domain,
+            identity,
+        ]);
+        return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function stableErrorIdentity(error) {
+    if (error instanceof Error) {
+        const name = canonicalErrorName(error.name);
+        if (name === undefined)
+            return undefined;
+        const fields = stableErrorFields(error);
+        if (!fields.ok)
+            return undefined;
+        if (fields.value.length > 0) {
+            return Object.freeze(["error_fields_v1", name, fields.value]);
+        }
+        if (error.cause !== undefined)
+            return undefined;
+        const message = canonicalErrorMessage(error.message);
+        return message === undefined
+            ? undefined
+            : Object.freeze(["error_message_v1", name, message]);
+    }
+    if (!isPlainRecord(error))
+        return undefined;
+    const fields = stableErrorFields(error);
+    if (!fields.ok)
+        return undefined;
+    const name = optionalCanonicalErrorName(error.name);
+    if (!name.ok)
+        return undefined;
+    if (fields.value.length > 0) {
+        return Object.freeze(["thrown_fields_v1", name.value, fields.value]);
+    }
+    if (Object.keys(error).some((key) => key !== "name" && key !== "message")) {
+        return undefined;
+    }
+    const message = canonicalErrorMessage(error.message);
+    return name.value === null || message === undefined
+        ? undefined
+        : Object.freeze(["thrown_message_v1", name.value, message]);
+}
+function stableErrorFields(error) {
+    const record = error;
+    const fields = [];
+    for (const key of STABLE_ERROR_FIELD_IDS) {
+        const value = record[key];
+        if (value === undefined || value === null || value === "")
+            continue;
+        if (typeof value === "string" &&
+            value.length <= ERROR_FIELD_MAX_LENGTH &&
+            value === value.trim()) {
+            fields.push(Object.freeze([key, value]));
+            continue;
+        }
+        if (typeof value === "number" && Number.isFinite(value)) {
+            fields.push(Object.freeze([key, value]));
+            continue;
+        }
+        return Object.freeze({ ok: false });
+    }
+    return Object.freeze({ ok: true, value: Object.freeze(fields) });
+}
+function optionalCanonicalErrorName(value) {
+    if (value === undefined || value === null) {
+        return Object.freeze({ ok: true, value: null });
+    }
+    const name = canonicalErrorName(value);
+    return name === undefined
+        ? Object.freeze({ ok: false })
+        : Object.freeze({ ok: true, value: name });
+}
+function canonicalErrorName(value) {
+    return typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= ERROR_NAME_MAX_LENGTH &&
+        /^[A-Za-z][A-Za-z0-9_.:-]*$/.test(value)
+        ? value
+        : undefined;
+}
+function canonicalErrorMessage(value) {
+    return typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= ERROR_MESSAGE_MAX_LENGTH &&
+        value === value.trim()
+        ? value
+        : undefined;
+}
+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;
+}

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

@@ -0,0 +1,6 @@
+export declare const WORKER_CAPABILITY_OPERATION_SUPERVISION_LIMIT_ERROR: "worker_capability_begin_rejected:operation_supervision_limit_exceeded";
+export declare class WorkerCapabilityOperationSupervisionLimitError extends Error {
+    readonly issueCode: "operation_supervision_limit_exceeded";
+    constructor();
+}
+export declare function isWorkerCapabilityOperationSupervisionLimitError(error: unknown): error is WorkerCapabilityOperationSupervisionLimitError;

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

@@ -0,0 +1,11 @@
+export const WORKER_CAPABILITY_OPERATION_SUPERVISION_LIMIT_ERROR = "worker_capability_begin_rejected:operation_supervision_limit_exceeded";
+export class WorkerCapabilityOperationSupervisionLimitError extends Error {
+    issueCode = "operation_supervision_limit_exceeded";
+    constructor() {
+        super(WORKER_CAPABILITY_OPERATION_SUPERVISION_LIMIT_ERROR);
+        this.name = "WorkerCapabilityOperationSupervisionLimitError";
+    }
+}
+export function isWorkerCapabilityOperationSupervisionLimitError(error) {
+    return error instanceof WorkerCapabilityOperationSupervisionLimitError;
+}

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

@@ -0,0 +1,7 @@
+import { type CapabilityAdapterResult } from "../../capability-adapters/result.js";
+import type { WorkerCapabilityAdapterResult } from "../contracts.js";
+export type CanonicalWorkerCapabilityAdapterResult = WorkerCapabilityAdapterResult & Readonly<{
+    exactResult: CapabilityAdapterResult;
+}>;
+export declare function exactResultNormalizationIssueCode(error: unknown): string;
+export declare function attachCanonicalExactResult(normalized: WorkerCapabilityAdapterResult, raw?: WorkerCapabilityAdapterResult): CanonicalWorkerCapabilityAdapterResult;

package/dist/src/runtime/orchestration/worker-capabilities/execution/adapter-exact-result.js

@@ -0,0 +1,35 @@
+import { captureLegacyCapabilityAdapterResult, normalizeCapabilityAdapterResult, } from "../../capability-adapters/result.js";
+export function exactResultNormalizationIssueCode(error) {
+    if (!(error instanceof Error))
+        return "adapter_result_unreadable";
+    const prefix = "capability_exact_result_invalid:";
+    if (!error.message.startsWith(prefix))
+        return "adapter_result_unreadable";
+    const code = error.message.slice(prefix.length);
+    if (!isKnownExactResultIssueCode(code))
+        return "adapter_result_unreadable";
+    return `adapter_${code}`;
+}
+export function attachCanonicalExactResult(normalized, raw = normalized) {
+    const exact = raw.exactResult === undefined
+        ? captureLegacyCapabilityAdapterResult(omitAdapterBoundaryMetadata(raw))
+        : normalizeCapabilityAdapterResult(raw.exactResult);
+    if (!exact.ok) {
+        throw new Error(`capability_exact_result_invalid:${exact.code}`);
+    }
+    return Object.freeze({
+        ...normalized,
+        exactResult: exact.value,
+    });
+}
+function isKnownExactResultIssueCode(code) {
+    return (code === "result_invalid" ||
+        code === "result_not_json_safe" ||
+        code === "result_too_large");
+}
+function omitAdapterBoundaryMetadata(result) {
+    if (result.outcome === "succeeded")
+        return result;
+    const { failureOutcomeFingerprint: _failureOutcomeFingerprint, ...evidence } = result;
+    return evidence;
+}

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

@@ -0,0 +1,9 @@
+import type { WorkerCapabilityDescriptor, WorkerCapabilityPreparedExecution } from "../contracts.js";
+import { type WorkerCapabilityDiagnosticContext } from "../diagnostics.js";
+import { type CanonicalWorkerCapabilityExecution } from "./adapter-result-normalization.js";
+export declare function executePreparedAndNormalizeAdapter(params: {
+    prepared: WorkerCapabilityPreparedExecution;
+    descriptor: WorkerCapabilityDescriptor;
+    diagnostic: WorkerCapabilityDiagnosticContext;
+    executionId: string;
+}): Promise<CanonicalWorkerCapabilityExecution>;

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

@@ -0,0 +1,28 @@
+import { createWorkerCapabilityExecutionErrorOutcomeFingerprint, createWorkerCapabilityResultRejectionOutcomeFingerprint, } from "../outcome-fingerprint.js";
+import { traceWorkerCapabilityExecutionFailed, traceWorkerCapabilityResultRejected, } from "../diagnostics.js";
+import { createTechnicalExecutionFailureResult, normalizeCompletedAdapterExecution, } from "./adapter-result-normalization.js";
+export async function executePreparedAndNormalizeAdapter(params) {
+    let rawResult;
+    try {
+        rawResult = await params.prepared.execute(params.executionId);
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError")
+            throw error;
+        traceWorkerCapabilityExecutionFailed(params.diagnostic, params.descriptor, error, params.executionId);
+        const result = createTechnicalExecutionFailureResult(error);
+        const outcomeFingerprint = createWorkerCapabilityExecutionErrorOutcomeFingerprint(error);
+        return Object.freeze({
+            result,
+            ...(outcomeFingerprint ? { outcomeFingerprint } : {}),
+        });
+    }
+    const normalized = normalizeCompletedAdapterExecution(rawResult, params.descriptor.effect);
+    if (normalized.ok)
+        return normalized.execution;
+    traceWorkerCapabilityResultRejected(params.diagnostic, params.descriptor, normalized.issueCode, params.executionId);
+    return Object.freeze({
+        result: normalized.result,
+        outcomeFingerprint: createWorkerCapabilityResultRejectionOutcomeFingerprint(normalized.issueCode),
+    });
+}

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

@@ -0,0 +1,18 @@
+import { type RoleOperationOutcomeFingerprint } from "../../role-calls/index.js";
+import type { WorkerCapabilityAdapterResult, WorkerCapabilityEffect } from "../contracts.js";
+import { type CanonicalWorkerCapabilityAdapterResult } from "./adapter-exact-result.js";
+export type { CanonicalWorkerCapabilityAdapterResult } from "./adapter-exact-result.js";
+export type CanonicalWorkerCapabilityExecution = Readonly<{
+    result: CanonicalWorkerCapabilityAdapterResult;
+    outcomeFingerprint?: RoleOperationOutcomeFingerprint;
+}>;
+export type CompletedAdapterNormalization = Readonly<{
+    ok: true;
+    execution: CanonicalWorkerCapabilityExecution;
+}> | Readonly<{
+    ok: false;
+    issueCode: string;
+    result: CanonicalWorkerCapabilityAdapterResult;
+}>;
+export declare function createTechnicalExecutionFailureResult(error: unknown): CanonicalWorkerCapabilityAdapterResult;
+export declare function normalizeCompletedAdapterExecution(input: WorkerCapabilityAdapterResult, declaredEffect: WorkerCapabilityEffect): CompletedAdapterNormalization;

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

@@ -0,0 +1,197 @@
+import { ROLE_CAPABILITY_REFERENCE_DATA_MAX_LENGTH, ROLE_CALL_RESULT_MAX_LENGTH, isRoleOperationOutcomeFingerprintForOutcome, } from "../../role-calls/index.js";
+import { attachCanonicalExactResult, exactResultNormalizationIssueCode, } from "./adapter-exact-result.js";
+import { normalizeResultReferences } from "./adapter-result-references.js";
+const TECHNICAL_EXECUTION_FAILURE_SUMMARY = "The capability failed before returning a valid result.";
+const INVALID_EXECUTION_RESULT_SUMMARY = "The capability returned an invalid result.";
+const OVERSIZED_EXECUTION_RESULT_SUMMARY = "The capability result exceeded the Runtime evidence size limit.";
+export function createTechnicalExecutionFailureResult(error) {
+    return attachCanonicalExactResult(technicalFailure(adapterExecutionFailureSummary(error)));
+}
+export function normalizeCompletedAdapterExecution(input, declaredEffect) {
+    let normalized;
+    try {
+        normalized = normalizeAdapterResult(input, declaredEffect);
+    }
+    catch (error) {
+        normalized = {
+            ok: false,
+            issueCode: exactResultNormalizationIssueCode(error),
+        };
+    }
+    if (normalized.ok) {
+        return {
+            ok: true,
+            execution: canonicalExecution(normalized.value),
+        };
+    }
+    return {
+        ok: false,
+        issueCode: normalized.issueCode,
+        result: attachCanonicalExactResult(technicalFailure(normalized.issueCode === "adapter_result_too_large"
+            ? OVERSIZED_EXECUTION_RESULT_SUMMARY
+            : INVALID_EXECUTION_RESULT_SUMMARY)),
+    };
+}
+function normalizeAdapterResult(input, declaredEffect) {
+    if (!isAdapterResultRecord(input)) {
+        return { ok: false, issueCode: "adapter_result_not_object" };
+    }
+    if (!hasSupportedAdapterResultShape(input)) {
+        return { ok: false, issueCode: "adapter_result_shape_invalid" };
+    }
+    if (!hasValidAdapterResultSummary(input.summary)) {
+        return { ok: false, issueCode: "adapter_result_summary_invalid" };
+    }
+    if (!hasValidAdapterReferenceData(input.referenceData)) {
+        return { ok: false, issueCode: "adapter_result_reference_data_invalid" };
+    }
+    const references = normalizeResultReferences(input.references);
+    if (references === null) {
+        return { ok: false, issueCode: "adapter_result_references_invalid" };
+    }
+    if (input.outcome === "succeeded") {
+        return normalizeSucceededAdapterResult(input, declaredEffect, references);
+    }
+    if (input.outcome === "failed") {
+        return normalizeFailedAdapterResult(input, declaredEffect, references);
+    }
+    return { ok: false, issueCode: "adapter_result_outcome_invalid" };
+}
+function normalizeSucceededAdapterResult(input, declaredEffect, references) {
+    if (Object.hasOwn(input, "failureOutcomeFingerprint")) {
+        return {
+            ok: false,
+            issueCode: "adapter_result_failure_outcome_fingerprint_unexpected",
+        };
+    }
+    if (!isSuccessfulObservedEffectCompatible(input.observedEffect, declaredEffect)) {
+        return { ok: false, issueCode: "observed_effect_mismatch" };
+    }
+    return {
+        ok: true,
+        value: attachCanonicalExactResult(Object.freeze({
+            outcome: "succeeded",
+            observedEffect: input.observedEffect,
+            summary: input.summary.trim(),
+            ...(input.referenceData
+                ? { referenceData: input.referenceData.trim() }
+                : {}),
+            ...(references ? { references } : {}),
+        }), input),
+    };
+}
+function normalizeFailedAdapterResult(input, declaredEffect, references) {
+    if (!Object.hasOwn(input, "failureOutcomeFingerprint")) {
+        return {
+            ok: false,
+            issueCode: "adapter_result_failure_outcome_fingerprint_missing",
+        };
+    }
+    if (input.failureOutcomeFingerprint !== null &&
+        !isRoleOperationOutcomeFingerprintForOutcome(input.failureOutcomeFingerprint, "failed")) {
+        return {
+            ok: false,
+            issueCode: "adapter_result_failure_outcome_fingerprint_invalid",
+        };
+    }
+    if (!isFailedObservedEffectCompatible(input.observedEffect, declaredEffect)) {
+        return { ok: false, issueCode: "failed_effect_invalid" };
+    }
+    return {
+        ok: true,
+        value: attachCanonicalExactResult(Object.freeze({
+            outcome: "failed",
+            observedEffect: input.observedEffect,
+            summary: input.summary.trim(),
+            ...(input.referenceData
+                ? { referenceData: input.referenceData.trim() }
+                : {}),
+            ...(references ? { references } : {}),
+            failureOutcomeFingerprint: input.failureOutcomeFingerprint,
+        }), input),
+    };
+}
+function isAdapterResultRecord(input) {
+    return typeof input === "object" && input !== null && !Array.isArray(input);
+}
+function hasSupportedAdapterResultShape(input) {
+    const keys = Object.keys(input);
+    if (keys.length < 3 || keys.length > 7)
+        return false;
+    if (!keys.includes("outcome"))
+        return false;
+    if (!keys.includes("observedEffect"))
+        return false;
+    if (!keys.includes("summary"))
+        return false;
+    return keys.every((key) => [
+        "outcome",
+        "observedEffect",
+        "summary",
+        "referenceData",
+        "references",
+        "exactResult",
+        "failureOutcomeFingerprint",
+    ].includes(key));
+}
+function hasValidAdapterResultSummary(input) {
+    return (typeof input === "string" &&
+        input.trim().length > 0 &&
+        input.length <= ROLE_CALL_RESULT_MAX_LENGTH);
+}
+function hasValidAdapterReferenceData(input) {
+    if (input === undefined)
+        return true;
+    return (typeof input === "string" &&
+        input.trim().length > 0 &&
+        input.length <= ROLE_CAPABILITY_REFERENCE_DATA_MAX_LENGTH);
+}
+function canonicalExecution(result) {
+    if (result.outcome === "succeeded") {
+        return Object.freeze({ result, outcomeFingerprint: "succeeded" });
+    }
+    const outcomeFingerprint = result.failureOutcomeFingerprint ?? undefined;
+    return Object.freeze({
+        result,
+        ...(outcomeFingerprint ? { outcomeFingerprint } : {}),
+    });
+}
+function adapterExecutionFailureSummary(error) {
+    if (!(error instanceof Error))
+        return TECHNICAL_EXECUTION_FAILURE_SUMMARY;
+    if (error.message.endsWith("canonical_result_result_too_large")) {
+        return OVERSIZED_EXECUTION_RESULT_SUMMARY;
+    }
+    if (error.message.endsWith("canonical_result_result_invalid")) {
+        return INVALID_EXECUTION_RESULT_SUMMARY;
+    }
+    if (error.message.endsWith("canonical_result_result_not_json_safe")) {
+        return INVALID_EXECUTION_RESULT_SUMMARY;
+    }
+    return TECHNICAL_EXECUTION_FAILURE_SUMMARY;
+}
+function isSuccessfulObservedEffectCompatible(observedEffect, declaredEffect) {
+    if (declaredEffect === "mixed") {
+        return observedEffect === "observation" || observedEffect === "mutation";
+    }
+    return observedEffect === declaredEffect;
+}
+function isFailedObservedEffectCompatible(observedEffect, declaredEffect) {
+    if (observedEffect === "none")
+        return true;
+    if (observedEffect === "indeterminate")
+        return true;
+    if (observedEffect === "observation")
+        return true;
+    if (observedEffect !== "mutation")
+        return false;
+    return declaredEffect === "mutation" || declaredEffect === "mixed";
+}
+function technicalFailure(summary) {
+    return Object.freeze({
+        outcome: "failed",
+        observedEffect: "indeterminate",
+        summary,
+        failureOutcomeFingerprint: null,
+    });
+}

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

@@ -0,0 +1,2 @@
+import { type RoleCapabilityResultReference } from "../../role-calls/index.js";
+export declare function normalizeResultReferences(input: unknown): readonly RoleCapabilityResultReference[] | undefined | null;