deepline 0.3.141 → 0.3.143

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

@@ -2712,6 +2712,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   private toolDispatchGroupRoundTripEwmaMs: number | null = null;
   private readonly toolDispatcherWakeWaiters = new Set<() => void>();
   private toolDispatcherFailure: unknown | null = null;
+  /** Active provider HTTP attempts in this Play execution, grouped by provider. */
+  private readonly inFlightProviderRequests = new Map<string, number>();
   /**
    * Deepline's own zero-credit denial is run-fatal. Keep it independently of
    * customer control flow so a broad `try/catch` cannot turn it into a
@@ -8457,6 +8459,52 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         : derivePlayRowIdentity(stableInputRow(row), resolvedTableNamespace);
     };
 
+    // A terminal write can be durably accepted into this run's history while
+    // losing the mutable latest-view race to newer intent. That outcome must
+    // not leak into the dataset returned by this execution. A later same-run
+    // reconciliation can explicitly recover a key; only that positive fact
+    // makes it visible again.
+    const staleCompletionKeys = new Set<string>();
+    const staleCompletedKeys = new Set<string>();
+    const staleFailedKeys = new Set<string>();
+    const recoveredStaleCompletionKeys = new Set<string>();
+    const observeMapWriteResult = (
+      writeResult: unknown,
+      writtenRows: readonly PersistableMapRow[] = [],
+    ): void => {
+      if (!writeResult || typeof writeResult !== 'object') return;
+      const result = writeResult as {
+        staleDroppedKeys?: unknown;
+        recoveredStaleKeys?: unknown;
+      };
+      const rowsByKey = new Map(writtenRows.map((row) => [row.key, row]));
+      if (Array.isArray(result.staleDroppedKeys)) {
+        for (const key of result.staleDroppedKeys) {
+          if (typeof key !== 'string' || !key) continue;
+          staleCompletionKeys.add(key);
+          if (rowsByKey.get(key)?.status === 'failed') {
+            staleFailedKeys.add(key);
+            staleCompletedKeys.delete(key);
+          } else {
+            staleCompletedKeys.add(key);
+            staleFailedKeys.delete(key);
+          }
+        }
+      }
+      if (Array.isArray(result.recoveredStaleKeys)) {
+        for (const key of result.recoveredStaleKeys) {
+          if (typeof key !== 'string' || !key) continue;
+          recoveredStaleCompletionKeys.add(key);
+          staleCompletionKeys.delete(key);
+          staleCompletedKeys.delete(key);
+          staleFailedKeys.delete(key);
+        }
+      }
+    };
+    const isVisibleTerminalRow = (row: PersistableMapRow): boolean =>
+      !staleCompletionKeys.has(row.key) ||
+      recoveredStaleCompletionKeys.has(row.key);
+
     // Identity for SEED rows (pre-execution raw inputs), matching the server's
     // own derivation in startRuntimeSheetDataset: hash the FULL cleaned input
     // row, output-named columns INCLUDED. Two distinct input rows that differ
@@ -8604,6 +8652,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               ),
               staticPipeline: this.currentStaticPipeline ?? null,
             });
+            observeMapWriteResult(writeResult, chunk);
             const supersededKeys =
               typeof writeResult === 'object' && writeResult !== null
                 ? (writeResult.supersededKeys ?? [])
@@ -8831,9 +8880,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           totalRows: totalInputCount,
           completedRowKeys: [],
           pendingRowKeys: execution.rowFeed ? [] : [...execution.rowKeys],
-          completedRowsCount: Math.max(0, processedCount - failedCount),
+          completedRowsCount: Math.max(
+            0,
+            processedCount - failedCount - staleCompletedKeys.size,
+          ),
           pendingRowsCount: Math.max(0, totalInputCount - processedCount),
-          failedRowsCount: failedCount,
+          failedRowsCount: Math.max(0, failedCount - staleFailedKeys.size),
           startedAt:
             this.checkpoint.mapFrames?.[mapScope.mapInvocationId]?.startedAt ??
             Date.now(),
@@ -8857,8 +8909,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               executionRowKeys: execution.rowKeys,
               executionRowIndexes: execution.rowIndexes,
               progressCompletedOffset: () =>
-                Math.max(0, processedCount - failedCount),
-              progressFailedOffset: () => failedCount,
+                Math.max(
+                  0,
+                  processedCount - failedCount - staleCompletedKeys.size,
+                ),
+              progressFailedOffset: () =>
+                Math.max(0, failedCount - staleFailedKeys.size),
               progressTotalRows: () => totalInputCount,
               rowFeed: execution.rowFeed,
               retainedRowsMemoryBudgetBytes:
@@ -8885,9 +8941,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         }
 
         await incrementalPersistence.flush();
+        const visibleCompletedRows =
+          mapResult.completedRows.filter(isVisibleTerminalRow);
+        const visibleFailedRows =
+          mapResult.failedRows.filter(isVisibleTerminalRow);
         const mapCellMeta = this.activeMapCellMeta;
         const persistRows: PersistableMapRow[] = [];
-        for (const row of mapResult.completedRows) {
+        for (const row of visibleCompletedRows) {
           if (incrementalPersistence.isPersisted(row)) continue;
           const meta = mapCellMeta?.get(row.key);
           persistRows.push(
@@ -8903,7 +8963,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           );
         }
         persistRows.push(
-          ...mapResult.failedRows.filter(
+          ...visibleFailedRows.filter(
             (row) => !incrementalPersistence.isPersisted(row),
           ),
         );
@@ -8919,7 +8979,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             'the current execution page exceeded the in-memory result budget',
           );
         }
-        for (const row of mapResult.completedRows) {
+        for (const row of visibleCompletedRows) {
           const materializedRow = this.toMaterializedOutputRow(row.data);
           if (
             immediateMaterializedCacheEnabled &&
@@ -9060,6 +9120,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         }
       }
 
+      successfulCount = Math.max(0, successfulCount - staleCompletedKeys.size);
+      failedCount = Math.max(0, failedCount - staleFailedKeys.size);
+
       // Isolated failures are a partial result only when at least one admitted
       // row completed. A fully failed admission run is systemic: preserve the
       // failed sheet rows for recovery, but fail the enclosing play loudly.
@@ -9110,7 +9173,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         totalRows: totalInputCount,
         completedRowKeys: [],
         pendingRowKeys: [],
-        completedRowsCount: Math.max(0, processedCount - failedCount),
+        completedRowsCount: Math.max(
+          0,
+          processedCount -
+            failedCount -
+            staleFailedKeys.size -
+            staleCompletedKeys.size,
+        ),
         pendingRowsCount: 0,
         failedRowsCount: failedCount,
         startedAt:
@@ -9124,7 +9193,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         mapNodeId: mapScope.mapNodeId ?? null,
         logicalNamespace: mapScope.logicalNamespace,
         artifactTableNamespace: resolvedTableNamespace,
-        completedRows: Math.max(0, processedCount - failedCount),
+        completedRows: Math.max(
+          0,
+          processedCount -
+            failedCount -
+            staleFailedKeys.size -
+            staleCompletedKeys.size,
+        ),
         failedRows: failedCount,
         totalRows: totalInputCount,
         at: Date.now(),
@@ -9500,7 +9575,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
     this.beginActiveMapCellMeta();
     this.beginActiveMapCheckpointUpdates();
-    const staleCompletionKeys = new Set<string>();
     const persistMapRows = async (rows: PersistableMapRow[]) => {
       if (!this.#options.onMapRowsCompleted || rows.length === 0) {
         return;
@@ -9529,15 +9603,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             ),
             staticPipeline: this.currentStaticPipeline ?? null,
           });
-          if (writeResult) {
-            const recoveredStaleKeys = new Set(
-              writeResult.recoveredStaleKeys ?? [],
-            );
-            for (const key of writeResult.staleDroppedKeys ?? []) {
-              if (recoveredStaleKeys.has(key)) continue;
-              staleCompletionKeys.add(key);
-            }
-          }
+          observeMapWriteResult(writeResult, chunk);
           this.resourceGovernor.observe({
             sheetFlushBytes: chunkBytes,
             sheetFlushLatencyMs: Date.now() - flushStartedAt,
@@ -9623,23 +9689,31 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         this.clearActiveMapCheckpointUpdates();
       }
     }
+    const visibleCompletedRows =
+      mapResult.completedRows.filter(isVisibleTerminalRow);
+    const visibleFailedRows = mapResult.failedRows.filter(isVisibleTerminalRow);
     const resultsByKey = new Map<string, Record<string, unknown>>();
-    for (const row of mapResult.completedRows) {
+    for (const row of visibleCompletedRows) {
       if (row.key) resultsByKey.set(row.key, row.data);
     }
     const failedRowKeys = new Set(
-      mapResult.failedRows.map((row) => row.key).filter(Boolean),
+      visibleFailedRows.map((row) => row.key).filter(Boolean),
     );
-    const directCompletedResults = mapResult.completedRows.map((row) =>
+    const directCompletedResults = visibleCompletedRows.map((row) =>
       this.toPublicOutputRow(row.data),
     );
     let results =
-      mapResult.failedRows.length === 0 &&
+      visibleFailedRows.length === 0 &&
       directCompletedResults.length === rawItems.length
         ? directCompletedResults
         : rawItems.flatMap((rawItem, index) => {
             const rowKey = rowIdentity(rawItem, index);
-            if (rowKey && failedRowKeys.has(rowKey)) {
+            if (
+              rowKey &&
+              (failedRowKeys.has(rowKey) ||
+                (staleCompletionKeys.has(rowKey) &&
+                  !recoveredStaleCompletionKeys.has(rowKey)))
+            ) {
               return [];
             }
             return [
@@ -9652,11 +9726,11 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     // Persist executed rows to the tenant runtime sheet — the sheet is the
     // source of truth, not this in-memory results array. Chunked by rows AND
     // bytes so large cells (scraped pages) never produce oversized writes.
-    if (resultsByKey.size > 0 || mapResult.failedRows.length > 0) {
+    if (resultsByKey.size > 0 || visibleFailedRows.length > 0) {
       await incrementalPersistence?.flush();
       const mapCellMeta = this.activeMapCellMeta;
       const persistRows: PersistableMapRow[] = [];
-      for (const row of mapResult.completedRows) {
+      for (const row of visibleCompletedRows) {
         if (incrementalPersistence?.isPersisted(row)) continue;
         const rowKey = row.key;
         const meta = mapCellMeta?.get(rowKey);
@@ -9672,7 +9746,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         );
       }
       persistRows.push(
-        ...mapResult.failedRows.filter(
+        ...visibleFailedRows.filter(
           (row) => !incrementalPersistence?.isPersisted(row),
         ),
       );
@@ -9687,18 +9761,11 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     this.clearActiveMapCellMeta();
     this.clearActiveMapCheckpointUpdates();
 
-    if (staleCompletionKeys.size > 0) {
-      results = results.filter((row, index) => {
-        const key = rowIdentity(row, itemOriginalIndexes[index] ?? index);
-        return !staleCompletionKeys.has(key);
-      });
-    }
-
     const durableCompletedRows = Math.max(
       0,
-      reusedCount + mapResult.completedRows.length - staleCompletionKeys.size,
+      reusedCount + visibleCompletedRows.length,
     );
-    const durableFailedRows = mapResult.failedRows.length;
+    const durableFailedRows = visibleFailedRows.length;
     const terminalFrame = this.checkpoint.mapFrames?.[mapScope.mapInvocationId];
     if (terminalFrame) {
       this.setMapFrame({
@@ -9730,7 +9797,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       at: Date.now(),
     });
 
-    if (this.#options.onMapRowsCompleted && staleCompletionKeys.size === 0) {
+    if (this.#options.onMapRowsCompleted) {
       const finalizationPageReader = createRuntimeSheetDatasetPageReader({
         context: {
           baseUrl: this.#options.baseUrl!,
@@ -9748,9 +9815,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         mapName: normalizedMapNamespace,
         tableNamespace: resolvedTableNamespace,
         runId: this.#options.runId,
-        expectedRows: totalInputCount,
+        expectedRows: Math.max(0, totalInputCount - staleCompletionKeys.size),
         currentRows: results,
-        failedRowCount: mapResult.failedRows.length,
+        failedRowCount: visibleFailedRows.length,
         log: (line) => this.runtimeLog(line),
         readPersistedRows: async (readInput) => {
           if (
@@ -9870,7 +9937,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         reused: reusedCount,
         skipped: reusedCount,
         pending: 0,
-        failed: mapResult.failedRows.length,
+        failed: visibleFailedRows.length,
         ...(duplicateReuseCount > 0
           ? { duplicates: { exact: duplicateReuseCount } }
           : {}),
@@ -12350,6 +12417,31 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     );
   }
 
+  private beginProviderRequest(provider: string): {
+    inFlightCount: () => number;
+    release: () => void;
+  } {
+    const providerKey = provider.trim().toLowerCase() || 'unknown';
+    this.inFlightProviderRequests.set(
+      providerKey,
+      (this.inFlightProviderRequests.get(providerKey) ?? 0) + 1,
+    );
+    let released = false;
+    return {
+      inFlightCount: () => this.inFlightProviderRequests.get(providerKey) ?? 0,
+      release: () => {
+        if (released) return;
+        released = true;
+        const remaining = this.inFlightProviderRequests.get(providerKey) ?? 0;
+        if (remaining <= 1) {
+          this.inFlightProviderRequests.delete(providerKey);
+        } else {
+          this.inFlightProviderRequests.set(providerKey, remaining - 1);
+        }
+      },
+    };
+  }
+
   private async executeTool(
     key: string,
     toolId: string,
@@ -12408,6 +12500,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       (await this.resolveToolAuthScopeDigest(toolId))?.trim() ?? null;
     const eventWaitHandler =
       (await this.#options.getIntegrationEventWaitHandler?.(toolId)) ?? null;
+    const explicitForce =
+      options?.force === true ||
+      toolExecutionOverrides.getStore()?.force === true;
     const cacheableToolResult =
       !eventWaitHandler &&
       !isQueryResultDatasetReadRequest(toolId, input) &&
@@ -12462,6 +12557,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           toolId,
           input,
           eventWaitHandler,
+          explicitForce,
         );
       }
       if (toolId === 'run_javascript') {
@@ -13226,6 +13322,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     toolId: string,
     input: Record<string, unknown>,
     handler: IntegrationEventWaitHandler,
+    force = false,
   ): Promise<unknown> {
     this.assertInlineChildContract('suspending_child');
     if (!this.#options.durableBoundaries) {
@@ -13295,6 +13392,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               ...(existing.messageRef
                 ? { messageRef: existing.messageRef }
                 : {}),
+              ...(existing.requestKey
+                ? { requestKey: existing.requestKey }
+                : {}),
+              ...(existing.interactionId
+                ? { interactionId: existing.interactionId }
+                : {}),
               ...(timeoutPolicy ? { timeoutPolicy } : {}),
             },
           });
@@ -13344,8 +13447,52 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       payload: input,
       context: eventContext,
       boundary: preparedBoundary,
+      ...(force ? { force: true } : {}),
     });
 
+    if (boundary.resolvedOutput) {
+      this.checkpoint.resolvedBoundaries = {
+        ...(this.checkpoint.resolvedBoundaries ?? {}),
+        [boundary.boundaryId]: {
+          kind: 'integration_event',
+          eventKey: boundary.eventKey,
+          timeoutMs: boundary.timeoutMs,
+          provider: boundary.provider,
+          toolId: boundary.toolId,
+          output: boundary.resolvedOutput,
+          ...(boundary.timeoutPolicy
+            ? { timeoutPolicy: boundary.timeoutPolicy }
+            : {}),
+          ...(rowScope
+            ? {
+                scope: {
+                  type: 'map_row' as const,
+                  tableNamespace: rowScope.tableNamespace,
+                  rowKey: rowScope.rowKey,
+                  rowIndex: rowScope.rowId,
+                  fieldName: rowScope.fieldName,
+                },
+              }
+            : { scope: { type: 'workflow' as const } }),
+          ...(boundary.messageRef ? { messageRef: boundary.messageRef } : {}),
+          ...(boundary.requestKey ? { requestKey: boundary.requestKey } : {}),
+          ...(boundary.interactionId
+            ? { interactionId: boundary.interactionId }
+            : {}),
+        },
+      };
+      this.#options.onBatchComplete?.(this.checkpoint);
+      return await this.wrapToolExecutionResult({
+        toolId,
+        status: 'completed',
+        result: boundary.resolvedOutput,
+        execution: toolExecutionMetadataForOutcome({
+          kind: 'checkpoint',
+          cacheKey: `integration_event:${boundary.boundaryId}`,
+        }),
+      });
+    }
+
     this.runtimeLog(
       `Armed ${handler.provider} integration event wait: ${boundary.eventKey}`,
     );
@@ -13357,6 +13504,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         timeoutMs: boundary.timeoutMs,
         provider: boundary.provider,
         toolId: boundary.toolId,
+        ...(boundary.requestKey ? { requestKey: boundary.requestKey } : {}),
+        ...(boundary.interactionId
+          ? { interactionId: boundary.interactionId }
+          : {}),
         ...(boundary.timeoutPolicy
           ? { timeoutPolicy: boundary.timeoutPolicy }
           : {}),
@@ -13954,7 +14105,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           ? `${rowStore.mapScope.mapInvocationId}:${rowStore.rowKey ?? rowStore.rowId}`
           : `row:${rowStore.rowKey ?? rowStore.rowId}`;
         const scopedIndexKey = `${this.currentExecutionScope.receipt.namespace}:${rowScope}`;
-        const scopedIndex = this.sleepBoundaryIndexByScope.get(scopedIndexKey) ?? 0;
+        const scopedIndex =
+          this.sleepBoundaryIndexByScope.get(scopedIndexKey) ?? 0;
         this.sleepBoundaryIndexByScope.set(scopedIndexKey, scopedIndex + 1);
         const scopedBoundaryId = this.durableBoundaryId(
           `sleep-${stableDigest(`${rowScope}:${scopedIndex}`)}-${delayMs}`,
@@ -14409,9 +14561,22 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         this.runtimeLog(
           `ctx.step(${normalizedKey}): recovered result from checkpoint`,
         );
+        // The step callback is not evaluated on replay, so any sleeps that it
+        // contained would otherwise disappear from the positional sleep
+        // cursor. Preserve the authored boundary sequence before evaluating
+        // the next sibling operation. This is deliberately run-local state;
+        // it is not a cross-run sleep cache or an input-derived identity.
+        if (
+          Number.isSafeInteger(existing.sleepCount) &&
+          existing.sleepCount !== undefined &&
+          existing.sleepCount > 0
+        ) {
+          this.sleepBoundaryIndex += existing.sleepCount;
+        }
         return existing.output as T;
       }
 
+      const sleepBoundaryIndexBefore = this.sleepBoundaryIndex;
       const output = await run();
       assertJsonSerializableStepOutput(normalizedKey, output);
       // A caught durable suspension is still the invocation's outcome. Never
@@ -14424,6 +14589,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           kind: 'step',
           stepId: normalizedKey,
           output,
+          sleepCount: this.sleepBoundaryIndex - sleepBoundaryIndexBefore,
           completedAt: Date.now(),
         },
       };
@@ -18077,6 +18243,11 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             let providerCallStartedAt: number | null = null;
             let providerCallElapsedMs: number | null = null;
             let integrationFetchStartedAt: number | null = null;
+            let providerRequestsInFlightAt429: number | null = null;
+            let activeProviderRequest: {
+              inFlightCount: () => number;
+              release: () => void;
+            } | null = null;
             let fetchDispatched = false;
             // A provider 429 must be reported while its server-minted
             // admission lease is still live. Keep its parsed outcome here so
@@ -18342,6 +18513,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                           providerCallStartedAt =
                             dispatchedProviderCallStartedAt;
                           fetchDispatched = true;
+                          activeProviderRequest =
+                            this.beginProviderRequest(provider);
                           const dispatchedResponse = await fetch(url, {
                             method: 'POST',
                             signal: abortController?.signal,
@@ -18386,6 +18559,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                           // headers arrive; decoded body data stays scoped until
                           // it has been read and verified below.
                           response = dispatchedResponse;
+                          if (dispatchedResponse.status === 429) {
+                            providerRequestsInFlightAt429 =
+                              activeProviderRequest?.inFlightCount() ?? null;
+                          }
                           const dispatchedFetchToHeadersMs =
                             Date.now() - fetchedAt;
                           // The response writer owns these named wall times.
@@ -18533,6 +18710,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                               }),
                             };
                           }
+                          activeProviderRequest?.release();
+                          activeProviderRequest = null;
                           return {
                             response: dispatchedResponse,
                             responseData: dispatchedResponseData,
@@ -18599,6 +18778,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     } catch (error) {
                       // `request()` can fail while waiting for its transport
                       // lease, before its beforeRelease callback runs.
+                      activeProviderRequest?.release();
+                      activeProviderRequest = null;
                       releaseProviderExecution();
                       throw error;
                     }
@@ -18657,6 +18838,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               }
               if (error instanceof ProviderExhaustedError) {
                 const retryAtMs = Date.parse(error.retryAt);
+                const providerFailure =
+                  error.cause instanceof ToolExecutionError
+                    ? error.cause
+                    : null;
                 throw createToolHttpError(
                   toolErrorSchemaVersion,
                   error.message,
@@ -18678,6 +18863,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                       : null,
                     networkKind: null,
                     networkScope: null,
+                    ...(providerFailure?.publicDetails
+                      ? { publicDetails: providerFailure.publicDetails }
+                      : {}),
                   },
                 );
               }
@@ -18852,6 +19040,45 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     ? { providerLatencyMs: providerCallElapsedMs }
                     : {}),
                 });
+              let surfacedError = failure.error;
+              if (
+                response.status === 429 &&
+                providerRequestsInFlightAt429 !== null &&
+                failure.error instanceof ToolExecutionError &&
+                failure.error.origin === 'provider'
+              ) {
+                const providerFailure = failure.error as typeof failure.error &
+                  ToolExecutionError;
+                surfacedError = createToolHttpError(
+                  toolErrorSchemaVersion,
+                  providerFailure.message,
+                  providerFailure.billing,
+                  providerFailure.status,
+                  providerFailure.receiptFailureKind,
+                  {
+                    toolId: providerFailure.toolId,
+                    provider: providerFailure.provider,
+                    operation: providerFailure.operation,
+                    code: providerFailure.code ?? null,
+                    origin: providerFailure.origin,
+                    category: providerFailure.category,
+                    retryable: providerFailure.retryable,
+                    statusCode: providerFailure.statusCode ?? null,
+                    requestId: providerFailure.requestId,
+                    retryAfterMs: providerFailure.retryAfterMs,
+                    networkKind: providerFailure.networkKind,
+                    networkScope: providerFailure.networkScope,
+                    publicDetails: {
+                      ...(providerFailure.publicDetails ?? {}),
+                      inFlightProviderRequestsAt429:
+                        providerRequestsInFlightAt429,
+                      providerConcurrencyScope:
+                        'same_provider_in_play_execution',
+                      includesFailedRequest: true,
+                    },
+                  },
+                );
+              }
               if (failure.reason === 'concurrency_backpressure') {
                 // Our own relay shed. The classifier keeps it out of provider
                 // backpressure (origin is not the provider); count it apart
@@ -18887,7 +19114,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   throw new ProviderExhaustedError({
                     provider,
                     retryAtMs: Date.now() + failure.backpressureDelayMs,
-                    cause: failure.error,
+                    cause: surfacedError,
                   });
                 }
               }
@@ -18991,11 +19218,11 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               // or operator sees; carry the identifiers that locate the
               // upstream request without the debug transport trace.
               this.runtimeLog(
-                `${failure.error.message} (request_id=${deeplineRequestId ?? 'none'} ` +
+                `${surfacedError.message} (request_id=${deeplineRequestId ?? 'none'} ` +
                   `gateway=${transportGatewayOriginForDiagnostic(url)} attempt=${httpFailureAttempt})`,
                 { level: 'error' },
               );
-              throw failure.error;
+              throw surfacedError;
             }
 
             if (!responseData) {

package/dist/bundling-sources/shared_libs/play-runtime/ctx-types.ts

@@ -675,6 +675,11 @@ export type IntegrationEventWaitBoundary = {
     channel: string;
     ts: string;
   };
+  /** Provider identity used to finalize a durable wait after replay. */
+  requestKey?: string;
+  interactionId?: string;
+  /** A previously completed identical request can resolve without parking. */
+  resolvedOutput?: Record<string, unknown>;
   /**
    * Optional control-plane timeout behavior. Missing preserves the legacy
    * "return the timed_out result" replay behavior for older app deployments.
@@ -703,6 +708,7 @@ export type IntegrationEventWaitHandler = {
     payload: Record<string, unknown>;
     context: IntegrationEventWaitRuntimeContext;
     boundary: IntegrationEventWaitBoundary;
+    force?: boolean;
   }) => Promise<IntegrationEventWaitBoundary>;
   /**
    * Runs during the resumed execution only when this boundary reached its
@@ -884,6 +890,10 @@ export interface ContextOptions {
     staticPipeline?: PlayStaticPipeline | null;
   }) => Promise<void | {
     updated: number;
+    /**
+     * Row-level latest-view conflicts. These rows are omitted from this map's
+     * returned dataset, while the Play and independent rows continue.
+     */
     staleDroppedKeys?: string[];
     /**
      * Keys initially fenced by a terminal write but verified by the
@@ -892,12 +902,10 @@ export interface ContextOptions {
      */
     recoveredStaleKeys?: string[];
     /**
-     * Stale keys that prove this attempt no longer owns the sheet: the rows
-     * carry a different write version than the one this attempt admitted them
-     * under. A handler that returns any (instead of throwing
-     * `RuntimeSheetAttemptSupersededError` itself) makes the Context throw it:
-     * the map fails and the persistence latch trips, so no further provider
-     * call is spent on rows that can never be persisted.
+     * Legacy attempt-wide stop signal. Ordinary row-level latest-view
+     * conflicts must use staleDroppedKeys; returning supersededKeys explicitly
+     * means this attempt cannot continue and makes the Context throw
+     * RuntimeSheetAttemptSupersededError to trip the persistence latch.
      */
     supersededKeys?: string[];
   }>;
@@ -1174,6 +1182,8 @@ export interface PlayCheckpoint {
           channel: string;
           ts: string;
         };
+        requestKey?: string;
+        interactionId?: string;
         /**
          * Control-plane timeout behavior captured when the wait was armed.
          * Missing fields preserve legacy checkpoint replay behavior.
@@ -1193,6 +1203,15 @@ export interface PlayCheckpoint {
         kind: 'step';
         stepId: string;
         output?: unknown;
+        /**
+         * Number of authored ctx.sleep calls evaluated inside this step.
+         *
+         * A replay can recover the step output without executing its callback.
+         * Keeping this count lets the surrounding execution advance its
+         * run-local sleep cursor, so a later sleep cannot accidentally reuse a
+         * nested sleep boundary that was hidden by the cached step.
+         */
+        sleepCount?: number;
         completedAt?: number;
       }
   >;