deepline 0.3.73 → 0.3.75

package/dist/bundling-sources/shared_libs/play-runtime/context.ts

@@ -100,7 +100,6 @@ import {
 import { CTX_FETCH_EGRESS_TOOL_ID } from './builtin-pacing';
 import {
   legacyRawFromToolResponseRawV2,
-  normalizeToolResponseContract,
   providerMetaFromToolResponseRawV2,
   RAW_V2_TOOL_RESPONSE_CONTRACT,
   type ToolResponseContract,
@@ -115,7 +114,6 @@ import {
   isProviderUnavailable,
   serializeToolExecutionFailure,
   ToolExecutionError,
-  TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
   TOOL_EXECUTION_ERROR_SCHEMA_HEADER,
   type ToolExecutionErrorSchemaVersion,
   type ToolExecutionFailureV1,
@@ -177,7 +175,7 @@ import {
   buildDurableToolCallCacheKey,
   buildLegacyRevisionedDurableToolCallCacheKey,
   buildDurableToolPayloadProviderIdempotencyKey,
-  buildDurableToolProviderIdempotencyKey,
+  buildProviderOperationIdempotencyKey,
   buildDurableToolReceiptPrefix,
   resolveDurableCallCachePolicy,
 } from './durable-call-cache';
@@ -195,6 +193,10 @@ import {
   type PlayAuthoringRunScope,
   type PlayAuthoringRuntimeContext,
 } from '../plays/authoring-contract';
+import {
+  resolvePlayArtifactRuntimeContract,
+  type PlayArtifactRuntimeContract,
+} from './play-artifact-runtime-contract';
 import {
   LOG_LEVELS,
   formatCtxFetchHttpFailureDiagnostic,
@@ -217,11 +219,7 @@ import {
   type DurableReceiptExecutionStore,
 } from './durable-receipt-execution';
 import {
-  asyncOperationDurableStartInput,
   asyncOperationShouldWait,
-  classifyAsyncOperationResult,
-  executeAsyncOperationLifecycle,
-  resolveAsyncOperationPolling,
   type AsyncOperationContractWire,
 } from './async-operation';
 import {
@@ -407,14 +405,8 @@ type InlineCompositionStore = {
   governor: PlayExecutionGovernor;
   playName: string;
   staticPipeline: ContextOptions['staticPipeline'];
-  /** Immutable error contract pinned by the child play artifact. */
-  toolErrorSchemaVersion: ToolExecutionErrorSchemaVersion;
-  /** Immutable authoring semantics pinned by the child play artifact. */
-  authoringContractEdition: PlayAuthoringContractEdition;
-  /** Execute response contract pinned by the child artifact. */
-  toolResponseContract: ToolResponseContract;
-  /** Explicit response-transform revision used for durable receipt identity. */
-  toolResponseReceiptRevision?: string;
+  /** Immutable compatibility projection of the child Play artifact. */
+  runtimeContract: PlayArtifactRuntimeContract;
 };
 const inlineCompositionContext =
   new AsyncLocalStorage<InlineCompositionStore>();
@@ -1089,7 +1081,10 @@ export function resolveToolRuntimeTimeoutMs(
   authoringContractEdition: PlayAuthoringContractEdition = PLAY_AUTHORING_CONTRACT_EDITION,
 ): number | undefined {
   if (requestedTimeoutMs !== undefined) {
-    if (authoringContractEdition >= 2) {
+    if (
+      resolvePlayArtifactRuntimeContract({ authoringContractEdition }).semantics
+        .validation === 'strict'
+    ) {
       validatePlayAuthoringField(
         'ctx.tools.execute.timeoutMs',
         requestedTimeoutMs,
@@ -1249,27 +1244,6 @@ function publicToolResponseEnvelope(value: unknown): {
   };
 }
 
-function materializedAsyncToolResponse(
-  response: ParsedToolExecuteResponse['toolResponse'] | undefined,
-  result: unknown,
-): ParsedToolExecuteResponse['toolResponse'] {
-  const hasRawV2 =
-    response !== undefined &&
-    Object.prototype.hasOwnProperty.call(response, 'rawV2');
-  const materializedRawV2 =
-    response?.view === 'data'
-      ? {
-          ...(recordOrNull(response.rawV2) ?? {}),
-          data: result,
-        }
-      : result;
-  return {
-    ...(response ?? {}),
-    raw: result,
-    ...(hasRawV2 ? { rawV2: materializedRawV2 } : {}),
-  };
-}
-
 /**
  * A batched provider request returns one envelope for several logical source
  * tool calls. Each source call persists only its own item-shaped canonical
@@ -1399,13 +1373,11 @@ type ToolExecutionApiOptions = {
   /** The receipt key is a completed-result cache for this read-only call. */
   completedResultCache?: boolean;
   executionAuthScopeDigest?: string | null;
-  /**
-   * Historical receipt identity used for the API's provider/billing
-   * idempotency receipt. This can differ from the worker-owned durable cache
-   * receipt while a response contract migrates.
-   */
-  providerIdempotencyReceiptKey?: string | null;
   providerIdempotencyKey?: string | null;
+  /** Exact forced-member identities that participate in a native batch key. */
+  providerOperationForceRefreshIdentities?: readonly string[];
+  /** Presentation-only cache identity paired with a separate execution fence. */
+  providerIdempotencyReceiptKey?: string | null;
   receiptLeaseExpiresAt?: string | null;
   beforeProviderCall?: () => Promise<void> | void;
   heartbeatReceipt?: () => Promise<void> | void;
@@ -1430,6 +1402,13 @@ type ToolExecutionApiOptions = {
   };
   /** Internal recursion guard for lifecycle poll/finish calls. */
   skipAsyncOperationResolution?: boolean;
+  /**
+   * A status/result request belonging to a live async lifecycle. It must not
+   * create a result receipt or provider idempotency identity from a parent
+   * cache entry: the job handle is process-local, while the outer tool-call
+   * cache stores only its terminal materialized output.
+   */
+  uncachedAsyncLifecycleCall?: boolean;
 };
 const IN_MEMORY_STEP_RESULT_PREVIEW_LIMIT = 25;
 /**
@@ -2110,11 +2089,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     string,
     { resolve: (value: unknown) => void; reject: (reason: unknown) => void }
   >();
-  private readonly asyncOperationCapacity = new Map<
-    string,
-    { active: number; waiters: Array<() => void> }
-  >();
   #options: ContextOptions;
+  private readonly rootRuntimeContract: PlayArtifactRuntimeContract;
   private readonly executionScope: RunExecutionScope;
   private logBuffer: string[] = [];
   private readonly logRateLimitState = new Map<
@@ -2160,6 +2136,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     boundaryId: string;
     eventKey: string;
     timeoutMs: number;
+    messageRef?: { channel: string; ts: string };
   }> = [];
   private processedRowCount = 0;
   private sleepBoundaryIndex = 0;
@@ -2253,7 +2230,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       assertNoSecretTaint(request.input, 'ctx.tools.execute input');
       if (
         request.timeoutMs !== undefined &&
-        this.currentAuthoringContractEdition >= 2
+        this.currentRuntimeSemantics.validation === 'strict'
       ) {
         validatePlayAuthoringField(
           'ctx.tools.execute.timeoutMs',
@@ -2262,7 +2239,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       }
       if (
         request.receiptWaitMs !== undefined &&
-        this.currentAuthoringContractEdition >= 2
+        this.currentRuntimeSemantics.validation === 'strict'
       ) {
         validatePlayAuthoringField(
           'ctx.tools.execute.receiptWaitMs',
@@ -2406,7 +2383,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       }
       const handle = createSecretHandle(name.trim());
       const value =
-        this.currentAuthoringContractEdition >= 4
+        this.currentRuntimeSemantics.secrets.value === 'plaintext_promise'
           ? createPlaintextSecretPromise(handle.name, () =>
               this.resolveSecretHandle(handle),
             )
@@ -2430,6 +2407,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   };
 
   constructor(options: ContextOptions) {
+    this.rootRuntimeContract =
+      options.artifactRuntimeContract ??
+      resolvePlayArtifactRuntimeContract({
+        authoringContractEdition: options.authoringContractEdition,
+        toolResponseContract: options.toolResponseContract,
+        toolResponseReceiptRevision: options.toolResponseReceiptRevision,
+      });
     const fixtureBehavior = validateFixtureBehavior(options.fixtureBehavior);
     if (fixtureBehavior.ok === false) {
       throw new Error(fixtureBehavior.error);
@@ -2749,20 +2733,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
   /**
    * Inline children share this context's queues, but not its artifact contract.
-   * Each child tool call must preserve the error shape pinned when that child
-   * was published, even when the parent was published under another schema.
+   * Each child uses its own admitted semantics and response projection even
+   * when the parent was published under another artifact contract.
    */
   private get currentToolErrorSchemaVersion(): ToolExecutionErrorSchemaVersion {
-    // Historical artifacts must not turn durable structured failures back into
-    // strings. Every runtime tool call and receipt rehydration uses v1.
-    return TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
+    return this.currentRuntimeContract.toolErrorSchemaVersion;
   }
 
   private get currentToolResponseContract(): ToolResponseContract {
-    return normalizeToolResponseContract(
-      this.activeInlineComposition?.toolResponseContract ??
-        this.#options.toolResponseContract,
-    );
+    return this.currentRuntimeContract.toolResponseContract;
   }
 
   /**
@@ -2775,6 +2754,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   private get hasPinnedToolResponseContract(): boolean {
     return (
       this.activeInlineComposition !== null ||
+      this.#options.artifactRuntimeContract !== undefined ||
       this.#options.toolResponseContract !== undefined
     );
   }
@@ -2784,20 +2764,23 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
    * changes the completed-result cache identity.
    */
   private get currentToolResponseReceiptRevision(): string | undefined {
-    if (this.activeInlineComposition) {
-      return this.activeInlineComposition.toolResponseReceiptRevision;
-    }
-    return this.#options.toolResponseReceiptRevision;
+    return this.currentRuntimeContract.toolResponseReceiptRevision;
   }
 
   private get currentAuthoringContractEdition(): PlayAuthoringContractEdition {
+    return this.currentRuntimeContract.semantics.authoringContractEdition;
+  }
+
+  private get currentRuntimeContract(): PlayArtifactRuntimeContract {
     return (
-      this.activeInlineComposition?.authoringContractEdition ??
-      this.#options.authoringContractEdition ??
-      PLAY_AUTHORING_CONTRACT_EDITION
+      this.activeInlineComposition?.runtimeContract ?? this.rootRuntimeContract
     );
   }
 
+  private get currentRuntimeSemantics() {
+    return this.currentRuntimeContract.semantics;
+  }
+
   private recordPlayCallStep(input: {
     playId: string;
     execution?: 'inline';
@@ -9326,7 +9309,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     }
     if (
       options?.timeoutMs !== undefined &&
-      this.currentAuthoringContractEdition >= 2
+      this.currentRuntimeSemantics.validation === 'strict'
     ) {
       validatePlayAuthoringField(
         'ctx.tools.execute.timeoutMs',
@@ -9335,7 +9318,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     }
     if (
       options?.receiptWaitMs !== undefined &&
-      this.currentAuthoringContractEdition >= 2
+      this.currentRuntimeSemantics.validation === 'strict'
     ) {
       validatePlayAuthoringField(
         'ctx.tools.execute.receiptWaitMs',
@@ -9382,9 +9365,18 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       executionAuthScopeDigest,
       staleAfterSeconds: toolCachePolicy.staleAfterSeconds,
     });
-    // Only explicitly fenced operations use this key as a provider identity.
-    // Ordinary calls use it solely as their completed-result cache key.
-    let providerIdempotencyKeyBase = durableCacheKey;
+    const providerActionVersion =
+      (await this.#options.getToolActionCacheVersion?.(toolId))?.trim() ?? '';
+    // A provider operation is keyed by its requested semantic payload. The
+    // durable receipt below remains a completed-result cache only.
+    let providerIdempotencyKeyBase =
+      buildDurableToolPayloadProviderIdempotencyKey({
+        orgId: this.#options.orgId,
+        toolId,
+        executionAuthScopeDigest,
+        providerActionVersion,
+        payload: input,
+      });
     let directResultReceiptKey = durableCacheKey;
     // A raw-v2 artifact must never read an older receipt that cannot render
     // raw-v2. If both the primary and its revisioned recovery receipt are
@@ -9664,17 +9656,16 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   ...(toolRetryPolicy?.requiresExecutionFence === true
                     ? {
                         providerIdempotencyReceiptKey:
-                          cacheableToolResult && operationKey
-                            ? operationKey
+                          cacheableToolResult && resultReceiptKey
+                            ? resultReceiptKey
                             : physicalDirectKey,
                         providerIdempotencyKey:
                           this.providerIdempotencyKeyForToolCall({
-                            cacheKey:
+                            operationKey:
                               useDirectResultReceipts && operationKey
                                 ? providerIdempotencyKeyBase
                                 : physicalDirectKey,
                             force: cacheableToolResult && toolCachePolicy.force,
-                            leaseId: directReceiptLeaseId,
                             logicalCallId,
                           }),
                       }
@@ -9756,9 +9747,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 dispatcher,
               })
             : null;
-          const providerActionVersion =
-            (await this.#options.getToolActionCacheVersion?.(toolId))?.trim() ??
-            '';
           const call: Omit<ToolCallInput, 'compatibility'> = {
             scope: {
               organizationId: this.#options.orgId ?? 'unknown-org',
@@ -9987,7 +9975,14 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           executionAuthScopeDigest,
           staleAfterSeconds: toolCachePolicy.staleAfterSeconds,
         });
-        providerIdempotencyKeyBase = durableCacheKey;
+        providerIdempotencyKeyBase =
+          buildDurableToolPayloadProviderIdempotencyKey({
+            orgId: this.#options.orgId,
+            toolId,
+            executionAuthScopeDigest,
+            providerActionVersion,
+            payload: input,
+          });
         directResultReceiptKey = durableCacheKey;
         bypassDirectResultCache = false;
         checkpointCacheKeys.splice(
@@ -10042,6 +10037,21 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     const existing =
       this.checkpoint.resolvedBoundaries?.[preparedBoundary.boundaryId];
     if (existing?.kind === 'integration_event' && 'output' in existing) {
+      const output = recordOrNull(existing.output);
+      if (output?.timed_out === true) {
+        await handler.onTimeout?.({
+          payload: input,
+          context: eventContext,
+          boundary: {
+            boundaryId: preparedBoundary.boundaryId,
+            eventKey: preparedBoundary.eventKey,
+            timeoutMs: preparedBoundary.timeoutMs,
+            provider: existing.provider ?? handler.provider,
+            toolId: existing.toolId ?? handler.toolId,
+            ...(existing.messageRef ? { messageRef: existing.messageRef } : {}),
+          },
+        });
+      }
       this.runtimeLog(
         `Integration event ${preparedBoundary.boundaryId}: recovered response from checkpoint`,
       );
@@ -10097,6 +10107,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         boundaryId: boundary.boundaryId,
         eventKey: boundary.eventKey,
         timeoutMs: boundary.timeoutMs,
+        ...(boundary.messageRef ? { messageRef: boundary.messageRef } : {}),
       });
     }
 
@@ -10105,6 +10116,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       boundaryId: boundary.boundaryId,
       eventKey: boundary.eventKey,
       timeoutMs: boundary.timeoutMs,
+      ...(boundary.messageRef ? { messageRef: boundary.messageRef } : {}),
     });
   }
 
@@ -10164,8 +10176,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     const childCompatibility = normalizePlayContractCompatibility(
       childCompatibilitySnapshot,
     );
-    const childToolErrorSchemaVersion =
-      childCompatibility.toolErrorSchemaVersion;
     const childToolResponseContract = childCompatibility.toolResponseContract;
     const childToolResponseReceiptRevision =
       childCompatibility.toolResponseReceiptRevision;
@@ -10240,11 +10250,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             governor: inlineChildGovernor,
             playName: resolvedName,
             staticPipeline: resolvedPlay.staticPipeline ?? null,
-            toolErrorSchemaVersion: childToolErrorSchemaVersion,
-            toolResponseContract: childToolResponseContract,
-            toolResponseReceiptRevision: childToolResponseReceiptRevision,
-            authoringContractEdition:
-              childCompatibility.authoringContractEdition,
+            runtimeContract: resolvePlayArtifactRuntimeContract({
+              authoringContractEdition:
+                childCompatibility.authoringContractEdition,
+              toolResponseContract: childToolResponseContract,
+              toolResponseReceiptRevision: childToolResponseReceiptRevision,
+            }),
           },
           () => this.executeResolvedPlay(resolvedPlay, this, input),
         );
@@ -10553,7 +10564,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   async sleep(ms: number): Promise<void> {
     this.assertInlineChildContract('suspending_child');
     const delayMs =
-      this.currentAuthoringContractEdition >= 2
+      this.currentRuntimeSemantics.validation === 'strict'
         ? (validatePlayAuthoringField('ctx.sleep.ms', ms), ms)
         : Math.max(0, Math.round(ms));
     if (this.#options.durableBoundaries) {
@@ -10679,14 +10690,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               ...secretHeaderMarkers,
             },
             row: rowFetchScope,
-            // Edition 5 changes non-2xx responses from cached values to
-            // non-cacheable errors. Partition those receipts from editions
-            // 1–4 so a republished artifact makes a fresh request instead of
-            // inheriting a legacy error record.
-            ...(this.currentAuthoringContractEdition >= 5
+            // A pinned fetch policy that turns non-2xx responses into typed,
+            // non-cacheable errors needs its own receipt epoch. Preserve the
+            // historical epoch selected by the artifact rather than deriving a
+            // new cache key from every future authoring edition.
+            ...(this.currentRuntimeSemantics.fetch.receiptIdentityEdition !==
+            null
               ? {
                   authoringContractEdition:
-                    this.currentAuthoringContractEdition,
+                    this.currentRuntimeSemantics.fetch.receiptIdentityEdition,
                 }
               : {}),
           }),
@@ -10702,7 +10714,11 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               httpStatus: output.status,
             });
           }
-          if (!output.ok && this.currentAuthoringContractEdition >= 5) {
+          if (
+            !output.ok &&
+            this.currentRuntimeSemantics.fetch.httpFailure ===
+              'throw_typed_error'
+          ) {
             throw new CtxFetchHttpError(output);
           }
           return output;
@@ -10710,7 +10726,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         shouldPersistFailure: (error) =>
           !(
             error instanceof CtxFetchHttpError &&
-            this.currentAuthoringContractEdition >= 5
+            !this.currentRuntimeSemantics.fetch.persistHttpFailure
           ),
         execute: async ({ retainExternalCallSlot }) => {
           const secretHeaders = await this.resolveSecretAuth(secretAuth);
@@ -10914,11 +10930,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               });
             }
 
-            // Edition 5 adopts normal fetch semantics: a non-2xx response is
-            // a failed durable operation. Throw before checkpoint/receipt
-            // completion so the failure is never cached. Editions 1–4 retain
-            // their response-record behavior for the same upstream response.
-            if (!output.ok && this.currentAuthoringContractEdition >= 5) {
+            // The artifact-pinned fetch policy decides whether a non-2xx
+            // response is a returned record or a failed durable operation.
+            // Throw before checkpoint/receipt completion so the throwing
+            // policy never caches its failure.
+            if (
+              !output.ok &&
+              this.currentRuntimeSemantics.fetch.httpFailure ===
+                'throw_typed_error'
+            ) {
               throw new CtxFetchHttpError(output);
             }
 
@@ -11310,15 +11330,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           async () =>
             await recordsFor(
               resultReceiptKeys,
-              await this.getRuntimeStepReceipts(
-                [...new Set(
+              await this.getRuntimeStepReceipts([
+                ...new Set(
                   resultReceiptKeys.flatMap((receiptKey) => [
                     receiptKey,
                     ...(input.requestForReceipt.get(receiptKey)
                       ?.legacyReceiptKeys ?? []),
                   ]),
-                )],
-              ),
+                ),
+              ]),
             ),
         ),
       complete: async ({ receipts }) => {
@@ -12575,7 +12595,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                       dispatchPayload: owner.input,
                       resultReceiptKey: receiptKey,
                       providerOperationKey:
-                        owner.providerIdempotencyKeyBase ?? owner.cacheKey,
+                        this.providerOperationKeyForQueuedToolCall(owner),
                       apiOptions: {
                         beforeProviderCall: () =>
                           this.assertRuntimeToolReceiptOwnership([owner]),
@@ -12583,18 +12603,14 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                         playNodeScope: playNodeScopeForToolCallRequest(owner),
                         executionAuthScopeDigest:
                           owner.executionAuthScopeDigest,
-                        providerIdempotencyReceiptKey:
-                          owner.providerIdempotencyKeyBase ?? owner.cacheKey,
                         receiptLeaseExpiresAt: owner.receiptLeaseExpiresAt,
                         heartbeatReceipt: () =>
                           this.renewRuntimeToolReceiptOwnership([owner]),
                         providerIdempotencyKey:
                           this.providerIdempotencyKeyForToolCall({
-                            cacheKey:
-                              owner.providerIdempotencyKeyBase ??
-                              owner.cacheKey,
+                            operationKey:
+                              this.providerOperationKeyForQueuedToolCall(owner),
                             force: owner.force === true,
-                            leaseId: owner.receiptLeaseId,
                             logicalCallId: owner.logicalCallId,
                           }),
                         timeoutMs: resolveRuntimeTimeoutMsForClaimedOwners([
@@ -12928,7 +12944,17 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                         toolId: batch.batchOperation,
                       }),
                     });
-                  const aggregateProviderIdempotencyReceiptKey =
+                  const aggregateForceRefreshIdentities = batch.memberRequests
+                    .filter((request) => request.force === true)
+                    .map((request) =>
+                      this.providerIdempotencyKeyForToolCall({
+                        operationKey:
+                          this.providerOperationKeyForQueuedToolCall(request),
+                        force: true,
+                        logicalCallId: request.logicalCallId,
+                      }),
+                    );
+                  const aggregateProviderOperationKey =
                     buildDurableToolPayloadProviderIdempotencyKey({
                       orgId: this.#options.orgId,
                       toolId: batch.batchOperation,
@@ -12942,18 +12968,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                           )
                         )?.trim() ?? 'unversioned',
                       payload: batch.batchPayload,
-                      forceRefreshIdentities: batch.memberRequests
-                        .filter((request) => request.force === true)
-                        .map((request) =>
-                          this.providerIdempotencyKeyForToolCall({
-                            cacheKey:
-                              request.providerIdempotencyKeyBase ??
-                              request.cacheKey,
-                            force: true,
-                            leaseId: request.receiptLeaseId,
-                            logicalCallId: request.logicalCallId,
-                          }),
-                        ),
+                      forceRefreshIdentities: aggregateForceRefreshIdentities,
                     });
                   let releaseToolSlot: () => void = () => undefined;
                   try {
@@ -12963,8 +12978,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                         dispatchToolId: batch.batchOperation,
                         dispatchPayload: batch.batchPayload,
                         resultReceiptKey: aggregateReceiptKey,
-                        providerOperationKey:
-                          aggregateProviderIdempotencyReceiptKey,
+                        providerOperationKey: aggregateProviderOperationKey,
                         apiOptions: {
                           durableCallReceiptKey: aggregateReceiptKey,
                           // A native batch is one physical provider request for
@@ -12977,10 +12991,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                           executionAuthScopeDigest:
                             batch.memberRequests[0]?.executionAuthScopeDigest ??
                             null,
-                          providerIdempotencyReceiptKey:
-                            aggregateProviderIdempotencyReceiptKey,
-                          providerIdempotencyKey:
-                            aggregateProviderIdempotencyReceiptKey,
+                          providerIdempotencyKey: aggregateProviderOperationKey,
+                          providerOperationForceRefreshIdentities:
+                            aggregateForceRefreshIdentities,
                           receiptLeaseExpiresAt: batch.memberRequests.reduce<
                             string | null
                           >((earliest, request) => {
@@ -13183,15 +13196,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                         request,
                         dispatchToolId: toolId,
                         dispatchPayload: request.input,
-                        // Always-fresh map calls intentionally have no durable
-                        // receipt or provider idempotency header. Their cache
-                        // key is only a local ToolCall contract identity.
+                        // Always-fresh map calls intentionally have no
+                        // result cache. Their provider-operation identity is
+                        // a unique forced semantic request, never a cache key.
                         resultReceiptKey:
                           request.receiptKey ?? request.cacheKey,
                         providerOperationKey:
-                          request.providerIdempotencyKeyBase ??
-                          request.receiptKey ??
-                          request.cacheKey,
+                          this.providerOperationKeyForQueuedToolCall(request),
                         apiOptions: {
                           beforeProviderCall: () =>
                             pendingReceiptHeartbeat
@@ -13207,16 +13218,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                                 completedResultCache: true,
                                 executionAuthScopeDigest:
                                   request.executionAuthScopeDigest,
-                                providerIdempotencyReceiptKey:
-                                  request.providerIdempotencyKeyBase ??
-                                  request.receiptKey,
                                 providerIdempotencyKey:
                                   this.providerIdempotencyKeyForToolCall({
-                                    cacheKey:
-                                      request.providerIdempotencyKeyBase ??
-                                      request.receiptKey,
+                                    operationKey:
+                                      this.providerOperationKeyForQueuedToolCall(
+                                        request,
+                                      ),
                                     force: request.force === true,
-                                    leaseId: request.receiptLeaseId,
                                     logicalCallId: request.logicalCallId,
                                   }),
                                 receiptLeaseExpiresAt:
@@ -13226,7 +13234,17 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                                     request,
                                   ]),
                               }
-                            : {}),
+                            : {
+                                providerIdempotencyKey:
+                                  this.providerIdempotencyKeyForToolCall({
+                                    operationKey:
+                                      this.providerOperationKeyForQueuedToolCall(
+                                        request,
+                                      ),
+                                    force: true,
+                                    logicalCallId: request.logicalCallId,
+                                  }),
+                              }),
                           timeoutMs: resolveRuntimeTimeoutMsForClaimedOwners([
                             request,
                           ]),
@@ -13369,173 +13387,36 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   }
 
   private providerIdempotencyKeyForToolCall(input: {
-    cacheKey: string;
+    operationKey: string;
     force?: boolean;
-    leaseId?: string | null;
     logicalCallId?: string;
   }): string {
     let fallbackAttemptId: string | null = null;
-    if (input.force === true && !input.leaseId) {
+    if (input.force === true) {
       if (!input.logicalCallId) {
         throw new Error(
-          'Forced tool execution without a receipt lease requires a stable logical call identity.',
+          'Forced tool execution requires a stable logical call identity.',
         );
       }
       fallbackAttemptId = `${this.currentRunId}:${input.logicalCallId}`;
     }
-    return buildDurableToolProviderIdempotencyKey({
-      receiptKey: input.cacheKey,
+    return buildProviderOperationIdempotencyKey({
+      operationKey: input.operationKey,
       force: input.force,
-      receiptLeaseId: input.leaseId,
       fallbackAttemptId,
     });
   }
 
-  private async acquireAsyncOperationCapacity(input: {
-    toolId: string;
-    provider: string;
-    contract: AsyncOperationContractWire;
-    authScopeDigest: string | null;
-  }): Promise<() => void> {
-    const scopeSuffix =
-      input.contract.capacity.scope === 'organization_action'
-        ? input.toolId
-        : input.contract.capacity.scope === 'organization_connection'
-          ? (input.authScopeDigest ?? 'default-connection')
-          : input.provider;
-    const key = `${this.#options.orgId ?? 'unknown-org'}:${input.provider}:${input.contract.capacity.scope}:${scopeSuffix}`;
-    let limit = 1;
-    if (input.contract.capacity.limit.kind === 'fixed') {
-      limit = input.contract.capacity.limit.maxConcurrentJobs;
-    } else {
-      const hints =
-        (await this.#options.getToolQueueHints?.(input.toolId)) ?? [];
-      const declaredLimits = hints
-        .map((hint) => hint.maxConcurrency)
-        .filter(
-          (value): value is number =>
-            typeof value === 'number' && Number.isFinite(value) && value > 0,
-        );
-      limit = declaredLimits.length > 0 ? Math.min(...declaredLimits) : 1;
-    }
-    const state = this.asyncOperationCapacity.get(key) ?? {
-      active: 0,
-      waiters: [],
-    };
-    this.asyncOperationCapacity.set(key, state);
-    if (state.active >= limit) {
-      if (input.contract.capacity.onConflict === 'fail') {
-        throw new Error(
-          `Async provider capacity is full for ${input.provider}; the contract allows ${limit} active job(s).`,
-        );
-      }
-      await new Promise<void>((resolve) => state.waiters.push(resolve));
-    }
-    state.active += 1;
-    let released = false;
-    return () => {
-      if (released) return;
-      released = true;
-      state.active = Math.max(0, state.active - 1);
-      state.waiters.shift()?.();
-      if (state.active === 0 && state.waiters.length === 0) {
-        this.asyncOperationCapacity.delete(key);
-      }
-    };
-  }
-
-  private asyncOperationActionReceiptKey(input: {
-    action: string;
-    parentReceiptKey: string | null;
-    jobId: string;
-    phase: string;
-  }): string | null {
-    if (!input.parentReceiptKey) return null;
-    return `${buildDurableToolReceiptPrefix({
-      orgId: this.#options.orgId,
-      toolId: input.action,
-    })}${stableDigest(
-      stableStringify({
-        parentReceiptKey: input.parentReceiptKey,
-        jobId: input.jobId,
-        phase: input.phase,
-      }),
-    )}`;
-  }
-
-  private async resolveAsyncOperation(input: {
-    toolId: string;
-    startInput: Record<string, unknown>;
-    startResponse: ParsedToolExecuteResponse;
-    contract: AsyncOperationContractWire;
-    receiptKey: string | null;
-  }): Promise<ParsedToolExecuteResponse> {
-    const responseValue = (response: ParsedToolExecuteResponse): unknown => {
-      if (response.toolResponse && 'raw' in response.toolResponse) {
-        return response.toolResponse.raw;
-      }
-      const result = recordOrNull(response.result);
-      return result && Object.prototype.hasOwnProperty.call(result, 'data')
-        ? result.data
-        : response.result;
-    };
-    const startResult = responseValue(input.startResponse);
-    const lifecycle = await executeAsyncOperationLifecycle({
-      contract: input.contract,
-      startInput: input.startInput,
-      startResult,
-      jobId: input.startResponse.jobId,
-      sleep: async (delayMs) =>
-        await this.sleepWithCheckpointHeartbeat(delayMs),
-      responseValue,
-      executeAction: async (request) => {
-        const receiptKey = this.asyncOperationActionReceiptKey({
-          action: request.action,
-          parentReceiptKey: input.receiptKey,
-          jobId: request.jobId,
-          phase: `${request.phase}:${request.pollAttempt}:${request.page ?? ''}`,
-        });
-        return await this.callToolExecutionAPI(request.action, request.input, {
-          skipAsyncOperationResolution: true,
-          durableCallReceiptKey: receiptKey,
-          providerIdempotencyReceiptKey: receiptKey,
-          providerIdempotencyKey: receiptKey,
-        });
-      },
-    });
-    if (lifecycle.kind === 'timed_out') {
-      const polling = resolveAsyncOperationPolling({
-        contract: input.contract,
-        startInput: input.startInput,
-      });
-      throw new Error(
-        `Async operation ${input.toolId} (${lifecycle.jobId}) did not reach a terminal state within ${polling.timeoutMs}ms.`,
-      );
-    }
-    if (
-      lifecycle.classification.outcome === 'failed' ||
-      lifecycle.classification.outcome === 'cancelled'
-    ) {
+  private providerOperationKeyForQueuedToolCall(
+    request: ToolCallRequest,
+  ): string {
+    const operationKey = request.providerIdempotencyKeyBase?.trim();
+    if (!operationKey) {
       throw new Error(
-        lifecycle.classification.message ??
-          `Async operation ${input.toolId} (${lifecycle.jobId}) ended ${lifecycle.classification.outcome}.`,
+        `Queued tool call ${request.callId} is missing its semantic provider operation identity.`,
       );
     }
-    const materialized = lifecycle.materialized!;
-    const selectedResponse = lifecycle.finishResponse ?? lifecycle.pollResponse;
-    return {
-      ...selectedResponse,
-      status:
-        lifecycle.classification.outcome === 'no_result' ||
-        materialized.outcome === 'no_result'
-          ? 'no_result'
-          : 'completed',
-      result: { data: materialized.result },
-      toolResponse: materializedAsyncToolResponse(
-        selectedResponse.toolResponse,
-        materialized.result,
-      ),
-    };
+    return operationKey;
   }
 
   private async callToolExecutionAPI(
@@ -13551,7 +13432,29 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     const requestsDurableInvocationFence =
       this.#options.requestDurableInvocationFence === true ||
       this.#options.durableInvocationFence === true;
-    const executeSuffix = requestsDurableInvocationFence
+    const asyncContract = options?.skipAsyncOperationResolution
+      ? null
+      : ((await this.#options.getToolAsyncOperation?.(toolId)) ?? null);
+    const shouldWaitForAsyncOperation = Boolean(
+      asyncContract && asyncOperationShouldWait(asyncContract, input),
+    );
+    const executionAuthScopeDigest = options?.executionAuthScopeDigest
+      ? options.executionAuthScopeDigest.trim() || null
+      : ((await this.resolveToolAuthScopeDigest(toolId))?.trim() ?? null);
+    const provider =
+      (await this.#options.getToolProvider?.(toolId))?.trim() ||
+      toolId.split(/[._]/)[0]?.trim() ||
+      'provider';
+    // A receipt is a terminal-output cache, never an async provider-job
+    // record. Launch/poll/finish transport must therefore remain receiptless:
+    // if this process stops, a later cache miss starts a new provider request
+    // rather than attaching itself to this one.
+    const uncachedAsyncLifecycleCall =
+      options?.uncachedAsyncLifecycleCall === true ||
+      shouldWaitForAsyncOperation;
+    const usesDurableInvocationFence =
+      requestsDurableInvocationFence && !uncachedAsyncLifecycleCall;
+    const executeSuffix = usesDurableInvocationFence
       ? 'execute-fenced-v1'
       : 'execute';
     // Keep receipts, runner heartbeats, terminals, sheets, and runtime control
@@ -13566,17 +13469,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       options?.timeoutMs,
       this.currentAuthoringContractEdition,
     );
-    const provider = toolId.split(/[._]/)[0]?.trim() || 'provider';
-    const asyncContract = options?.skipAsyncOperationResolution
-      ? null
-      : ((await this.#options.getToolAsyncOperation?.(toolId)) ?? null);
-    const shouldWaitForAsyncOperation = Boolean(
-      asyncContract && asyncOperationShouldWait(asyncContract, input),
-    );
-    const effectiveInput =
-      asyncContract && shouldWaitForAsyncOperation
-        ? asyncOperationDurableStartInput(asyncContract, input)
-        : input;
     const activityId = `provider:${toolId}`;
     let retryActivityEmitted = false;
     let toolCallSucceeded = false;
@@ -13585,16 +13477,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     // execution. Per-provider rate admission is intentionally deferred until
     // each physical fetch is ready to leave this process.
     const admissionStartedAt = Date.now();
-    const asyncCapacityRelease =
-      asyncContract && shouldWaitForAsyncOperation
-        ? await this.acquireAsyncOperationCapacity({
-            toolId,
-            provider,
-            contract: asyncContract,
-            authScopeDigest:
-              (await this.resolveToolAuthScopeDigest(toolId))?.trim() ?? null,
-          })
-        : null;
     let toolSlot: RuntimeResourceLease;
     try {
       toolSlot = await this.resourceGovernor.acquireTool({
@@ -13603,7 +13485,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         toolId,
       });
     } catch (error) {
-      asyncCapacityRelease?.();
       if (!(error instanceof ProviderExhaustedError)) throw error;
       const retryAtMs = Date.parse(error.retryAt);
       throw createToolHttpError(
@@ -13659,9 +13540,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           // Snapshot the caller-controlled payload exactly once. The replay
           // decision and every physical attempt must refer to the same bytes,
           // even if the original object has getters or is later mutated.
-          const toolInputSnapshot = JSON.parse(
-            JSON.stringify(effectiveInput),
-          ) as Record<string, unknown>;
+          const toolInputSnapshot = JSON.parse(JSON.stringify(input)) as Record<
+            string,
+            unknown
+          >;
           const retryPolicy = await this.#options
             .getToolRetryPolicy?.(toolId, toolInputSnapshot)
             .catch(() => null);
@@ -13681,19 +13563,17 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           const ambiguousTransportReplayAllowed =
             readOnlyQuery || retrySafeTransientHttp;
           const invocationOrgId = this.#options.orgId?.trim() ?? '';
-          const durableCallReceiptKey =
-            options?.durableCallReceiptKey?.trim() ||
-            (requestsDurableInvocationFence && invocationOrgId
-              ? `${buildDurableToolReceiptPrefix({
-                  orgId: invocationOrgId,
-                  toolId,
-                })}${stableDigest(
-                  `transport:${this.currentRunId}:${toolId}:${crypto.randomUUID()}`,
-                )}`
-              : null);
-          const executionAuthScopeDigest = options?.executionAuthScopeDigest
-            ? options.executionAuthScopeDigest.trim() || null
-            : ((await this.resolveToolAuthScopeDigest(toolId))?.trim() ?? null);
+          const durableCallReceiptKey = uncachedAsyncLifecycleCall
+            ? null
+            : options?.durableCallReceiptKey?.trim() ||
+              (usesDurableInvocationFence && invocationOrgId
+                ? `${buildDurableToolReceiptPrefix({
+                    orgId: invocationOrgId,
+                    toolId,
+                  })}${stableDigest(
+                    `transport:${this.currentRunId}:${toolId}:${crypto.randomUUID()}`,
+                  )}`
+                : null);
           const executionRequestNonce = crypto.randomUUID();
           // This identifies one logical tool call to billing. Physical retry
           // count remains in request metadata, so a transport retry cannot
@@ -13713,6 +13593,29 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               `Tool ${toolId} requires a provider execution fence but no provider operation identity was supplied.`,
             );
           }
+          const canonicalOperationActionVersion = providerExecutionFenceKey
+            ? (
+                await this.#options.getToolActionCacheVersion?.(toolId)
+              )?.trim() || null
+            : null;
+          const canonicalOperation =
+            providerExecutionFenceKey && canonicalOperationActionVersion
+              ? {
+                  version: 1,
+                  tool_id: toolId,
+                  action_version: canonicalOperationActionVersion,
+                  play_scope: this.currentGovernance.currentPlayId || 'play',
+                  output_intent: options?.completedResultCache
+                    ? 'dataset'
+                    : 'value',
+                  ...(options?.providerOperationForceRefreshIdentities?.length
+                    ? {
+                        force_refresh_identities:
+                          options.providerOperationForceRefreshIdentities,
+                      }
+                    : {}),
+                }
+              : null;
           // Every runtime provider call carries at least a tool-scoped
           // attribution. Callers that know the execution location (row-scoped
           // map cells, batched owners) supply the fuller scope.
@@ -13724,7 +13627,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               metadata: {
                 parent_run_id: this.#options.runId,
                 invocation_attempt: invocationAttempt,
-                ...(requestsDurableInvocationFence
+                ...(shouldWaitForAsyncOperation
+                  ? { async_operation_wait: true }
+                  : {}),
+                ...(usesDurableInvocationFence
                   ? { invocation_fence_version: 1 }
                   : {}),
                 ...(durableCallReceiptKey
@@ -13749,6 +13655,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                         : {}),
                     }
                   : {}),
+                ...(canonicalOperation
+                  ? { canonical_operation: canonicalOperation }
+                  : {}),
                 ...(options?.customerDbDataset
                   ? {
                       query_result_dataset: {
@@ -14377,29 +14286,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     ? 'array'
                     : typeof parsed.result,
             });
-            const parsedValue =
-              parsed.toolResponse && 'raw' in parsed.toolResponse
-                ? parsed.toolResponse.raw
-                : (recordOrNull(parsed.result)?.data ?? parsed.result);
-            const asyncStartPending =
-              asyncContract && shouldWaitForAsyncOperation
-                ? classifyAsyncOperationResult(asyncContract, parsedValue)
-                    .outcome === 'running'
-                : false;
-            const resolved =
-              asyncContract &&
-              shouldWaitForAsyncOperation &&
-              (parsed.status === 'running' || asyncStartPending)
-                ? await this.resolveAsyncOperation({
-                    toolId,
-                    startInput: input,
-                    startResponse: parsed,
-                    contract: asyncContract,
-                    receiptKey: durableCallReceiptKey,
-                  })
-                : parsed;
             toolCallSucceeded = true;
-            return resolved;
+            return parsed;
           }
         },
       );
@@ -14426,7 +14314,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       if (!toolSlotTransferred) {
         toolSlot.release();
       }
-      asyncCapacityRelease?.();
     }
   }