@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/runtime/steps/degraded-finalization/super.js

@@ -0,0 +1,128 @@
+import { RequestModelStepInvoker } from "../../model/invoke-step.js";
+import { resolveOutputIncompleteError } from "../../model/provider-completion.js";
+import { traceDebug } from "../../observability/debug-logger.js";
+import { ROLE_CALL_RESPONSE_MAX_LENGTH } from "../../orchestration/role-calls/index.js";
+import { resolveRequestSteeringInbox } from "../../request/request-steering.js";
+import { DEGRADED_FINALIZATION_STEP_ID, } from "./contract.js";
+import { buildDegradedFinalizationFallback } from "./fallback.js";
+import { buildDegradedFinalizationModelInput } from "./input.js";
+import { parseDegradedFinalizationPhrasing } from "./parser.js";
+import { renderDegradedFinalization } from "./render.js";
+/** One presentation attempt; this adapter owns no request or role transition. */
+export async function runSuperDegradedFinalization(params) {
+    const fallback = createSuperFailureFallback(params.input, params.steeringVersion);
+    const attemptRejection = resolveSuperFailureAttemptRejection(params);
+    if (attemptRejection) {
+        traceDebug("runtime.degraded_finalization", "super.skipped", {
+            requestId: params.request.requestId,
+            primaryCode: params.input.problem.code,
+            secondaryCode: attemptRejection,
+            source: "runtime_fallback",
+        });
+        return withSecondary(fallback, attemptRejection);
+    }
+    try {
+        const steering = resolveRequestSteeringInbox(params.request.requestSteering).snapshot();
+        const modelInput = buildDegradedFinalizationModelInput({
+            request: params.request,
+            input: params.input,
+            languageSampleText: steering.updates.at(-1)?.text,
+        });
+        const phrasing = await new RequestModelStepInvoker(params.request, params.request.onEvent).invoke({
+            modelStep: DEGRADED_FINALIZATION_STEP_ID,
+            messages: modelInput.messages,
+            format: modelInput.format,
+            boundSteeringVersion: params.steeringVersion,
+            timeoutReason: "degraded_finalization_timeout",
+            accept(text, diagnostics) {
+                const incomplete = resolveOutputIncompleteError(diagnostics);
+                if (incomplete)
+                    throw incomplete;
+                const parsed = parseDegradedFinalizationPhrasing(text);
+                if (!parsed)
+                    throw new Error("invalid_degraded_finalization_output");
+                return parsed;
+            },
+        });
+        if (params.request.abortSignal.aborted)
+            return fallback;
+        const output = renderBoundedSuperFailure(params.input, phrasing, params.maxResponseChars);
+        if (!output)
+            return withSecondary(fallback, "degraded_finalization_response_too_long");
+        return Object.freeze({
+            output,
+            source: "model",
+            steeringVersion: params.steeringVersion,
+        });
+    }
+    catch (error) {
+        const secondaryCode = boundedSuperFailureCode(error);
+        traceDebug("runtime.degraded_finalization", "super.fallback", {
+            requestId: params.request.requestId,
+            primaryCode: params.input.problem.code,
+            secondaryCode,
+            source: "runtime_fallback",
+        });
+        return withSecondary(fallback, secondaryCode);
+    }
+}
+export function createSuperFailureFallback(input, steeringVersion) {
+    const output = buildDegradedFinalizationFallback({
+        ...input,
+        progress: null,
+    });
+    if (!fitsSuperFailureResponse(output, ROLE_CALL_RESPONSE_MAX_LENGTH))
+        throw new Error("degraded_finalization_outer_response_limit_invalid");
+    return Object.freeze({ output, source: "runtime_fallback", steeringVersion });
+}
+export function fitsSuperFailureResponse(output, limit) {
+    if (!Number.isSafeInteger(limit))
+        return false;
+    if (limit <= 0)
+        return false;
+    return output.length <= Math.min(limit, ROLE_CALL_RESPONSE_MAX_LENGTH);
+}
+export function boundedSuperFailureCode(error) {
+    const value = error instanceof Error ? error.message : "request_failed";
+    return /^[a-z][a-z0-9_]{0,159}$/iu.test(value) ? value : "request_failed";
+}
+function resolveSuperFailureAttemptRejection(params) {
+    if (params.request.abortSignal.aborted)
+        return boundedSuperFailureCode(params.request.abortSignal.reason);
+    const config = params.request.runnerConfig.steps[DEGRADED_FINALIZATION_STEP_ID];
+    if (!config)
+        return "missing_degraded_finalization_config";
+    if (!Number.isFinite(config.timeoutMs))
+        return "degraded_finalization_timeout_invalid";
+    if (config.timeoutMs <= 0)
+        return "degraded_finalization_timeout_invalid";
+    if (hasExpiredRequestBudget(params.readBudgets?.()))
+        return "request_deadline_exhausted";
+    if (!resolveRequestSteeringInbox(params.request.requestSteering).isCurrent(params.steeringVersion))
+        return "degraded_finalization_steering_superseded";
+    if (!fitsSuperFailureResponse(createSuperFailureFallback(params.input, params.steeringVersion).output, params.maxResponseChars))
+        return "degraded_finalization_response_limit_invalid";
+    return undefined;
+}
+function hasExpiredRequestBudget(budgets) {
+    if (!budgets)
+        return false;
+    if (budgets.requestTimeoutMs > 0 && budgets.requestRemainingMs <= 0)
+        return true;
+    return budgets.inactivityTimeoutMs > 0 && budgets.inactivityRemainingMs <= 0;
+}
+function renderBoundedSuperFailure(input, phrasing, limit) {
+    const complete = renderDegradedFinalization({ input, phrasing });
+    if (fitsSuperFailureResponse(complete, limit))
+        return complete;
+    const withoutProgress = renderDegradedFinalization({
+        input: { ...input, progress: null },
+        phrasing,
+    });
+    return fitsSuperFailureResponse(withoutProgress, limit)
+        ? withoutProgress
+        : undefined;
+}
+function withSecondary(explanation, secondaryCode) {
+    return Object.freeze({ ...explanation, secondaryCode });
+}

package/dist/src/runtime/steps/execution-agent/capability-decision-parsing.d.ts

@@ -6,6 +6,7 @@ export declare function parseCapabilityInvocation(params: Readonly<{
     value: unknown;
     path: string;
     capabilities: readonly PreparedExecutionAgentCapability[];
+    eligibleControlsEvidenceExecutionIds: readonly string[];
     observationOnly: boolean;
     includesAction: boolean;
     issues: ExecutionAgentDecisionValidationIssue[];

package/dist/src/runtime/steps/execution-agent/capability-decision-parsing.js

@@ -1,4 +1,5 @@
 import { CAPABILITY_INTENT_MAX_LENGTH, materializeCapabilityControlsIfComplete, validateCapabilitySelectionControls, } from "../../orchestration/capability-adapters/index.js";
+import { parseControlsEvidenceSelection, requiresControlsEvidenceSelection, } from "./controls-evidence-contract.js";
 import { normalizeExecutionWorkingDirectory } from "../../orchestration/capability-adapters/working-directory.js";
 import { executionCapabilityControlsIssue, normalizeGeneratedExecutionCapabilityControls, parseExecutionOperationObjective, requiresExecutionOperationObjective, } from "./capability-invocation-contract.js";
 import { EXECUTION_AGENT_CAPABILITY_SCOPE_GROUP_COUNT_MAX, } from "./contracts.js";
@@ -34,6 +35,7 @@ export function parseCapabilityBatch(value, contract, issues) {
             value: invocation,
             path: `decision.invocations.${index}`,
             capabilities: contract.capabilities,
+            eligibleControlsEvidenceExecutionIds: contract.eligibleControlsEvidenceExecutionIds,
             observationOnly: true,
             includesAction: false,
             issues,
@@ -73,9 +75,13 @@ export function parseCapabilityInvocation(params) {
     }
     const expectedKeys = [
         ...baseExpectedKeys,
-        ...(capability && requiresExecutionOperationObjective(capability.partition)
+        ...(capability &&
+            requiresExecutionOperationObjective(capability.partition, capability.requiresPayloadAuthoringObjective)
             ? ["operationObjective"]
             : []),
+        ...(capability && requiresControlsEvidenceSelection(capability.partition)
+            ? ["controlsEvidenceExecutionIds"]
+            : []),
         ...(capability?.partition.selectionControlIds.length
             ? ["selectionControls"]
             : []),
@@ -94,10 +100,18 @@ export function parseCapabilityInvocation(params) {
     const operationObjective = parseExecutionOperationObjective({
         value: record.operationObjective,
         required: capability !== undefined &&
-            requiresExecutionOperationObjective(capability.partition),
+            requiresExecutionOperationObjective(capability.partition, capability.requiresPayloadAuthoringObjective),
         path: `${params.path}.operationObjective`,
         issues: params.issues,
     });
+    const evidenceSelection = parseControlsEvidenceSelection({
+        value: record.controlsEvidenceExecutionIds,
+        required: capability !== undefined &&
+            requiresControlsEvidenceSelection(capability.partition),
+        eligible: params.eligibleControlsEvidenceExecutionIds,
+        path: `${params.path}.controlsEvidenceExecutionIds`,
+        issues: params.issues,
+    });
     let selectionControls;
     let controls;
     if (capability) {
@@ -136,7 +150,8 @@ export function parseCapabilityInvocation(params) {
     if (!capability ||
         (params.observationOnly && capability.effect !== "observation") ||
         intent === undefined ||
-        !operationObjective.ok) {
+        !operationObjective.ok ||
+        !evidenceSelection.ok) {
         return { expectedKeys };
     }
     return {
@@ -147,6 +162,9 @@ export function parseCapabilityInvocation(params) {
             ...(operationObjective.value
                 ? { operationObjective: operationObjective.value }
                 : {}),
+            ...(evidenceSelection.value
+                ? { controlsEvidenceExecutionIds: evidenceSelection.value }
+                : {}),
             ...(selectionControls ? { selectionControls } : {}),
             ...(controls ? { controls } : {}),
         }),

package/dist/src/runtime/steps/execution-agent/capability-invocation-contract.d.ts

@@ -7,7 +7,7 @@ type ParsedExecutionOperationObjective = Readonly<{
 }> | Readonly<{
     ok: false;
 }>;
-export declare function requiresExecutionOperationObjective(partition: CapabilityControlsPartition): boolean;
+export declare function requiresExecutionOperationObjective(partition: CapabilityControlsPartition, requiresPayloadAuthoringObjective?: boolean): boolean;
 export declare function executionOperationObjectiveSchema(): Record<string, unknown>;
 export declare function parseExecutionOperationObjective(params: Readonly<{
     value: unknown;

package/dist/src/runtime/steps/execution-agent/capability-invocation-contract.js

@@ -1,6 +1,8 @@
 export const EXECUTION_AGENT_OPERATION_OBJECTIVE_MAX_LENGTH = 4_096;
-const EXECUTION_AGENT_OPERATION_OBJECTIVE_DESCRIPTION = "Complete bounded operation for this invocation. This is internal execution input for controls refinement, not client-facing status, and cannot add unrelated request outcomes.";
-export function requiresExecutionOperationObjective(partition) {
+const EXECUTION_AGENT_OPERATION_OBJECTIVE_DESCRIPTION = "Complete bounded operation for this invocation, including all changes its payload must make. This is internal execution input for controls and payload authoring, not client-facing status, and cannot add unrelated request outcomes.";
+export function requiresExecutionOperationObjective(partition, requiresPayloadAuthoringObjective = false) {
+    if (requiresPayloadAuthoringObjective)
+        return true;
     return Object.keys(partition.remainingSchema.properties).length > 0;
 }
 export function executionOperationObjectiveSchema() {

package/dist/src/runtime/steps/execution-agent/capability-selection-schema.d.ts

@@ -0,0 +1,3 @@
+import type { PreparedExecutionAgentCapability } from "./format.js";
+/** Groups only capabilities whose complete model-facing invocation shapes agree. */
+export declare function projectCapabilitySelectionProperties(capabilities: readonly PreparedExecutionAgentCapability[], eligibleEvidence: readonly string[]): readonly Readonly<Record<string, unknown>>[];

package/dist/src/runtime/steps/execution-agent/capability-selection-schema.js

@@ -0,0 +1,72 @@
+import { CAPABILITY_INTENT_MAX_LENGTH, } from "../../orchestration/capability-adapters/index.js";
+import { executionOperationObjectiveSchema, requiresExecutionOperationObjective, } from "./capability-invocation-contract.js";
+import { controlsEvidenceSelectionSchema, requiresControlsEvidenceSelection, } from "./controls-evidence-contract.js";
+/** Groups only capabilities whose complete model-facing invocation shapes agree. */
+export function projectCapabilitySelectionProperties(capabilities, eligibleEvidence) {
+    const groups = new Map();
+    for (const capability of capabilities) {
+        const signature = JSON.stringify([
+            capability.partition.selectionSchema,
+            requiresExecutionOperationObjective(capability.partition, capability.requiresPayloadAuthoringObjective),
+            requiresControlsEvidenceSelection(capability.partition),
+        ]);
+        const group = groups.get(signature) ?? [];
+        group.push(capability);
+        groups.set(signature, group);
+    }
+    return Object.freeze([...groups.values()].map((group) => {
+        const representative = group[0];
+        const partition = representative.partition;
+        return Object.freeze({
+            capabilityId: {
+                type: "string",
+                enum: group.map(({ capabilityId }) => capabilityId),
+            },
+            intent: {
+                type: "string",
+                minLength: 1,
+                maxLength: CAPABILITY_INTENT_MAX_LENGTH,
+            },
+            ...(requiresExecutionOperationObjective(partition, representative.requiresPayloadAuthoringObjective)
+                ? { operationObjective: executionOperationObjectiveSchema() }
+                : {}),
+            ...(requiresControlsEvidenceSelection(partition)
+                ? {
+                    controlsEvidenceExecutionIds: controlsEvidenceSelectionSchema(eligibleEvidence),
+                }
+                : {}),
+            ...(partition.selectionControlIds.length > 0
+                ? {
+                    selectionControls: projectControlsSchema(partition.selectionSchema),
+                }
+                : {}),
+        });
+    }));
+}
+function projectControlsSchema(schema) {
+    const required = new Set(schema.required);
+    const properties = Object.fromEntries(Object.entries(schema.properties).map(([controlId, control]) => [
+        controlId,
+        required.has(controlId)
+            ? projectControlSchema(control)
+            : { anyOf: [projectControlSchema(control), { type: "null" }] },
+    ]));
+    return {
+        type: "object",
+        properties,
+        required: Object.keys(properties),
+        additionalProperties: false,
+    };
+}
+function projectControlSchema(control) {
+    if (control.type === "array")
+        return {
+            type: "array",
+            items: projectControlSchema(control.items),
+            minItems: control.minItems,
+            maxItems: control.maxItems,
+        };
+    if (control.type === "string" && "enum" in control)
+        return { type: "string", enum: [...control.enum] };
+    return { ...control };
+}

package/dist/src/runtime/steps/execution-agent/compaction.d.ts

@@ -1,15 +1,18 @@
+import type { RequestSteeringSnapshot } from "../../request/request-steering.js";
 import type { ModelStep } from "../../../shared/model-steps.js";
 import type { RoleCallFrame } from "../../orchestration/role-calls/index.js";
 import type { RequestExecutionScope } from "../../request/execution-scope.js";
 type ExecutionAgentCompactionOptions = Readonly<{
     call: RoleCallFrame;
+    steeringSnapshot: RequestSteeringSnapshot;
     sourceRevision: number;
+    consumer?: ModelStep;
     allowedConsumers: readonly ModelStep[];
     scopeSuffix?: string;
 }>;
 export declare function createExecutionAgentCompactionController(request: RequestExecutionScope, options: ExecutionAgentCompactionOptions): Readonly<{
-    compactionScope: "active_request" | "session_history";
     project(messages: readonly import("../../../model-gateway/types.js").ChatMessage[]): import("../../../model-gateway/types.js").ChatMessage[];
-    prepare(messages: readonly import("../../../model-gateway/types.js").ChatMessage[]): Promise<import("../../model/model-step-port.js").ModelStepContextCompactionPreparation>;
+    hasExhaustedVerifiedCompactionSources?(messages: readonly import("../../../model-gateway/types.js").ChatMessage[]): boolean;
+    getStages(): readonly import("../../model/context-compaction-contracts.js").ModelStepCompactionStage[];
 }>;
 export {};

package/dist/src/runtime/steps/execution-agent/compaction.js

@@ -1,12 +1,18 @@
+import { executionCompactionScopeId, projectExecutionCompactionObjective, } from "../../context/execution-compaction-objective.js";
 import { createModelStepCompactionController } from "../../context/model-step-compaction.js";
 export function createExecutionAgentCompactionController(request, options) {
-    const call = options.call.objective
-        ? options.call
-        : Object.freeze({ ...options.call, objective: request.prompt });
+    const objective = projectExecutionCompactionObjective(request.prompt, options.steeringSnapshot.updates);
+    const call = Object.freeze({ ...options.call, objective });
     return createModelStepCompactionController(request, {
         call,
         sourceRevision: options.sourceRevision,
         allowedConsumers: options.allowedConsumers,
-        ...(options.scopeSuffix ? { scopeSuffix: options.scopeSuffix } : {}),
+        consumer: options.consumer,
+        scopeId: executionCompactionScopeId({
+            callId: call.callId,
+            prompt: request.prompt,
+            objective,
+            ...(options.scopeSuffix ? { scopeSuffix: options.scopeSuffix } : {}),
+        }),
     });
 }

package/dist/src/runtime/steps/execution-agent/contracts.d.ts

@@ -38,8 +38,12 @@ export type ExecutionAgentCapabilityInvocation = Readonly<{
     capabilityId: string;
     /** Client-facing presentation metadata; never execution input. */
     intent: string;
-    /** Request-local execution input consumed only while refining controls. */
+    /** Request-local bounded operation consumed by controls and payload authoring. */
     operationObjective?: string;
+    /** Transient selection of canonical evidence for remaining-controls authoring. */
+    controlsEvidenceExecutionIds?: readonly string[];
+    /** Runtime-only mapping of the accepted operation for a payload capability. */
+    authoringObjective?: string;
     selectionControls?: CapabilityControls;
     /** Present only when selection mechanically satisfies the full schema. */
     controls?: CapabilityControls;
@@ -73,7 +77,14 @@ export type ExecutionAgentReconsiderCapabilitySelectionDecision = Readonly<{
     acknowledgement?: undefined;
     title?: undefined;
 }>;
-export type ExecutionAgentResolvedDecision = ExecutionAgentDecision | ExecutionAgentReconsiderCapabilitySelectionDecision;
+export type ExecutionAgentResolvedCapabilityInvocation = Readonly<Omit<ExecutionAgentCapabilityInvocation, "controls" | "operationObjective" | "controlsEvidenceExecutionIds"> & {
+    controls: CapabilityControls;
+}>;
+export type ExecutionAgentResolvedDecision = Exclude<ExecutionAgentDecision, {
+    action: "invoke_capability" | "invoke_capabilities";
+}> | (Omit<ExecutionAgentInvokeCapabilityDecision, keyof ExecutionAgentCapabilityInvocation> & ExecutionAgentResolvedCapabilityInvocation & Pick<ExecutionAgentDecision, "workPlan">) | (Omit<ExecutionAgentInvokeCapabilitiesDecision, "invocations"> & {
+    invocations: readonly ExecutionAgentResolvedCapabilityInvocation[];
+} & Pick<ExecutionAgentDecision, "workPlan">) | ExecutionAgentReconsiderCapabilitySelectionDecision;
 export type ExecutionAgentDecisionOutcome = Readonly<{
     decision: ExecutionAgentResolvedDecision;
     steeringVersion: number;
@@ -95,6 +106,7 @@ export type ExecutionAgentDecisionParseResult = Readonly<{
 export type ExecutionAgentDecisionContractOptions = Readonly<{
     workPlan?: ExecutionWorkPlanOptions;
     capabilities?: readonly CapabilityDescriptor[];
+    eligibleControlsEvidenceExecutionIds?: readonly string[];
     capabilityCatalogGroupIds?: readonly string[];
     activeCapabilityCatalogGroupIds?: readonly string[] | null;
     maxBatchCapabilityExecutions?: number;

package/dist/src/runtime/steps/execution-agent/controls-compacted-evidence.d.ts

@@ -0,0 +1,16 @@
+import type { ChatMessage } from "../../../model-gateway/types.js";
+import { type RequestToolResultsView } from "../../context/request-tool-results.js";
+import type { RequestContextCompactionStore } from "../../context/semantic-compaction/store.js";
+import type { RequestSteeringSnapshot } from "../../request/request-steering.js";
+export type ControlsCompactionContext = Readonly<{
+    prompt: string;
+    store?: RequestContextCompactionStore;
+}>;
+/** Transfer selected verified source digests, never the EA continuation. */
+export declare function buildExecutionControlsEvidenceMessage(view: RequestToolResultsView, params: Readonly<{
+    requestId: string;
+    callId: string;
+    steering: RequestSteeringSnapshot;
+    compaction?: ControlsCompactionContext;
+    onVerifiedCompaction?: (message: ChatMessage) => void;
+}>): ChatMessage;

package/dist/src/runtime/steps/execution-agent/controls-compacted-evidence.js

@@ -0,0 +1,67 @@
+import { projectExecutionCompactionObjective } from "../../context/execution-compaction-objective.js";
+import { resolveExecutionCompactedSources } from "../../context/execution-compacted-evidence.js";
+import { buildRequestToolResultsMessage, } from "../../context/request-tool-results.js";
+import { bindRequestToolResultsMessage } from "../../context/request-tool-results-message-binding.js";
+import { projectCompactedCapabilityResultReceipt } from "../../context/compacted-capability-result-receipt.js";
+import { projectSingleCopyCapabilityResult } from "../../context/capability-result-compaction-source.js";
+import { traceDebug } from "../../observability/debug-logger.js";
+/** Transfer selected verified source digests, never the EA continuation. */
+export function buildExecutionControlsEvidenceMessage(view, params) {
+    if (!params.compaction)
+        return buildRequestToolResultsMessage(view);
+    const compacted = resolveExecutionCompactedSources({
+        requestId: params.requestId,
+        prompt: params.compaction.prompt,
+        objective: projectExecutionCompactionObjective(params.compaction.prompt, params.steering.updates),
+        callId: params.callId,
+        store: params.compaction.store,
+        results: view.results.map((result) => ({
+            ...result,
+            adapterResult: result.adapterResult,
+        })),
+    });
+    if (!compacted)
+        return buildRequestToolResultsMessage(view);
+    const digests = new Map(compacted.sources.map((source) => [source.executionId, source]));
+    const results = view.results.map((result) => {
+        const digest = digests.get(result.executionId);
+        if (!digest)
+            return projectSingleCopyCapabilityResult(result);
+        return Object.freeze({
+            ...projectCompactedCapabilityResultReceipt(result),
+            compactedSourceRef: digest.sourceRef,
+        });
+    });
+    traceDebug("runtime.context.compaction", "controls.evidence_reused", {
+        requestId: params.requestId,
+        callId: params.callId,
+        modelStep: "capability.controls",
+        scopeId: compacted.scopeId,
+        sourceRevision: compacted.sourceRevision,
+        executionIds: compacted.sources.map(({ executionId }) => executionId),
+        reusedCompactedSourceCount: compacted.sources.length,
+        uncompactedResultCount: results.length - compacted.sources.length,
+    });
+    const message = bindRequestToolResultsMessage(view, JSON.stringify({
+        kind: "runtime_request_tool_results_v1",
+        authority: "reference_data",
+        sourceRevision: view.sourceRevision,
+        ...(view.scope ? { coverage: view.scope } : {}),
+        results,
+        compactedSourceEvidence: {
+            kind: "runtime_controls_compacted_source_evidence_v1",
+            authority: "passive_reference_only",
+            provenance: "same_call_verified_compaction_sources",
+            purpose: "evidence_for_the_frozen_controls_assignment",
+            presenceEffect: "does_not_change_assignment_permissions_or_completion",
+            omissionMeaning: "summarized_detail_not_proven_absent",
+            requestId: params.requestId,
+            callId: params.callId,
+            sourceScopeId: compacted.scopeId,
+            sourceRevision: compacted.sourceRevision,
+            sources: compacted.sources,
+        },
+    }));
+    params.onVerifiedCompaction?.(message);
+    return message;
+}

package/dist/src/runtime/steps/execution-agent/controls-evidence-contract.d.ts

@@ -0,0 +1,21 @@
+import type { CapabilityControlsPartition } from "../../orchestration/capability-adapters/index.js";
+import type { RoleCallFrame, RoleCallLedgerHead } from "../../orchestration/role-calls/index.js";
+import type { ExecutionAgentDecisionValidationIssue } from "./contracts.js";
+/** The actual EA partition owns this requirement; payload authority alone does not. */
+export declare function requiresControlsEvidenceSelection(partition: Pick<CapabilityControlsPartition, "remainingSchema">): boolean;
+export declare function projectEligibleControlsEvidenceExecutionIds(head: RoleCallLedgerHead, call: RoleCallFrame): readonly string[];
+export declare function freezeControlsEvidenceEligibility(value?: readonly string[]): readonly string[];
+export declare function controlsEvidenceSelectionSchema(eligible: readonly string[]): Record<string, unknown>;
+export declare function parseControlsEvidenceSelection(params: Readonly<{
+    value: unknown;
+    required: boolean;
+    eligible: readonly string[];
+    path: string;
+    issues: ExecutionAgentDecisionValidationIssue[];
+}>): Readonly<{
+    ok: true;
+    value?: readonly string[];
+}> | Readonly<{
+    ok: false;
+}>;
+export declare function controlsEvidenceSelectionRejection(value: unknown, eligible: readonly string[]): string | undefined;

package/dist/src/runtime/steps/execution-agent/controls-evidence-contract.js

@@ -0,0 +1,64 @@
+/** The actual EA partition owns this requirement; payload authority alone does not. */
+export function requiresControlsEvidenceSelection(partition) {
+    return Object.keys(partition.remainingSchema.properties).length > 0;
+}
+export function projectEligibleControlsEvidenceExecutionIds(head, call) {
+    return freezeControlsEvidenceEligibility(head.state.capabilityExecutions
+        .filter((execution) => execution.callId === call.callId && execution.status === "settled")
+        .map((execution) => execution.executionId));
+}
+export function freezeControlsEvidenceEligibility(value = []) {
+    if (!isControlsEvidenceIdList(value))
+        throw new Error("execution_agent_controls_evidence_eligibility_invalid");
+    if (new Set(value).size !== value.length)
+        throw new Error("execution_agent_controls_evidence_eligibility_invalid");
+    return Object.freeze([...value]);
+}
+export function controlsEvidenceSelectionSchema(eligible) {
+    const maximumIdLength = eligible.reduce((maximum, id) => Math.max(maximum, id.length), 0);
+    return {
+        type: "array",
+        minItems: 0,
+        maxItems: eligible.length,
+        items: {
+            type: "string",
+            minLength: 1,
+            ...(maximumIdLength > 0 ? { maxLength: maximumIdLength } : {}),
+        },
+        description: "Select eligible settled execution IDs needed to construct the complete operation, including source format, field meanings, representative data, prior outcomes or exact targets. Controls receives only selected evidence, as verified summaries where available or original results otherwise. Use [] only when the frozen operation and fixed sources supply the needed information; knowing a path alone does not establish its contents or format.",
+    };
+}
+export function parseControlsEvidenceSelection(params) {
+    if (!params.required)
+        return Object.freeze({ ok: true });
+    const rejection = controlsEvidenceSelectionRejection(params.value, params.eligible);
+    if (rejection) {
+        params.issues.push({
+            code: "execution_agent_controls_evidence_invalid",
+            path: params.path,
+            message: rejection,
+        });
+        return Object.freeze({ ok: false });
+    }
+    return Object.freeze({
+        ok: true,
+        value: Object.freeze([...params.value]),
+    });
+}
+export function controlsEvidenceSelectionRejection(value, eligible) {
+    if (!isControlsEvidenceIdList(value))
+        return "controlsEvidenceExecutionIds must be an explicit array of nonempty canonical execution IDs.";
+    if (value.length > eligible.length)
+        return "Evidence selection exceeds the eligible settled execution count.";
+    if (new Set(value).size !== value.length)
+        return "Evidence selection must not repeat an execution ID.";
+    const eligibleIds = new Set(eligible);
+    if (value.some((id) => !eligibleIds.has(id)))
+        return "Every selected execution ID must be eligible in this exact request, call and decision head.";
+    return undefined;
+}
+function isControlsEvidenceIdList(value) {
+    if (!Array.isArray(value))
+        return false;
+    return value.every((id) => typeof id === "string" && id.length > 0);
+}

package/dist/src/runtime/steps/execution-agent/controls-evidence.d.ts

@@ -0,0 +1,32 @@
+import type { ChatMessage } from "../../../model-gateway/types.js";
+import type { RequestToolResultsView } from "../../context/request-tool-results.js";
+import { type ControlsCompactionContext } from "./controls-compacted-evidence.js";
+import type { CapabilityControls, CapabilityControlsSchema } from "../../orchestration/capability-adapters/index.js";
+import type { RoleCallFrame, RoleCallLedgerHead } from "../../orchestration/role-calls/index.js";
+import type { RequestSteeringSnapshot } from "../../request/request-steering.js";
+export type ControlsEvidenceAssignmentSlot = Readonly<{
+    slot: string;
+    capabilityId: string;
+    operationObjective?: string;
+    selectionControls: CapabilityControls;
+    remainingControls: CapabilityControlsSchema;
+    controlsEvidenceExecutionIds?: readonly string[];
+    guidance: string;
+}>;
+/** Materializes only explicit choices; relevance remains the decision model's responsibility. */
+export declare function projectSelectedControlsEvidence(params: Readonly<{
+    requestId: string;
+    head: RoleCallLedgerHead;
+    call: RoleCallFrame;
+    workingDirectory?: string;
+    steering: RequestSteeringSnapshot;
+    compaction?: ControlsCompactionContext;
+    slots: readonly ControlsEvidenceAssignmentSlot[];
+}>): Readonly<{
+    slots: readonly ControlsEvidenceAssignmentSlot[];
+    messages: readonly ChatMessage[];
+    view: RequestToolResultsView;
+    scopeId: string;
+    preservationObjective: string;
+    hasVerifiedCompactedEvidence(messages: readonly ChatMessage[]): boolean;
+}>;