deepline 0.3.392 → 0.3.394

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

@@ -25,6 +25,10 @@ import { AsyncLocalStorage } from 'async_hooks';
 import { isDatasetPayloadField } from '../play-data-plane/sheet-contract';
 import {
   createDeferredPlayDataset,
+  copyPlayDatasetSourceRowIdentity,
+  getPlayDatasetSourceRowIdentity,
+  getPlayDatasetSourceRowIdentityAt,
+  setPlayDatasetSourceRowIdentity,
   deserializeLegacyPlayDataset,
   deserializePlayDatasetCell,
   isPlayDataset,
@@ -32,6 +36,7 @@ import {
   isSerializedPlayDatasetCell,
   iteratePlayDatasetInputPages,
   materializePlayDatasetInput,
+  residentPlayDatasetRows,
   resolveMaterializeLimitCap,
   serializePlayDatasetCell,
 } from '../plays/dataset';
@@ -69,7 +74,10 @@ import type {
   ProviderPacingGrant,
 } from './governor/rate-state-backend';
 import type { MapRowOutcome } from './durability-store';
-import { stringifyPostgresJson } from './postgres-json';
+import {
+  sanitizePostgresJsonValue,
+  stringifyPostgresJson,
+} from './postgres-json';
 import { providerCapacityLabel } from './activity-observation';
 import { RUNTIME_ROW_OUTPUT_NOT_JSON_SERIALIZABLE } from './runtime-sheet-row-transition';
 import {
@@ -91,7 +99,10 @@ import {
 import {
   DURABLE_INVOCATION_FENCE_VERSION,
   durableInvocationFenceExecutePath,
+  buildRuntimeExecutionRecoveryKey,
+  RUNTIME_EXECUTION_RECOVERY_SUPPORTED_HEADER,
 } from './durable-invocation-fence';
+import { isImmutableRuntimeExecutionRecoveryOrigin } from './scheduler-backends/runtime-api-origin';
 import {
   isRetryableSecretResolutionStatus,
   secretResolutionRetryDecision,
@@ -184,6 +195,7 @@ import {
   type ToolExecuteResult,
   type ToolResultExecutionMetadata,
   type ToolResultMetadataInput,
+  type CallFreshnessMetadata,
 } from './tool-result';
 import {
   EXECUTION_GATEWAY_RECEIPT_OUTPUT_REFERENCE_HEADER,
@@ -258,9 +270,12 @@ import {
   scopeToolReceiptToInvocation,
   resolveDurableCallCachePolicy,
 } from './durable-call-cache';
+import { resolveExplicitDurableCallPolicy } from './durable-call-policy';
+import { executeWithFreshnessReceipt } from './freshness-receipt-execution';
 import {
   CtxFetchHttpError,
   PLAY_AUTHORING_CONTRACT_EDITION,
+  PlayAuthoringFieldValidationError,
   normalizePlayAuthoringCustomerDbStatement,
   validateOptionalPlayAuthoringField,
   validatePlayAuthoringField,
@@ -304,9 +319,11 @@ import {
   classifyAsyncOperationResult,
   executeAsyncOperationLifecycle,
   extractAsyncOperationJobId,
+  formatAsyncOperationTimeout,
   readAsyncOperationPath,
   asyncOperationShouldWait,
   hasExplicitAsyncOperationTerminalMatch,
+  resolveAsyncOperationPolling,
   type AsyncOperationContractWire,
 } from './async-operation';
 import {
@@ -626,6 +643,7 @@ const inlineCompositionContext =
 const authoredStepContext = new AsyncLocalStorage<{
   context: PlayContextImpl;
   stepId: string;
+  invocationId?: string;
 }>();
 const toolExecutionOverrides = new AsyncLocalStorage<{ force: boolean }>();
 const PROGRESS_HEARTBEAT_INTERVAL_MS = 1_000;
@@ -2918,6 +2936,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   private mapInvocationIndex = 0;
   private readonly stepCallIndexByKey = new Map<string, number>();
   private readonly toolCallIndexByKey = new Map<string, number>();
+  private readonly freshnessCallIndexByKey = new Map<string, number>();
   /**
    * Parent-level inline-child aggregates. Maintained only by the single-writer
    * progress path (never per child) so concurrent fan-out cannot contend. See
@@ -3195,7 +3214,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     key: string,
     toolId: string,
     input: Record<string, unknown>,
-    options?: { description?: string },
+    options?: {
+      description?: string;
+      staleAfterSeconds?: number | null;
+    },
   ): Promise<ToolExecuteResult<TOutput>> {
     validatePlayAuthoringField('ctx.tool.key', key);
     validatePlayAuthoringField('ctx.tool.tool', toolId);
@@ -3211,6 +3233,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       tool: toolId,
       input,
       ...(options?.description ? { description: options.description } : {}),
+      ...(options?.staleAfterSeconds !== undefined
+        ? { staleAfterSeconds: options.staleAfterSeconds }
+        : {}),
     })) as ToolExecuteResult<TOutput>;
   }
 
@@ -3220,9 +3245,41 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   readonly customerDb = {
     query: async <TRow extends object = Record<string, unknown>>(
       statement: PlaySqlQuery | string,
-      options?: { maxRows?: number; timeoutMs?: number },
+      options?: {
+        id?: string;
+        staleAfterSeconds?: number | null;
+        maxRows?: number;
+        timeoutMs?: number;
+      },
     ): Promise<TRow[]> => {
       const sql = normalizePlayAuthoringCustomerDbStatement(statement);
+      if (this.usesExplicitFreshness) {
+        validatePlayAuthoringField(
+          'ctx.customerDb.query.options.id',
+          options?.id,
+        );
+      } else if (options?.id !== undefined) {
+        validatePlayAuthoringField(
+          'ctx.customerDb.query.options.id',
+          options.id,
+        );
+      }
+      if (options?.staleAfterSeconds !== undefined) {
+        validatePlayAuthoringField(
+          'ctx.customerDb.query.options.staleAfterSeconds',
+          options.staleAfterSeconds,
+        );
+      }
+      if (
+        this.usesExplicitFreshness &&
+        options?.staleAfterSeconds === undefined
+      ) {
+        throw new PlayAuthoringFieldValidationError(
+          'ctx.customerDb.query.options.staleAfterSeconds',
+          'play_authoring_durable_policy_invalid',
+          'Edition 11 Customer DB queries require staleAfterSeconds: 0.',
+        );
+      }
       if (options?.maxRows !== undefined) {
         validatePlayAuthoringField(
           'ctx.customerDb.query.options.maxRows',
@@ -3236,7 +3293,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         );
       }
       const result = (await this.tools.execute({
-        id: `customer_db_query_${this.customerDbQueryIndex++}`,
+        id: options?.id ?? `customer_db_query_${this.customerDbQueryIndex++}`,
         tool: 'query_customer_db',
         input: {
           sql,
@@ -3247,7 +3304,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         description: 'Customer DB query',
         // The direct executor never reused a prior SQL result. Preserve that
         // imperative behavior for reads and mutations alike.
-        force: true,
+        ...(this.usesExplicitFreshness
+          ? { staleAfterSeconds: options?.staleAfterSeconds }
+          : { force: true }),
         ...(options?.timeoutMs !== undefined
           ? { timeoutMs: options.timeoutMs }
           : {}),
@@ -3853,6 +3912,95 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     return this.currentRuntimeContract.semantics;
   }
 
+  private get usesExplicitFreshness(): boolean {
+    return (
+      this.currentRuntimeSemantics.freshness ===
+      'actual_age_with_operation_recovery'
+    );
+  }
+
+  private freshnessInvocationId(operation: string, id: string): string {
+    const row = rowContext.getStore();
+    const step = authoredStepContext.getStore();
+    const scope = stableStringify({
+      namespace: this.currentExecutionScope.receipt.namespace,
+      operation,
+      id,
+      step: step?.context === this ? (step.invocationId ?? step.stepId) : null,
+      row: row
+        ? {
+            table: row.tableNamespace ?? null,
+            key: row.rowKey ?? row.rowId,
+            field: row.fieldName ?? null,
+          }
+        : null,
+    });
+    const freshIndex = this.freshnessCallIndexByKey.get(scope) ?? 0;
+    this.freshnessCallIndexByKey.set(scope, freshIndex + 1);
+    // Invocation identity follows authored scope and call order. Keep it
+    // separate from the request/auth/action fingerprint used by reusable
+    // result caching, so credential or response-contract changes cannot mint
+    // a second provider operation key for the same authored effect.
+    // A mapped row can be re-entered after provider backpressure; its replay
+    // cursor restores the original call position.
+    const index = nextReplayableCallIndex(`freshness:${scope}`, freshIndex);
+    return sha256Hex(`${scope}:${index}`);
+  }
+
+  private async executeFreshnessControlledCall<T>(input: {
+    operation: DurableCtxOperation;
+    id: string;
+    semanticKey: string;
+    invocationId: string;
+    policy: { requested: number | null; effective: number | null };
+    execute: () => Promise<T>;
+    completedAt?: (value: T) => number | undefined;
+    onOutcome?: (value: T, metadata: CallFreshnessMetadata) => T;
+  }): Promise<T> {
+    const orgId = this.#options.orgId?.trim();
+    if (!orgId) {
+      throw new Error(
+        'Freshness-controlled calls require a resolved organization identity.',
+      );
+    }
+    return executeWithFreshnessReceipt({
+      orgId,
+      semanticKey: input.semanticKey,
+      invocationId: input.invocationId,
+      runId: this.currentRunId,
+      requestedStaleAfterSeconds: input.policy.requested,
+      effectiveStaleAfterSeconds: input.policy.effective,
+      store: this.durableReceiptExecutionStore(),
+      completedAt: input.completedAt,
+      withHydration: (read) =>
+        this.withRuntimeReceiptHydrationTurn(
+          (turn) =>
+            read((receipt) =>
+              turn.settleBytes(
+                runtimeStepReceiptPayloadBytes(receipt ? [receipt] : []),
+              ),
+            ),
+          { source: 'durable_operation' },
+        ),
+      execute: async () => {
+        const value = await input.execute();
+        this.assertNoPendingDurableSuspension();
+        return value;
+      },
+      onOutcome: (value, metadata) => {
+        this.runtimeLog(
+          JSON.stringify({
+            event: 'call_freshness',
+            operation: input.operation,
+            call_key: input.id,
+            ...metadata,
+          }),
+        );
+        return input.onOutcome ? input.onOutcome(value, metadata) : value;
+      },
+    });
+  }
+
   private recordPlayCallStep(input: {
     playId: string;
     execution?: 'inline';
@@ -6284,6 +6432,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       force?: boolean;
       receiptKey?: string | null;
       semanticKey?: string | null;
+      invocationId?: string;
       staleAfterSeconds?: number | null;
       repairRunningReceiptForSameRun?: boolean;
       repairRunningReceiptForSameRunAfterWaitTimeout?: boolean;
@@ -6327,6 +6476,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         },
       });
     if (opts.transient === true) {
+      if (
+        this.usesExplicitFreshness &&
+        opts.staleAfterSeconds !== undefined &&
+        opts.staleAfterSeconds !== 0
+      ) {
+        throw new Error(
+          'Transient fetch does not support retained result reuse; omit freshness or choose staleAfterSeconds: 0.',
+        );
+      }
       try {
         return await execute(null);
       } finally {
@@ -6334,6 +6492,44 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         release?.();
       }
     }
+    if (this.usesExplicitFreshness && operation === 'fetch') {
+      const policy = resolveExplicitDurableCallPolicy(opts);
+      const semanticKey = stableStringify({
+        orgId: this.#options.orgId,
+        namespace: this.currentExecutionScope.receipt.namespace,
+        operation,
+        id,
+        semanticKey: opts.semanticKey,
+      });
+      try {
+        return await this.executeFreshnessControlledCall({
+          operation,
+          id,
+          semanticKey,
+          invocationId:
+            opts.invocationId ?? this.freshnessInvocationId(operation, id),
+          policy,
+          execute: () => execute(null),
+          onOutcome: (value, freshness) => {
+            const output =
+              opts.onRecovered && freshness.source !== 'executed'
+                ? opts.onRecovered(
+                    value,
+                    {
+                      key: freshness.operationReceiptKey!,
+                      status: 'completed',
+                    },
+                    'cache',
+                  )
+                : value;
+            return { ...output, freshness };
+          },
+        });
+      } finally {
+        const release = releaseExternalCallSlot as (() => void) | null;
+        release?.();
+      }
+    }
     const stalePolicy = resolveDurableCallCachePolicy(
       opts.staleAfterSeconds,
       operation === 'step'
@@ -8206,6 +8402,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         options.onRowError,
       );
       validateOptionalPlayAuthoringField('ctx.dataset.run.mode', options.mode);
+      validateOptionalPlayAuthoringField(
+        'ctx.dataset.run.rowIdentity',
+        options.rowIdentity,
+      );
       validateOptionalPlayAuthoringField(
         'ctx.dataset.run.undrawnColumns',
         options.undrawnColumns,
@@ -8260,11 +8460,53 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         ),
       );
 
+    const residentSourceRows = isPlayDataset(items)
+      ? residentPlayDatasetRows(items)
+      : Array.isArray(items)
+        ? items
+        : null;
+    const csvSource =
+      (isPlayDataset(items) && items.datasetKind === 'csv') ||
+      residentSourceRows?.some(
+        (_row, index) =>
+          getPlayDatasetSourceRowIdentityAt(residentSourceRows, index) !==
+          undefined,
+      ) === true;
+    const csvOccurrenceIdentityRequired =
+      csvSource &&
+      this.currentRuntimeSemantics.datasets.csvRowIdentity === 'source_row';
+    const rowIdentityMode = csvOccurrenceIdentityRequired
+      ? 'source_row'
+      : (options?.rowIdentity ??
+        (options?.key !== undefined
+          ? 'key'
+          : csvSource
+            ? this.currentRuntimeSemantics.datasets.csvRowIdentity
+            : 'key'));
+    const useSourceRowIdentity = rowIdentityMode === 'source_row';
     const userKeyOption = options?.key;
     let explicitKeyResolver:
       | ((row: Record<string, unknown>, index: number) => string)
       | null = null;
-    if (userKeyOption !== undefined) {
+    if (useSourceRowIdentity) {
+      explicitKeyResolver = (row, index) => {
+        const source = getPlayDatasetSourceRowIdentity(row);
+        const inputRow = Object.fromEntries(
+          Object.entries(toSerializableCsvAliasedRow(row)).filter(
+            ([field]) => !field.startsWith('__deepline'),
+          ),
+        );
+        // Position distinguishes equal records; the input digest prevents a
+        // changed file at the same path from replaying an earlier row's output.
+        return JSON.stringify([
+          'source-row-v1',
+          source?.datasetId ??
+            (isPlayDataset(items) ? items.datasetId : normalizedMapNamespace),
+          source?.rowIndex ?? index,
+          stableDigest(stableStringify(inputRow)),
+        ]);
+      };
+    } else if (userKeyOption !== undefined) {
       explicitKeyResolver = (row, index) => {
         const inputRow = stripFieldOutputs(row);
         const raw =
@@ -8469,6 +8711,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       let failedCount = 0;
       let duplicateReuseCount = 0;
       let executedCount = 0;
+      let sourceRowsCount = 0;
       const failureSamples: Array<{ rowLabel: string; error: string }> = [];
       const failureSampleErrors = new Set<string>();
       const previewRows: Record<string, unknown>[] = [];
@@ -8572,9 +8815,17 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         offset: number;
       }): Promise<PreparedPage> => {
         this.assertRowAdmissionOpen();
-        const pageRawItems = page.rows.map((item) =>
-          this.toOutputRow(item as Record<string, unknown>),
-        );
+        sourceRowsCount += page.rows.length;
+        const pageRawItems = page.rows.map((item, index) => {
+          const row = this.toOutputRow(item as Record<string, unknown>);
+          const sourceIdentity = getPlayDatasetSourceRowIdentityAt(
+            page.rows,
+            index,
+          );
+          return sourceIdentity
+            ? setPlayDatasetSourceRowIdentity(row, sourceIdentity)
+            : row;
+        });
         const pageMemoryEstimate = estimateRuntimeMapRowsMemory(pageRawItems);
         if (pageMemoryEstimate.estimatedResidentBytes > pageBudgetBytes) {
           throw new RuntimeMapMemoryLimitError({
@@ -8588,6 +8839,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           const originalIndex = page.offset + index;
           return {
             ...toSerializableCsvAliasedRow(row),
+            ...(getPlayDatasetSourceRowIdentity(row)
+              ? { __deeplineSourceRow: getPlayDatasetSourceRowIdentity(row) }
+              : {}),
             ...mapRowOutcomeRuntimeFields({
               key: seedRowIdentity(row, originalIndex),
               inputIndex: originalIndex,
@@ -8630,9 +8884,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           completedRowsByKey.set(rowKey, row);
         }
 
-        const seededItems = page.rows.map((item, index) => {
+        const seededItems = pageRawItems.map((row, index) => {
           const originalIndex = page.offset + index;
-          const row = this.toOutputRow(item as Record<string, unknown>);
           const rowKey = seedRowIdentity(row, originalIndex);
           const persisted =
             pendingRowsByKey.get(rowKey) ?? completedRowsByKey.get(rowKey);
@@ -8661,7 +8914,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           { row: Record<string, unknown>; originalIndex: number }
         >();
         for (const { row, index } of admittedSeededItems) {
-          if (explicitKeyResolver) {
+          if (explicitKeyResolver && !useSourceRowIdentity) {
             const explicitKey = explicitKeyResolver(row, index);
             if (seenExplicitKeys.has(explicitKey)) {
               duplicateReuseCount += 1;
@@ -8990,12 +9243,14 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       );
       successfulCount = visibleResults.completedRows;
       failedCount = visibleResults.failedRows;
-      this.#options.onMapRowsSettled?.({
+      await this.#options.onMapRowsSettled?.({
         playName: this.#options.playName,
         runId: this.#options.runId,
         tableNamespace: resolvedTableNamespace,
         succeededRows: successfulCount,
         failedRows: failedCount,
+        expectedRows: totalInputCount - duplicateReuseCount,
+        staticPipeline: this.currentStaticPipeline,
       });
 
       // Isolated failures are a partial result only when at least one admitted
@@ -9181,6 +9436,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           skipped: duplicateReuseCount,
           pending: 0,
           failed: failedCount,
+          cardinality: {
+            sourceRows: sourceRowsCount,
+            uniqueInputRows: processedCount - duplicateReuseCount,
+            duplicateOccurrences: duplicateReuseCount,
+            outputRows: successfulCount,
+            rowIdentity: rowIdentityMode,
+          },
           ...(duplicateReuseCount > 0
             ? { duplicates: { exact: duplicateReuseCount } }
             : {}),
@@ -9228,24 +9490,66 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         },
       });
     }
-    const rawMaterializedEntries =
+    const rawMaterializedEntries: {
+      item: T;
+      inputIndex: number;
+      sourceIdentity?: ReturnType<typeof getPlayDatasetSourceRowIdentityAt>;
+    }[] =
       resumedPendingRowsOnly && suspendedInputRows
-        ? suspendedInputRows.map((row) => ({
-            item: cloneCsvAliasedRow(row.data) as T,
-            inputIndex: row.inputIndex,
-          }))
-        : (
-            await materializePlayDatasetInput(items, {
+        ? suspendedInputRows.map((row) => {
+            const retainedKey = resolveMapRowOutcomeKey(row.data);
+            return {
+              // Older checkpoints contain only execution data. New checkpoints
+              // also retain the original admission input before sheet outputs
+              // were restored; keep the already-admitted key across either path.
+              item: cloneCsvAliasedRow(
+                row.authoredInput?.data ?? row.data,
+                retainedKey
+                  ? mapRowOutcomeRuntimeFields({ key: retainedKey })
+                  : {},
+              ) as T,
+              inputIndex: row.inputIndex,
+              sourceIdentity: row.authoredInput?.source,
+            };
+          })
+        : await (async () => {
+            const materialized = await materializePlayDatasetInput(items, {
               onRow: (row) => {
                 materializationMemoryTracker.track(row);
               },
-            })
-          ).map((item, inputIndex) => ({ item, inputIndex }));
+            });
+            return materialized.map((item, inputIndex) => ({
+              item,
+              inputIndex,
+              sourceIdentity: getPlayDatasetSourceRowIdentityAt(
+                materialized,
+                inputIndex,
+              ),
+            }));
+          })();
     const rawMaterializedItems = rawMaterializedEntries.map(
-      (entry) => entry.item,
+      // Occurrence identity also applies to an explicitly selected array whose
+      // author reused the same object reference. Give each occurrence its own
+      // execution object so the original-index lookup cannot alias the last row.
+      (entry) => {
+        const sourceIdentity =
+          'sourceIdentity' in entry
+            ? entry.sourceIdentity
+            : getPlayDatasetSourceRowIdentity(entry.item);
+        if (!useSourceRowIdentity && !sourceIdentity) return entry.item;
+        const row = this.toOutputRow(entry.item);
+        return (
+          sourceIdentity
+            ? setPlayDatasetSourceRowIdentity(row, sourceIdentity)
+            : row
+        ) as T;
+      },
     );
     const originalInputIndexByItem = new Map<T, number>(
-      rawMaterializedEntries.map(({ item, inputIndex }) => [item, inputIndex]),
+      rawMaterializedItems.map((item, index) => [
+        item,
+        rawMaterializedEntries[index]!.inputIndex,
+      ]),
     );
     // Silent dedupe of duplicate explicit map keys: keep the first row per
     // canonical key and drop subsequent duplicates. Deduping the materialized
@@ -9253,24 +9557,75 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     // counts, sheet writes, resumable keys) consistent — the resolver derives
     // keys from row content, so dropped rows are excluded everywhere with no
     // index mismatch. Replaces the prior throw-on-duplicate behavior.
-    const dedupedMaterialized = explicitKeyResolver
-      ? dedupeExplicitMapKeyRows({
-          rows: rawMaterializedItems,
-          resolver: (item, index) =>
-            explicitKeyResolver(
-              this.toOutputRow(item as Record<string, unknown>),
-              originalInputIndexByItem.get(item) ?? index,
-            ),
-        })
-      : { rows: rawMaterializedItems, droppedCount: 0, duplicateKeys: [] };
+    const dedupedMaterialized =
+      explicitKeyResolver && !useSourceRowIdentity
+        ? dedupeExplicitMapKeyRows({
+            rows: rawMaterializedItems,
+            resolver: (item, index) =>
+              explicitKeyResolver(
+                this.toOutputRow(item as Record<string, unknown>),
+                originalInputIndexByItem.get(item) ?? index,
+              ),
+          })
+        : { rows: rawMaterializedItems, droppedCount: 0, duplicateKeys: [] };
     if (dedupedMaterialized.droppedCount > 0) {
-      const keySample = dedupedMaterialized.duplicateKeys.join(', ');
       this.runtimeLog(
-        `deduped ${dedupedMaterialized.droppedCount} duplicate dataset key(s) for ctx.dataset("${normalizedMapNamespace}"); keeping first occurrence` +
-          (keySample ? ` (e.g. ${keySample})` : ''),
+        `[runtime.dataset_input_cardinality] ${JSON.stringify({
+          dataset: normalizedMapNamespace,
+          rowIdentity: rowIdentityMode,
+          sourceRows: rawMaterializedEntries.length,
+          uniqueInputRows: dedupedMaterialized.rows.length,
+          duplicateOccurrences: dedupedMaterialized.droppedCount,
+          duplicatePolicy: 'first_wins',
+        })}`,
       );
     }
     const materializedItems = dedupedMaterialized.rows;
+    // A legacy checkpoint does not contain its pre-dedupe source cardinality.
+    // Leave the optional summary absent rather than report its pending subset
+    // as the original source. New checkpoints retain only fixed-size counts.
+    const inputCardinality = resumedPendingRowsOnly
+      ? replayMapFrame?.inputCardinality
+      : {
+          sourceRows: rawMaterializedEntries.length,
+          uniqueInputRows: materializedItems.length,
+          duplicateOccurrences: dedupedMaterialized.droppedCount,
+          rowIdentity: rowIdentityMode,
+        };
+    // Admission provenance is captured before onMapStart restores output
+    // cells. The execution row stays intact; only pending inputs enter a
+    // checkpoint, and their sheet outputs are restored by the existing owner
+    // after the next admission. Never infer original input from enriched data.
+    const retainedAuthoredInputsByIndex = new Map(
+      (suspendedInputRows ?? []).flatMap((row) =>
+        row.authoredInput ? [[row.inputIndex, row.authoredInput] as const] : [],
+      ),
+    );
+    const authoredInputsByIndex = new Map(
+      canReadPersistedMapResults
+        ? materializedItems.flatMap((item, index) => {
+            const inputIndex = originalInputIndexByItem.get(item) ?? index;
+            if (resumedPendingRowsOnly) {
+              const retained = retainedAuthoredInputsByIndex.get(inputIndex);
+              // An older pending checkpoint has execution data only. Keep its
+              // optional provenance absent rather than relabel enriched cells.
+              return retained ? [[inputIndex, retained] as const] : [];
+            }
+            const row = this.toOutputRow(item as Record<string, unknown>);
+            const source = getPlayDatasetSourceRowIdentity(row);
+            const data = sanitizePostgresJsonValue(
+              toSerializableCsvAliasedRow(row),
+            );
+            materializationMemoryTracker.track(data);
+            return [
+              [
+                inputIndex,
+                { data, ...(source ? { source: { ...source } } : {}) },
+              ] as const,
+            ];
+          })
+        : [],
+    );
     const priorAuthoredDigestsByIndex = new Map(
       (suspendedInputRows ?? []).flatMap((row) =>
         row.authoredInputDigest
@@ -9405,6 +9760,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         const inputIndex = itemOriginalIndexes[index] ?? index;
         return {
           ...toSerializableCsvAliasedRow(row),
+          ...(getPlayDatasetSourceRowIdentity(row)
+            ? { __deeplineSourceRow: getPlayDatasetSourceRowIdentity(row) }
+            : {}),
           ...mapRowOutcomeRuntimeFields({
             key: seedRowIdentity(row, inputIndex),
             inputIndex,
@@ -9513,6 +9871,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       artifactTableNamespace: mapScope.artifactTableNamespace,
       status: 'running',
       totalRows: totalInputCount,
+      inputCardinality,
       completedRowKeys,
       pendingRowKeys,
       completedRowsCount: previouslyCompletedRowsCount,
@@ -9663,13 +10022,17 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           executionRowIndexes: rowsToExecuteEntries.map(
             (entry) => entry.originalIndex,
           ),
-          ...(!canReadPersistedMapResults
+          ...(canReadPersistedMapResults
             ? {
+                authoredInputs: rowsToExecuteEntries.map((entry) =>
+                  authoredInputsByIndex.get(entry.originalIndex),
+                ),
+              }
+            : {
                 authoredInputDigests: rowsToExecuteEntries.map((entry) =>
                   authoredInputDigestsByIndex.get(entry.originalIndex),
                 ),
-              }
-            : {}),
+              }),
           retainedRowsMemoryBudgetBytes:
             mapMemoryLimits.materializedBudgetBytes,
           progressCompletedOffset:
@@ -9854,13 +10217,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       });
     }
 
-    this.#options.onMapRowsSettled?.({
+    await this.#options.onMapRowsSettled?.({
       playName: this.#options.playName,
       runId: this.#options.runId,
       tableNamespace: resolvedTableNamespace,
       succeededRows:
         previouslyCompletedRowKeys.length + visibleCompletedRows.length,
       failedRows: durableFailedRows,
+      expectedRows: totalInputCount - duplicateReuseCount,
+      staticPipeline: this.currentStaticPipeline,
     });
 
     // This map's terminal rows have already crossed the persistence barrier
@@ -9950,8 +10315,24 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         skipped: reusedCount,
         pending: 0,
         failed: durableFailedRows,
-        ...(duplicateReuseCount > 0
-          ? { duplicates: { exact: duplicateReuseCount } }
+        ...(inputCardinality
+          ? {
+              cardinality: {
+                ...inputCardinality,
+                uniqueInputRows:
+                  inputCardinality.uniqueInputRows - duplicateReuseCount,
+                duplicateOccurrences:
+                  inputCardinality.duplicateOccurrences + duplicateReuseCount,
+                outputRows: results.length,
+              },
+            }
+          : {}),
+        ...(dedupedMaterialized.droppedCount + duplicateReuseCount > 0
+          ? {
+              duplicates: {
+                exact: dedupedMaterialized.droppedCount + duplicateReuseCount,
+              },
+            }
           : {}),
       },
       resolvers: {
@@ -9989,6 +10370,11 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       onRowError?: 'isolate' | 'fail';
       executionRowKeys?: string[];
       executionRowIndexes?: number[];
+      authoredInputs?: Array<
+        NonNullable<
+          MapExecutionFrame['suspendedInputRows']
+        >[number]['authoredInput']
+      >;
       authoredInputDigests?: Array<string | undefined>;
       /**
        * Opt-in cap on how many row resolvers run their body concurrently. When
@@ -10796,6 +11182,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   ),
                   ...mapRowOutcomeRuntimeFields({ key: rowKey }),
                 },
+                ...(runtimeOptions?.authoredInputs?.[index]
+                  ? { authoredInput: runtimeOptions.authoredInputs[index] }
+                  : {}),
                 ...(runtimeOptions?.authoredInputDigests?.[index]
                   ? {
                       authoredInputDigest:
@@ -11204,6 +11593,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                       key: keyForIndex(index),
                     }),
                   },
+                  ...(runtimeOptions?.authoredInputs?.[index]
+                    ? { authoredInput: runtimeOptions.authoredInputs[index] }
+                    : {}),
                   ...(runtimeOptions?.authoredInputDigests?.[index]
                     ? {
                         authoredInputDigest:
@@ -11453,6 +11845,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     stepPath,
                   }),
                 ),
+                ...(step.staleAfterSeconds !== undefined
+                  ? { staleAfterSeconds: step.staleAfterSeconds }
+                  : {}),
               },
             )
           : await this.executeStepProgramStep(
@@ -12530,7 +12925,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
   private toOutputRow<T>(item: T): Record<string, unknown> {
     if (item != null && typeof item === 'object' && !Array.isArray(item)) {
-      return stripCsvProjectionMetadata(item as Record<string, unknown>);
+      return copyPlayDatasetSourceRowIdentity(
+        item,
+        stripCsvProjectionMetadata(item as Record<string, unknown>),
+      );
     }
 
     return { value: item };
@@ -12739,6 +13137,165 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     toolId: string,
     input: Record<string, unknown>,
     options?: ToolCallOptions,
+  ): Promise<unknown> {
+    if (!this.usesExplicitFreshness) {
+      return this.executeToolLegacyInternal(key, toolId, input, options);
+    }
+    const policy = resolveExplicitDurableCallPolicy(options ?? {});
+    if (
+      this.#options.cachePolicy?.forceToolRefresh === true ||
+      toolExecutionOverrides.getStore()?.force === true
+    ) {
+      policy.effective = 0;
+    }
+    const normalizedKey = this.normalizeContextKey(key, 'tool');
+    // Reserve operation identity before asynchronous metadata lookup. Two
+    // concurrent calls may share an authored id; assigning their identity
+    // after auth/action metadata resolves would make recovery depend on lookup
+    // completion order instead of authored call order.
+    const invocationId = this.freshnessInvocationId('tool', normalizedKey);
+    const sqlTool = isCustomerDbDatasetTool(toolId);
+    const scalarCustomerDbQuery = sqlTool && input.result_mode === 'rows';
+    const liveDataset =
+      isQueryResultDatasetReadRequest(toolId, input) && !scalarCustomerDbQuery;
+    const sqlMutation =
+      sqlTool &&
+      !isQueryResultDatasetReadRequest(toolId, {
+        ...input,
+        result_mode: undefined,
+      });
+    const [eventWait, invocationScoped, retryPolicy, reusableSupport] =
+      policy.effective === 0
+        ? ([null, false, null, null] as const)
+        : await Promise.all([
+            this.#options.getIntegrationEventWaitHandler?.(toolId) ?? null,
+            this.#options
+              .getToolIdempotencyScope?.(toolId)
+              .then((scope) => scope === 'invocation') ?? false,
+            this.#options.getToolRetryPolicy?.(toolId, input) ?? null,
+            this.#options.getToolReusableResultSupport?.(toolId) ?? null,
+          ]);
+    const requiresExecutionFence = retryPolicy?.requiresExecutionFence === true;
+    if (policy.effective !== 0 && reusableSupport?.supported !== true) {
+      throw new Error(
+        `Tool ${toolId} does not support reusable freshness; use staleAfterSeconds: 0. ${reusableSupport?.unavailableReason ?? 'No read-result reuse capability was supplied by the action owner.'}`,
+      );
+    }
+    if (
+      policy.effective !== 0 &&
+      (eventWait ||
+        invocationScoped ||
+        requiresExecutionFence ||
+        liveDataset ||
+        sqlMutation ||
+        isAlwaysFreshIntegrationTool(toolId))
+    ) {
+      throw new Error(
+        `Tool ${toolId} does not support reusable freshness; use staleAfterSeconds: 0. Live datasets, event waits, invocation-scoped actions, writes, and Workspace operations cannot reuse an older result.`,
+      );
+    }
+
+    const authScope = await this.resolveToolAuthScopeDigest(toolId);
+    const actionVersion =
+      (await this.#options.getToolActionCacheVersion?.(toolId))?.trim() ?? '';
+    if (!actionVersion) {
+      throw new Error(`Tool ${toolId} has no action identity for freshness.`);
+    }
+    const semanticKey = stableStringify({
+      kind: 'tool',
+      orgId: this.#options.orgId,
+      toolId,
+      input,
+      authScope,
+      actionVersion,
+      responseContract: this.currentToolResponseContract,
+      responseRevision: this.currentToolResponseReceiptRevision,
+    });
+    if (sqlTool && input.operation_key !== undefined) {
+      throw new Error(
+        'Play SQL operation identity is assigned by the runtime. Use the authored call id to identify the operation.',
+      );
+    }
+    const requestInput =
+      sqlTool && (sqlMutation || scalarCustomerDbQuery)
+        ? { ...input, operation_key: `${this.currentRunId}:${invocationId}` }
+        : input;
+
+    if (liveDataset || isAlwaysFreshIntegrationTool(toolId)) {
+      const value = await this.executeToolLegacyInternal(
+        key,
+        toolId,
+        requestInput,
+        { ...options, force: true, staleAfterSeconds: 0 },
+      );
+      const freshness: CallFreshnessMetadata = {
+        requestedStaleAfterSeconds: policy.requested,
+        effectiveStaleAfterSeconds: 0,
+        source: 'live_observation',
+        resultAgeMs: 0,
+        completedAt: Date.now(),
+        unavailableReason: liveDataset
+          ? 'Dataset rows are live observations; the dataset owner controls pagination and recovery.'
+          : 'Workspace reviewer edits and conflict checks must be observed on every invocation.',
+      };
+      return isToolExecuteResult(value)
+        ? cloneToolExecuteResultWithExecution(value, {
+            ...value._metadata.execution,
+            freshness,
+          })
+        : value;
+    }
+
+    return this.executeFreshnessControlledCall({
+      operation: 'tool',
+      id: normalizedKey,
+      semanticKey,
+      invocationId,
+      policy,
+      completedAt: (value) => {
+        if (!isToolExecuteResult(value)) return undefined;
+        const raw = value.toolResponse.raw as {
+          operation?: { completed_at_ms?: unknown };
+        } | null;
+        const completedAt = raw?.operation?.completed_at_ms;
+        return typeof completedAt === 'number' &&
+          Number.isSafeInteger(completedAt)
+          ? completedAt
+          : value._metadata.execution.completedAt;
+      },
+      execute: async () => {
+        const value = await this.executeToolLegacyInternal(
+          key,
+          toolId,
+          requestInput,
+          { ...options, force: true, staleAfterSeconds: 0 },
+        );
+        if ((await this.resolveToolAuthScopeDigest(toolId)) !== authScope) {
+          throw new Error(
+            'Tool credential identity changed during execution. Resume under the current credential identity before retaining this result.',
+          );
+        }
+        return value;
+      },
+      onOutcome: (value, freshness) =>
+        isToolExecuteResult(value)
+          ? cloneToolExecuteResultWithExecution(value, {
+              ...value._metadata.execution,
+              cached: freshness.source !== 'executed',
+              source: freshness.source === 'executed' ? 'live' : 'cache',
+              resultReceiptKey: freshness.operationReceiptKey,
+              freshness,
+              completedAt: freshness.completedAt,
+            })
+          : value,
+    });
+  }
+
+  private async executeToolLegacyInternal(
+    key: string,
+    toolId: string,
+    input: Record<string, unknown>,
+    options?: ToolCallOptions,
   ): Promise<unknown> {
     if (!rowContext.getStore()) this.assertRowAdmissionOpen();
     this.assertNoPendingDurableSuspension();
@@ -14873,6 +15430,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     if (!rowContext.getStore()) this.assertRowAdmissionOpen();
     validatePlayAuthoringField('ctx.fetch.key', key);
     const normalizedKey = this.normalizeContextKey(key, 'fetch');
+    const invocationId =
+      this.usesExplicitFreshness && options?.transient !== true
+        ? this.freshnessInvocationId('fetch', normalizedKey)
+        : undefined;
     const rowStore = rowContext.getStore();
     const rowFetchScope = rowStore
       ? {
@@ -14886,6 +15447,30 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     const url = input.toString();
     const parsedUrl = new URL(url);
     const method = (init.method ?? 'GET').toUpperCase();
+    const reusableReadMethod = ['GET', 'HEAD', 'OPTIONS'].includes(method);
+    if (this.usesExplicitFreshness && options?.transient === true) {
+      if (!reusableReadMethod) {
+        throw new Error(
+          'Edition 11 transient fetches are limited to read-only HTTP methods.',
+        );
+      }
+      if (
+        options.staleAfterSeconds !== undefined &&
+        options.staleAfterSeconds !== 0
+      ) {
+        throw new Error(
+          'Transient fetch does not support retained result reuse; omit freshness or choose staleAfterSeconds: 0.',
+        );
+      }
+    } else if (
+      this.usesExplicitFreshness &&
+      !reusableReadMethod &&
+      options?.staleAfterSeconds !== 0
+    ) {
+      throw new Error(
+        'Edition 11 mutating or non-read-only fetches require staleAfterSeconds: 0.',
+      );
+    }
     const urlContainsResolvedSecret =
       this.secretRedactor.containsRegisteredSecret(url, {
         includeEncoded: true,
@@ -14975,6 +15560,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               : {}),
           }),
         ),
+        invocationId,
         staleAfterSeconds: options?.staleAfterSeconds,
         transient: options?.transient === true,
         onRecovered: (output) => {
@@ -15026,6 +15612,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 },
                 body: receiptBody,
                 row: rowFetchScope,
+                ...(invocationId ? { invocationId } : {}),
               }),
             )}`,
           );
@@ -15174,6 +15761,24 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       'ctx.step.semanticKey',
       options?.semanticKey,
     );
+    const freshnessPolicy = this.usesExplicitFreshness
+      ? resolveExplicitDurableCallPolicy(options ?? {})
+      : null;
+    if (
+      freshnessPolicy &&
+      this.#options.cachePolicy?.forceStepRefresh === true
+    ) {
+      freshnessPolicy.effective = 0;
+    }
+    if (
+      freshnessPolicy &&
+      freshnessPolicy.requested !== 0 &&
+      !options?.semanticKey?.trim()
+    ) {
+      throw new Error(
+        'Reusable ctx.step results require a stable semanticKey.',
+      );
+    }
     const normalizedKey = this.normalizeContextKey(key, 'step');
     if (!normalizedKey.trim()) {
       throw new Error('ctx.step(key, fn) requires a non-empty stable step id.');
@@ -15181,7 +15786,26 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
     const rowStore = rowContext.getStore();
     const scope = rowStore ? `row-${rowStore.rowId}` : 'workflow';
-    const callIndexKey = `${this.currentExecutionScope.receipt.namespace}:${scope}:${normalizedKey}`;
+    const parentStep = authoredStepContext.getStore();
+    const explicitStepScope = freshnessPolicy
+      ? stableDigest(
+          stableStringify({
+            semanticKey: options?.semanticKey ?? null,
+            parent:
+              parentStep?.context === this
+                ? (parentStep.invocationId ?? parentStep.stepId)
+                : null,
+            row: rowStore
+              ? {
+                  table: rowStore.tableNamespace,
+                  key: rowStore.rowKey ?? rowStore.rowId,
+                  field: rowStore.fieldName,
+                }
+              : null,
+          }),
+        )
+      : null;
+    const callIndexKey = `${this.currentExecutionScope.receipt.namespace}:${scope}:${normalizedKey}${explicitStepScope ? `:${explicitStepScope}` : ''}`;
     const freshCallIndex = this.stepCallIndexByKey.get(callIndexKey) ?? 0;
     const callIndex = nextReplayableCallIndex(
       `step:${callIndexKey}`,
@@ -15193,7 +15817,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     );
     const boundarySuffix = callIndex === 0 ? '' : `:${callIndex}`;
     const boundaryId = this.durableBoundaryId(
-      `step-${scope}:${normalizedKey}${boundarySuffix}`,
+      `step-${scope}:${normalizedKey}${explicitStepScope ? `:${explicitStepScope}` : ''}${boundarySuffix}`,
     );
     const advanceRecoveredSleepCursor = async (
       receipt?: RuntimeStepReceipt,
@@ -15276,9 +15900,63 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       });
     try {
       const output = await authoredStepContext.run(
-        { context: this, stepId: normalizedKey },
-        () =>
-          this.executeWithRuntimeReceipt<T>(
+        {
+          context: this,
+          stepId: normalizedKey,
+          ...(freshnessPolicy ? { invocationId: boundaryId } : {}),
+        },
+        async () => {
+          if (freshnessPolicy) {
+            const semanticKey = stableStringify({
+              operation: 'step',
+              orgId: this.#options.orgId,
+              namespace: this.currentExecutionScope.receipt.namespace,
+              id: normalizedKey,
+              semanticKey: options?.semanticKey,
+              row: rowStore
+                ? {
+                    table: rowStore.tableNamespace,
+                    key: rowStore.rowKey ?? rowStore.rowId,
+                    field: rowStore.fieldName,
+                  }
+                : null,
+            });
+            const completed = await this.executeFreshnessControlledCall({
+              operation: 'step',
+              id: normalizedKey,
+              semanticKey,
+              invocationId: boundaryId,
+              policy: freshnessPolicy,
+              completedAt: (value) => value.completedAt,
+              execute: async () => {
+                const before = this.sleepBoundaryIndex;
+                const value = await executeStep();
+                const boundary =
+                  this.checkpoint.resolvedBoundaries?.[boundaryId];
+                return {
+                  output: value === undefined ? null : value,
+                  undefinedOutput: value === undefined,
+                  sleepCount: this.sleepBoundaryIndex - before,
+                  completedAt:
+                    (boundary?.kind === 'step'
+                      ? boundary.completedAt
+                      : undefined) ?? Date.now(),
+                };
+              },
+              onOutcome: (value, freshness) => {
+                if (freshness.source !== 'executed') {
+                  this.sleepBoundaryIndex += value.sleepCount;
+                }
+                return value;
+              },
+            });
+            const result = completed.undefinedOutput
+              ? undefined
+              : completed.output;
+            assertJsonSerializableStepOutput(normalizedKey, result);
+            return result as T;
+          }
+          return await this.executeWithRuntimeReceipt<T>(
             'step',
             normalizedKey,
             this.currentRunId,
@@ -15308,7 +15986,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               },
               execute: executeStep,
             },
-          ),
+          );
+        },
       );
       if (observe)
         this.emitExecutionEvent({
@@ -17746,6 +18425,17 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     );
     const shouldWaitAtExecutionBoundary =
       shouldWaitForAsyncOperation && !shouldResolveAsyncOperationInRuntime;
+    const asyncExecutionRecovery = shouldWaitAtExecutionBoundary
+      ? await this.#options.getToolAsyncExecutionRecovery?.(toolId)
+      : null;
+    if (
+      asyncExecutionRecovery &&
+      !isImmutableRuntimeExecutionRecoveryOrigin(asyncExecutionRecovery.origin)
+    ) {
+      throw new Error(
+        'Async execution recovery requires the serving app immutable origin. No provider request was sent.',
+      );
+    }
     // An explicitly opted-in caller-managed launch gives the Play author the
     // provider handle and leaves polling to the authored graph. Do not let a
     // provider's legacy synchronous helper turn a wide start wave into
@@ -18106,6 +18796,70 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           // map cells, batched owners) supply the fuller scope.
           const playNodeScope =
             options?.playNodeScope ?? buildPlayNodeScope({ toolId });
+          const asyncRecoveryInvocationKey = asyncExecutionRecovery
+            ? stableDigest(
+                stableStringify({
+                  toolId,
+                  // A queued call/chunk supplies its exact durable transport
+                  // identity. A direct invocation owns a fresh call identity.
+                  callIdentity:
+                    options?.durableCallReceiptKey ??
+                    (options?.providerOperationForceRefreshIdentities?.length
+                      ? options.providerOperationForceRefreshIdentities
+                      : (options?.providerIdempotencyKey ??
+                        executionRequestNonce)),
+                  payload: toolInputSnapshot,
+                  authScope: executionAuthScopeDigest,
+                  playNodeScope,
+                  forceRefreshIdentities:
+                    options?.providerOperationForceRefreshIdentities ?? [],
+                }),
+              )
+            : null;
+          const asyncRecoveryPolling = asyncExecutionRecovery
+            ? resolveAsyncOperationPolling({
+                contract: asyncContract!,
+                startInput: toolInputSnapshot,
+                playRuntimeWait: true,
+              })
+            : null;
+          const asyncRecoveryDeadlineAtMs = asyncRecoveryPolling
+            ? Date.now() + asyncRecoveryPolling.timeoutMs
+            : null;
+          let confirmedAsyncRecoveryPending = false;
+          let asyncRecoveryWaitTimeout: ReturnType<
+            typeof createToolHttpError
+          > | null = null;
+          const asyncRecoveryWaitTimeoutError = () =>
+            (asyncRecoveryWaitTimeout ??= createToolHttpError(
+              toolErrorSchemaVersion,
+              formatAsyncOperationTimeout({
+                startAction: asyncContract!.lifecycle.startAction,
+                jobId: null,
+                timeoutDescription: `${asyncRecoveryPolling!.timeoutMs}ms`,
+              }) +
+                ' The execution remains recoverable under its original idempotency key; it will not be relaunched.',
+              null,
+              504,
+              'repairable',
+              {
+                toolId,
+                provider,
+                operation: toolId,
+                code: 'ASYNC_OPERATION_TIMEOUT',
+                origin: 'provider',
+                category: 'upstream',
+                retryable: false,
+                statusCode: 504,
+              },
+            ));
+          const asyncRecoveryKey = (attempt: number) =>
+            asyncRecoveryInvocationKey
+              ? buildRuntimeExecutionRecoveryKey({
+                  parentRunId: this.currentRunId,
+                  invocationKey: `${asyncRecoveryInvocationKey}:attempt:${attempt}`,
+                })
+              : null;
           // This is deliberately a claim about only the immediately preceding
           // *durable* provider attempt. The execution gateway validates and
           // attests it before a retried call can use its fresh charge
@@ -18361,6 +19115,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               transportAttempt < TOOL_EXECUTE_TRANSPORT_MAX_ATTEMPTS &&
               (input.knownNotDispatched === true ||
                 usesDurableInvocationFence ||
+                asyncExecutionRecovery ||
                 ambiguousTransportReplayAllowed ||
                 fixtureReplaySafe)
             ) {
@@ -18368,7 +19123,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               // attempt and any prior provider-429 proof belong to the logical
               // invocation; only a definite retryable HTTP outcome advances it.
               // Ordinary transport retries retain their physical attempt count.
-              if (!usesDurableInvocationFence) {
+              if (!usesDurableInvocationFence && !asyncExecutionRecovery) {
                 providerRateLimitRetryFromInvocationAttempt = null;
                 invocationAttempt += 1;
               }
@@ -18454,6 +19209,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
           while (true) {
             toolAbortSignal?.throwIfAborted();
+            if (
+              confirmedAsyncRecoveryPending &&
+              Date.now() >= asyncRecoveryDeadlineAtMs!
+            ) {
+              throw asyncRecoveryWaitTimeoutError();
+            }
             if (
               providerNoProgressExpired({
                 startedAtMsByScope:
@@ -18806,6 +19567,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                           // A stale permit can take arbitrarily long to
                           // replace. Only fixture residence and the physical
                           // HTTP exchange spend the tool execution deadline.
+                          if (
+                            confirmedAsyncRecoveryPending &&
+                            Date.now() >= asyncRecoveryDeadlineAtMs!
+                          ) {
+                            throw asyncRecoveryWaitTimeoutError();
+                          }
                           armProviderTimeout();
                           beginProviderExecution();
                           const fetchedAt = Date.now();
@@ -18865,6 +19632,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                                     }
                                   : {}),
                                 'x-deepline-request-id': deeplineRequestId,
+                                ...(asyncRecoveryKey(invocationAttempt)
+                                  ? {
+                                      'idempotency-key':
+                                        asyncRecoveryKey(invocationAttempt)!,
+                                    }
+                                  : {}),
                                 ...(providerExecutionFenceKey
                                   ? {
                                       'x-deepline-idempotency-key':
@@ -19247,6 +20020,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 receiptHeartbeatSupervisor?.stop();
               }
             } catch (error) {
+              if (
+                asyncRecoveryWaitTimeout !== null &&
+                error === asyncRecoveryWaitTimeout
+              ) {
+                throw error;
+              }
               if (heartbeatFailure) {
                 throw heartbeatFailure;
               }
@@ -19366,6 +20145,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               const transportReplaySafe =
                 !ambiguousDispatchedFailure ||
                 usesDurableInvocationFence ||
+                Boolean(asyncExecutionRecovery) ||
                 ambiguousTransportReplayAllowed ||
                 fixtureReplaySafe;
               if (!transportReplaySafe) {
@@ -19444,8 +20224,62 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               continue;
             }
 
+            if (
+              asyncExecutionRecovery &&
+              response.ok &&
+              response.headers.get(
+                RUNTIME_EXECUTION_RECOVERY_SUPPORTED_HEADER,
+              ) !== 'true'
+            ) {
+              throw createToolHttpError(
+                toolErrorSchemaVersion,
+                `Tool ${toolId} did not confirm the declared async recovery reader. The execution will not be relaunched.`,
+                null,
+                response.status,
+                'repairable',
+              );
+            }
+
             if (!response.ok) {
               const text = responseErrorText ?? '';
+              const recoveryKey = asyncRecoveryKey(invocationAttempt);
+              if (
+                recoveryKey &&
+                response.status === 409 &&
+                response.headers.get(
+                  RUNTIME_EXECUTION_RECOVERY_SUPPORTED_HEADER,
+                ) === 'true'
+              ) {
+                const pending = (() => {
+                  try {
+                    return JSON.parse(text) as Record<string, unknown>;
+                  } catch {
+                    return null;
+                  }
+                })();
+                const recovery = pending?.executionRecovery as
+                  | Record<string, unknown>
+                  | undefined;
+                if (
+                  pending?.code === 'EXECUTION_IN_PROGRESS' &&
+                  pending.retryable === true &&
+                  recovery?.idempotencyKey === recoveryKey &&
+                  (recovery.state === 'running' ||
+                    recovery.state === 'completed')
+                ) {
+                  confirmedAsyncRecoveryPending = true;
+                  if (Date.now() >= asyncRecoveryDeadlineAtMs!) {
+                    throw asyncRecoveryWaitTimeoutError();
+                  }
+                  // This is continuation of already accepted work. Keep the
+                  // original body/key and let the route attach its saved job.
+                  await waitForToolRetry(
+                    Math.min(1_000, asyncRecoveryDeadlineAtMs! - Date.now()),
+                    false,
+                  );
+                  continue;
+                }
+              }
               const developerTunnelOrigin502 =
                 isDeeplineDeveloperTunnelOrigin502({
                   url,
@@ -19487,7 +20321,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   status: response.status,
                   bodyText: text,
                   transientHttpRetrySafe:
-                    retrySafeTransientHttp || fixtureReplaySafe,
+                    retrySafeTransientHttp ||
+                    fixtureReplaySafe ||
+                    Boolean(asyncExecutionRecovery),
                   executionFenced: usesDurableInvocationFence,
                 });
               const failure =
@@ -19501,7 +20337,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   retryAfterHeader: response.headers.get('retry-after'),
                   retryAtMs: parseToolExecuteExactProviderRetryAtMs(response),
                   transientHttpRetrySafe:
-                    retrySafeTransientHttp || fixtureReplaySafe,
+                    retrySafeTransientHttp ||
+                    fixtureReplaySafe ||
+                    Boolean(asyncExecutionRecovery),
                   executionFenced: usesDurableInvocationFence,
                   ...(providerCallElapsedMs !== null
                     ? { providerLatencyMs: providerCallElapsedMs }
@@ -19643,6 +20481,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 (failure.knownNotDispatched ||
                   failure.reason === 'gateway_invocation_in_progress' ||
                   ambiguousTransportReplayAllowed ||
+                  Boolean(asyncExecutionRecovery) ||
                   retrySafeTransientHttp ||
                   fixtureReplaySafe ||
                   // An explicit provider-owned 429 is a rejected operation,
@@ -19659,7 +20498,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 // prior-attempt sweep see an intentionally absent receipt.
                 if (
                   failure.reason !== 'gateway_invocation_in_progress' &&
-                  !shedKnownNotDispatched
+                  !shedKnownNotDispatched &&
+                  (!asyncExecutionRecovery ||
+                    failure.backpressureDelayMs !== null)
                 ) {
                   const previousInvocationAttempt = invocationAttempt;
                   if (failure.backpressureDelayMs !== null) {