deepline 0.1.10 → 0.1.12

package/dist/repo/shared_libs/play-runtime/context.ts

@@ -2,9 +2,9 @@
  * PlayContextImpl — the cloud execution engine.
  *
  * Batching model:
- * 1. ctx.map("table_key", rows, { key: "row_id" }).step("field", resolver) starts all row field resolvers concurrently
+ * 1. ctx.map("table_key", rows, { field: resolver }) starts all row field resolvers concurrently
  * 2. ctx.waterfall() calls inside field resolvers QUEUE requests (don't execute)
- * 3. ctx.tools.execute({ id, tool, input }) calls inside field resolvers also QUEUE
+ * 3. ctx.tools.execute() calls inside field resolvers also QUEUE
  * 4. After all rows have queued, executeBatchedWaterfalls() runs provider-by-provider
  * 5. Each provider batch = real HTTP call to /api/v2/integrations/{toolId}/execute
  * 6. Results resolve suspended row promises, rows complete
@@ -26,7 +26,6 @@ import {
   resolveWaterfallToolId,
 } from './batch-runtime';
 import { PlayRateLimitScheduler } from '@shared_libs/plays/rate-limit-scheduler';
-import { normalizePlayToolResult } from './result-normalization';
 import {
   cloneToolExecuteResultWithExecution,
   createToolExecuteResult,
@@ -38,19 +37,12 @@ import { sqlSafePlayColumnName } from '@shared_libs/plays/static-pipeline';
 import { createRuntimeDatasetId } from './dataset-id';
 import {
   derivePlayRowIdentity,
+  derivePlayRowIdentityFromKey,
   MAP_KEY_NAMESPACE_MAX_LENGTH,
   normalizeTableNamespace,
   resolveStaleMapTableNamespace,
 } from '@shared_libs/plays/row-identity';
-import {
-  assertUniqueExplicitMapKeys,
-  createExplicitMapKeyResolver,
-  deriveMapRowIdentity,
-  MapRowIdentity,
-} from './map-row-identity';
-import { MapExecutionFrameStore } from './map-execution-frame';
-import { PlayProgressEmitter } from './progress-emitter';
-import { WaterfallReplayStore } from './waterfall-replay';
+import { cloneCsvAliasedRow, stripCsvProjectedFields } from './csv-rename';
 import { setSpanAttributes, withActiveSpan } from './tracing';
 import { DISALLOWED_RUN_JAVASCRIPT_TOOL_MESSAGE } from './runtime-constraints';
 import {
@@ -64,12 +56,9 @@ import type {
   WaterfallRequest,
   WaterfallOptions,
   InlineWaterfallSpec,
-  MapDefinitionOptions,
   MapOptions,
-  MapRunOptions,
   ToolCallRequest,
   ToolBatchResult,
-  ToolExecutionRequest,
   ContextOptions,
   PlayCallOptions,
   PlayCheckpoint,
@@ -78,6 +67,7 @@ import type {
   PlayRowUpdate,
   MapFieldDefinition,
   MapFieldResolver,
+  ToolCallOptions,
   PlayExecutionGovernanceLimits,
   PlayExecutionGovernanceState,
   ResolvedPlayExecution,
@@ -111,10 +101,6 @@ const PURE_JS_HEARTBEAT_ROW_INTERVAL = 250;
 const TOOL_RETRY_AFTER_FALLBACK_MS = 1_000;
 const TOOL_RETRY_HEARTBEAT_INTERVAL_MS = 30_000;
 const TOOL_TRANSIENT_HTTP_MAX_ATTEMPTS = 3;
-const TRANSIENT_HTTP_RETRY_SAFE_TOOL_IDS = new Set([
-  'test_company_search',
-  'test_transient_500',
-]);
 const EXECUTE_TOOL_METADATA_HEADER = 'x-deepline-include-tool-metadata';
 const IN_MEMORY_STEP_RESULT_PREVIEW_LIMIT = 25;
 const WATERFALL_ROW_MATCH_LOG_SAMPLE_LIMIT = 10;
@@ -169,16 +155,6 @@ function isRuntimeConditionalStepResolver(
   );
 }
 
-function isMapDefinitionOptions(
-  value: unknown,
-): value is Omit<MapOptions, 'description'> {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    return false;
-  }
-  const keys = Object.keys(value);
-  return keys.every((key) => key === 'key' || key === 'staleAfterSeconds');
-}
-
 class RuntimeMapBuilder<T extends Record<string, unknown>> {
   private readonly program: RuntimeStepProgram = {
     kind: 'steps',
@@ -189,7 +165,6 @@ class RuntimeMapBuilder<T extends Record<string, unknown>> {
     private readonly ctx: PlayContextImpl,
     private readonly key: string,
     private readonly items: PlayDatasetInput<T>,
-    private readonly mapOptions?: MapDefinitionOptions<T>,
   ) {}
 
   step(name: string, resolver: RuntimeStepProgramStep['resolver']): this {
@@ -202,17 +177,13 @@ class RuntimeMapBuilder<T extends Record<string, unknown>> {
     return this;
   }
 
-  run(options?: MapRunOptions): Promise<PlayDataset<Record<string, unknown>>> {
-    if (
-      options &&
-      Object.keys(options).some((optionKey) => optionKey !== 'description')
-    ) {
-      throw new Error('ctx.map(...).run() only accepts description.');
-    }
-    return this.ctx.runStepProgramMap(this.key, this.items, this.program, {
-      ...this.mapOptions,
-      ...options,
-    } as MapOptions<T>);
+  run(options?: MapOptions<T>): Promise<PlayDataset<Record<string, unknown>>> {
+    return this.ctx.runStepProgramMap(
+      this.key,
+      this.items,
+      this.program,
+      options,
+    );
   }
 }
 
@@ -258,17 +229,6 @@ function parseRetryAfterMs(header: string | null): number {
   return TOOL_RETRY_AFTER_FALLBACK_MS;
 }
 
-function isRetryableTransientToolHttpStatus(
-  toolId: string,
-  status: number,
-): boolean {
-  return (
-    status >= 500 &&
-    status < 600 &&
-    TRANSIENT_HTTP_RETRY_SAFE_TOOL_IDS.has(toolId)
-  );
-}
-
 function parseJsonOrNull(bodyText: string): unknown | null {
   if (!bodyText.trim()) return null;
   try {
@@ -302,22 +262,18 @@ function parseExecuteToolMetadata(
   const readGetters = (value: unknown): Record<string, readonly string[]> => {
     if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
     return Object.fromEntries(
-      Object.entries(value as Record<string, unknown>).flatMap(
-        ([key, paths]) => {
-          if (!Array.isArray(paths)) return [];
-          const normalized = paths.filter(
-            (path): path is string =>
-              typeof path === 'string' && path.trim().length > 0,
-          );
-          return normalized.length > 0 ? [[key, normalized]] : [];
-        },
-      ),
+      Object.entries(value as Record<string, unknown>).flatMap(([key, paths]) => {
+        if (!Array.isArray(paths)) return [];
+        const normalized = paths.filter(
+          (path): path is string => typeof path === 'string' && path.trim().length > 0,
+        );
+        return normalized.length > 0 ? [[key, normalized]] : [];
+      }),
     );
   };
   const listExtractorPaths = Array.isArray(record.listExtractorPaths)
     ? record.listExtractorPaths.filter(
-        (path): path is string =>
-          typeof path === 'string' && path.trim().length > 0,
+        (path): path is string => typeof path === 'string' && path.trim().length > 0,
       )
     : [];
   return {
@@ -359,6 +315,14 @@ function emptyCheckpoint(): PlayCheckpoint {
   };
 }
 
+function cloneMapFrame(frame: MapExecutionFrame): MapExecutionFrame {
+  return {
+    ...frame,
+    completedRowKeys: [...frame.completedRowKeys],
+    pendingRowKeys: [...frame.pendingRowKeys],
+  };
+}
+
 function createDefaultGovernanceState(
   options: ContextOptions,
 ): PlayExecutionGovernanceState {
@@ -482,7 +446,7 @@ export class PlayContextImpl {
   private resolvers = new Map<string, (value: unknown) => void>();
   private waterfallQueue = new Map<string, WaterfallRequest[]>();
   private toolCallQueue: ToolCallRequest[] = [];
-  private toolCallResolvers = new Map<string, Array<(value: unknown) => void>>();
+  private toolCallResolvers = new Map<string, (value: unknown) => void>();
   private options: ContextOptions;
   private logBuffer: string[] = [];
   private checkpoint: PlayCheckpoint;
@@ -503,22 +467,56 @@ export class PlayContextImpl {
   private directToolCallIndex = 0;
   private sleepBoundaryIndex = 0;
   private fetchCallIndex = 0;
+  private mapInvocationIndex = 0;
   private readonly stepCallIndexByKey = new Map<string, number>();
   private readonly waterfallMatchLogCounts = new Map<string, number>();
   private readonly rateLimitScheduler: PlayRateLimitScheduler;
   private readonly governance: PlayExecutionGovernanceState;
-  private readonly mapRowIdentity = new MapRowIdentity();
-  private readonly mapFrames: MapExecutionFrameStore;
-  private readonly progress: PlayProgressEmitter;
-  private readonly waterfallReplay: WaterfallReplayStore;
   readonly tools = {
     execute: <TOutput = unknown>(
-      request: ToolExecutionRequest,
-    ): Promise<TOutput> => this.executeTool(request) as Promise<TOutput>,
+      requestOrKey:
+        | {
+            id: string;
+            tool: string;
+            input: Record<string, unknown>;
+            description?: string;
+          }
+        | string,
+      toolId?: string,
+      input?: Record<string, unknown>,
+      options?: ToolCallOptions,
+    ): Promise<TOutput> => {
+      if (typeof requestOrKey === 'object') {
+        return this.executeTool(
+          requestOrKey.id,
+          requestOrKey.tool,
+          requestOrKey.input,
+          requestOrKey.description
+            ? { description: requestOrKey.description }
+            : undefined,
+        ) as Promise<TOutput>;
+      }
+      if (!toolId || !input) {
+        throw new Error(
+          'ctx.tools.execute(key, toolId, input) requires a tool ID and input.',
+        );
+      }
+      return this.executeTool(
+        requestOrKey,
+        toolId,
+        input,
+        options,
+      ) as Promise<TOutput>;
+    },
   };
 
-  tool<TOutput = unknown>(request: ToolExecutionRequest): Promise<TOutput> {
-    return this.tools.execute<TOutput>(request);
+  tool<TOutput = unknown>(
+    key: string,
+    toolId: string,
+    input: Record<string, unknown>,
+    options?: ToolCallOptions,
+  ): Promise<TOutput> {
+    return this.tools.execute<TOutput>(key, toolId, input, options);
   }
 
   constructor(options: ContextOptions) {
@@ -527,16 +525,6 @@ export class PlayContextImpl {
       getQueueHints: options.getToolQueueHints,
     });
     this.checkpoint = options.checkpoint ?? emptyCheckpoint();
-    this.mapFrames = new MapExecutionFrameStore(this.checkpoint, (event) =>
-      this.emitExecutionEvent(event),
-    );
-    this.progress = new PlayProgressEmitter(
-      options.onRowUpdate,
-      options.onExecutionEvent,
-      () => rowContext.getStore() ?? null,
-      isInlineWaterfallToolStep,
-    );
-    this.waterfallReplay = new WaterfallReplayStore(this.checkpoint);
     this.governance = {
       ...(options.governance ?? createDefaultGovernanceState(options)),
       inFlightPlayCallsByPlayId:
@@ -557,14 +545,73 @@ export class PlayContextImpl {
     tableNamespace: string | null,
     update: Omit<PlayRowUpdate, 'key'>,
   ): void {
-    this.progress.rowUpdate(key, tableNamespace, update);
+    const rowScope = rowContext.getStore()?.mapScope;
+    if (rowScope && key) {
+      this.emitExecutionEvent({
+        type: 'map.row.updated',
+        mapInvocationId: rowScope.mapInvocationId,
+        mapNodeId: rowScope.mapNodeId ?? null,
+        logicalNamespace: rowScope.logicalNamespace,
+        artifactTableNamespace: rowScope.artifactTableNamespace,
+        rowKey: key,
+        rowStatus: update.status,
+        fieldName: rowContext.getStore()?.fieldName ?? null,
+        stage: update.stage ?? null,
+        provider: update.provider ?? null,
+        at: Date.now(),
+      });
+    }
+    if (!key || !this.options.onRowUpdate) {
+      return;
+    }
+    void this.options.onRowUpdate({
+      ...update,
+      key,
+      tableNamespace,
+    });
   }
 
   private emitExecutionEvent(event: PlayExecutionEvent): void {
     if (!this.options.onExecutionEvent) {
       return;
     }
-    this.progress.executionEvent(event);
+    void this.options.onExecutionEvent(event);
+  }
+
+  private setMapFrame(frame: MapExecutionFrame): void {
+    this.checkpoint.mapFrames = {
+      ...(this.checkpoint.mapFrames ?? {}),
+      [frame.mapInvocationId]: cloneMapFrame(frame),
+    };
+  }
+
+  private createMapExecutionScope(input: {
+    logicalNamespace: string;
+    artifactTableNamespace: string;
+    mapNodeId?: string | null;
+    explicitKey?:
+      | ((row: Record<string, unknown>, index: number) => string)
+      | null;
+  }): MapExecutionScope {
+    const mapInvocationId = `${input.logicalNamespace}:${this.mapInvocationIndex}`;
+    this.mapInvocationIndex += 1;
+    const explicitKey = input.explicitKey ?? null;
+    return {
+      mapInvocationId,
+      mapNodeId: input.mapNodeId ?? null,
+      logicalNamespace: input.logicalNamespace,
+      artifactTableNamespace: input.artifactTableNamespace,
+      rowIdentity: (row, index) =>
+        explicitKey
+          ? derivePlayRowIdentityFromKey(
+              explicitKey(row, index ?? 0),
+              input.artifactTableNamespace,
+            )
+          : derivePlayRowIdentity(
+              stripCsvProjectedFields(row),
+              input.artifactTableNamespace,
+            ),
+    };
   }
 
   private normalizeContextKey(key: string, operation: string): string {
@@ -743,7 +790,35 @@ export class PlayContextImpl {
     reused?: boolean;
     dataPatch?: Record<string, unknown>;
   }): void {
-    this.progress.fieldMetaUpdate(input);
+    if (!input.fieldName) {
+      this.emitScopedRowUpdate(input.key, input.tableNamespace, {
+        rowId: input.rowId,
+        status: input.rowStatus,
+        stage: input.stage ?? null,
+        provider: input.provider ?? null,
+        error: input.error ?? null,
+        dataPatch: input.dataPatch ?? {},
+      });
+      return;
+    }
+
+    this.emitScopedRowUpdate(input.key, input.tableNamespace, {
+      rowId: input.rowId,
+      status: input.rowStatus,
+      stage: input.stage ?? null,
+      provider: input.provider ?? null,
+      error: input.error ?? null,
+      dataPatch: input.dataPatch ?? {},
+      cellMetaPatch: {
+        [input.fieldName]: {
+          status: input.status,
+          stage: input.stage ?? null,
+          provider: input.provider ?? null,
+          error: input.error ?? null,
+          ...(input.reused !== undefined ? { reused: input.reused } : {}),
+        },
+      },
+    });
   }
 
   private emitCellUpdate(input: {
@@ -765,7 +840,23 @@ export class PlayContextImpl {
     error?: string | null;
     value?: unknown;
   }): void {
-    this.progress.cellUpdate(input);
+    this.emitScopedRowUpdate(input.key, input.tableNamespace, {
+      rowId: input.rowId,
+      status: input.rowStatus,
+      stage: input.stage ?? null,
+      provider: input.provider ?? null,
+      error: input.error ?? null,
+      dataPatch:
+        input.value === undefined ? {} : { [input.columnName]: input.value },
+      cellMetaPatch: {
+        [input.columnName]: {
+          status: input.status,
+          stage: input.stage ?? null,
+          provider: input.provider ?? null,
+          error: input.error ?? null,
+        },
+      },
+    });
   }
 
   private emitQueuedInlineWaterfallSteps(
@@ -774,12 +865,18 @@ export class PlayContextImpl {
     tableNamespace: string | null,
     spec: InlineWaterfallSpec,
   ): void {
-    this.progress.queuedInlineWaterfallSteps({
-      rowId,
-      key,
-      tableNamespace,
-      spec,
-    });
+    for (const step of spec.steps) {
+      this.emitCellUpdate({
+        rowId,
+        key,
+        tableNamespace,
+        columnName: sqlSafePlayColumnName(`${spec.id}.${step.id}`),
+        status: 'queued',
+        stage: step.id,
+        provider: isInlineWaterfallToolStep(step) ? step.toolId : 'code',
+        value: null,
+      });
+    }
   }
 
   private isCompletedFieldValue(value: unknown): boolean {
@@ -1038,8 +1135,7 @@ export class PlayContextImpl {
     return createToolExecuteResult({
       status: input.status,
       result: input.result,
-      metadata:
-        input.metadata ?? (await this.resolveToolResultMetadata(input.toolId)),
+      metadata: input.metadata ?? (await this.resolveToolResultMetadata(input.toolId)),
       execution: {
         idempotent: true,
         cached: input.cached,
@@ -1072,11 +1168,9 @@ export class PlayContextImpl {
     });
     this.cacheToolResult(toolId, cacheKey, wrapped);
 
-    const resolvers = this.toolCallResolvers.get(request.callId);
-    if (resolvers) {
-      for (const resolver of resolvers) {
-        resolver(wrapped);
-      }
+    const resolver = this.toolCallResolvers.get(request.callId);
+    if (resolver) {
+      resolver(wrapped);
       this.toolCallResolvers.delete(request.callId);
     }
 
@@ -1124,11 +1218,6 @@ export class PlayContextImpl {
     );
   }
 
-  map<T extends Record<string, unknown>>(
-    key: string,
-    items: PlayDatasetInput<T>,
-    options: MapDefinitionOptions<T>,
-  ): RuntimeMapBuilder<T>;
   map<T extends Record<string, unknown>>(
     key: string,
     items: PlayDatasetInput<T>,
@@ -1145,10 +1234,7 @@ export class PlayContextImpl {
   >(
     key: string,
     items: PlayDatasetInput<T>,
-    input?:
-      | MapFieldDefinition<T, TColumns>
-      | RuntimeStepProgram
-      | MapDefinitionOptions<T>,
+    input?: MapFieldDefinition<T, TColumns> | RuntimeStepProgram,
     options?: MapOptions<T>,
   ): RuntimeMapBuilder<T> | Promise<PlayDataset<Record<string, unknown>>> {
     if (rowContext.getStore()) {
@@ -1158,20 +1244,17 @@ export class PlayContextImpl {
     }
     this.assertNoDuplicateConcurrentMapBackedPlay();
 
-    if (input === undefined || isMapDefinitionOptions(input)) {
-      return new RuntimeMapBuilder(
-        this,
-        key,
-        items,
-        input as MapDefinitionOptions<T> | undefined,
-      );
+    if (input === undefined) {
+      return new RuntimeMapBuilder(this, key, items);
     }
 
     if (isRuntimeStepProgram(input)) {
       return this.runStepProgramMap(key, items, input, options);
     }
 
-    throw new Error('ctx.map() accepts key, rows, and map options only.');
+    throw new Error(
+      'ctx.map(key, rows, fields, options) was removed. Use ctx.map(key, rows).step(...).run(options).',
+    );
   }
 
   async runStepProgramMap<T extends Record<string, unknown>>(
@@ -1213,7 +1296,7 @@ export class PlayContextImpl {
     } catch (error) {
       throw new Error(
         error instanceof Error
-          ? `${error.message} Example: ctx.map(\"${normalizedMapNamespace}\", rows, { key: \"stable_id\", staleAfterSeconds: 86400 }).step("company", row => row.domain).run({ description: "..." }).`
+          ? `${error.message} Example: ctx.map(\"${normalizedMapNamespace}\", rows, { company: ... }, { staleAfterSeconds: 86400 }).`
           : `ctx.map() key must normalize to <= ${MAP_KEY_NAMESPACE_MAX_LENGTH} characters.`,
       );
     }
@@ -1234,23 +1317,66 @@ export class PlayContextImpl {
     let itemsToProcess: Array<Record<string, unknown>> = [];
     let completedItemsByKey: Map<string, Record<string, unknown>> | null = null;
     const mapFieldNames = Object.keys(input);
-    const userKeyFn = options?.key;
-    const explicitKeyResolver = createExplicitMapKeyResolver({
-      mapNamespace: normalizedMapNamespace,
-      fieldNames: mapFieldNames,
-      key: userKeyFn as Parameters<
-        typeof createExplicitMapKeyResolver
-      >[0]['key'],
-    });
+    const stripFieldOutputs = (row: Record<string, unknown>) =>
+      Object.fromEntries(
+        Object.entries(row).filter(
+          ([fieldName]) => !mapFieldNames.includes(fieldName),
+        ),
+      );
+
+    const userKeyOption = options?.key;
+    let explicitKeyResolver:
+      | ((row: Record<string, unknown>, index: number) => string)
+      | null = null;
+    if (userKeyOption !== undefined) {
+      explicitKeyResolver = (row, index) => {
+        const inputRow = stripFieldOutputs(row);
+        const raw =
+          typeof userKeyOption === 'function'
+            ? (
+                userKeyOption as (
+                  row: Record<string, unknown>,
+                  index: number,
+                ) => string | number | readonly unknown[]
+              )(inputRow, index)
+            : Array.isArray(userKeyOption)
+              ? userKeyOption.map((fieldName) => inputRow[fieldName])
+              : inputRow[String(userKeyOption)];
+        const parts = Array.isArray(raw) ? raw : [raw];
+        if (parts.some((part) => part === null || part === undefined)) {
+          throw new Error(
+            `ctx.map("${normalizedMapNamespace}") key returned null or undefined for row ${index}. ` +
+              'Return a non-empty string or number derived from a stable input column (e.g. row.email ?? row.domain).',
+          );
+        }
+        const normalizedParts = parts.map((part) => {
+          if (typeof part === 'number') {
+            return Number.isFinite(part) ? String(part) : '';
+          }
+          return String(part).trim();
+        });
+        if (normalizedParts.some((part) => !part)) {
+          throw new Error(
+            `ctx.map("${normalizedMapNamespace}") key returned an empty value for row ${index}. ` +
+              'Return a non-empty string or finite number derived from a stable input column.',
+          );
+        }
+        return normalizedParts.length === 1
+          ? normalizedParts[0]!
+          : JSON.stringify(normalizedParts);
+      };
+    }
 
     const rowIdentity = (row: Record<string, unknown>, index = 0) =>
-      deriveMapRowIdentity({
-        row,
-        index,
-        artifactTableNamespace: resolvedTableNamespace,
-        fieldNames: mapFieldNames,
-        explicitKey: explicitKeyResolver,
-      });
+      explicitKeyResolver
+        ? derivePlayRowIdentityFromKey(
+            explicitKeyResolver(row, index),
+            resolvedTableNamespace,
+          )
+        : derivePlayRowIdentity(
+            stripCsvProjectedFields(stripFieldOutputs(row)),
+            resolvedTableNamespace,
+          );
 
     const materializedItems = await materializePlayDatasetInput(items);
     totalInputCount = materializedItems.length;
@@ -1259,14 +1385,29 @@ export class PlayContextImpl {
       this.toOutputRow(item as Record<string, unknown>),
     );
 
-    assertUniqueExplicitMapKeys({
-      mapNamespace: normalizedMapNamespace,
-      rows: rawItems,
-      resolver: explicitKeyResolver,
-    });
+    if (explicitKeyResolver) {
+      const seenKeys = new Map<string, number>();
+      for (let index = 0; index < rawItems.length; index += 1) {
+        const keyValue = explicitKeyResolver(rawItems[index]!, index);
+        const previousIndex = seenKeys.get(keyValue);
+        if (previousIndex !== undefined) {
+          throw new Error(
+            `ctx.map("${normalizedMapNamespace}") key function produced duplicate value "${keyValue}" for rows ${previousIndex} and ${index}. ` +
+              'Each row must produce a unique key. Combine columns (e.g. `${row.email}|${row.company}`) or pick a column that is unique per row.',
+          );
+        }
+        seenKeys.set(keyValue, index);
+      }
+    }
     if (this.options.onMapStart) {
+      const mapStartRows = explicitKeyResolver
+        ? rawItems.map((row, index) => ({
+            ...row,
+            __deeplineRowKey: rowIdentity(row, index),
+          }))
+        : rawItems;
       const mapStartResult = await this.options.onMapStart(
-        rawItems,
+        mapStartRows,
         resolvedTableNamespace,
         {
           playName: this.options.playName,
@@ -1278,16 +1419,30 @@ export class PlayContextImpl {
       resolvedTableNamespace = normalizeTableNamespace(
         mapStartResult.tableNamespace,
       );
+      const persistedRowIdentity = (
+        row: Record<string, unknown>,
+        index = 0,
+      ) =>
+        typeof row.__deeplineRowKey === 'string'
+          ? row.__deeplineRowKey
+          : rowIdentity(row, index);
       const pendingKeys = new Set(
-        mapStartResult.pendingRows.map((row) => rowIdentity(row)),
+        mapStartResult.pendingRows.map((row, index) =>
+          persistedRowIdentity(row, index),
+        ),
       );
       itemsToProcess = materializedItems
-        .map((item) => this.toOutputRow(item as Record<string, unknown>))
-        .filter((row) => pendingKeys.has(rowIdentity(row)));
+        .map((item, index) => ({
+          row: this.toOutputRow(item as Record<string, unknown>),
+          index,
+        }))
+        .filter(({ row, index }) => pendingKeys.has(rowIdentity(row, index)))
+        .map(({ row }) => row);
       if (mapStartResult.completedRows.length > 0) {
         completedItemsByKey = new Map();
-        for (const row of mapStartResult.completedRows) {
-          const rowKey = rowIdentity(row);
+        for (let index = 0; index < mapStartResult.completedRows.length; index += 1) {
+          const row = mapStartResult.completedRows[index]!;
+          const rowKey = persistedRowIdentity(row, index);
           if (rowKey) completedItemsByKey.set(rowKey, row);
         }
         this.log(
@@ -1296,22 +1451,38 @@ export class PlayContextImpl {
       }
     }
 
-    const mapScope = this.mapRowIdentity.createScope({
+    const mapScope = this.createMapExecutionScope({
       logicalNamespace: normalizedMapNamespace,
       artifactTableNamespace: resolvedTableNamespace,
       explicitKey: explicitKeyResolver,
-      fieldNames: mapFieldNames,
     });
     const completedRowKeys =
       completedItemsByKey != null ? [...completedItemsByKey.keys()] : [];
-    const pendingRowKeys = itemsToProcess.map((item) =>
-      mapScope.rowIdentity(this.toOutputRow(item)),
+    const pendingRowKeys = itemsToProcess.map((item, index) =>
+      mapScope.rowIdentity(this.toOutputRow(item), index),
     );
-    this.mapFrames.start({
-      scope: mapScope,
+    this.setMapFrame({
+      mapInvocationId: mapScope.mapInvocationId,
+      mapNodeId: mapScope.mapNodeId ?? null,
+      logicalNamespace: mapScope.logicalNamespace,
+      artifactTableNamespace: mapScope.artifactTableNamespace,
+      status: 'running',
       totalRows: totalInputCount,
       completedRowKeys,
       pendingRowKeys,
+      startedAt: Date.now(),
+      updatedAt: Date.now(),
+    });
+    this.emitExecutionEvent({
+      type: 'map.started',
+      mapInvocationId: mapScope.mapInvocationId,
+      mapNodeId: mapScope.mapNodeId ?? null,
+      logicalNamespace: mapScope.logicalNamespace,
+      artifactTableNamespace: mapScope.artifactTableNamespace,
+      totalRows: totalInputCount,
+      completedRows: completedRowKeys.length,
+      pendingRows: pendingRowKeys.length,
+      at: Date.now(),
     });
 
     const mapResults = await this.runFieldMap(
@@ -1334,19 +1505,19 @@ export class PlayContextImpl {
               const rowIdentityRow = this.toOutputRow(
                 itemsToProcess[index] as Record<string, unknown>,
               );
-              const rowKey = rowIdentity(rowIdentityRow);
+              const rowKey = rowIdentity(rowIdentityRow, index);
               if (rowKey) resultsByKey.set(rowKey, row);
             }
-            return rawItems.map((rawItem) => {
-              const rowKey = rowIdentity(rawItem);
-              return (
+            return rawItems.map((rawItem, index) => {
+              const rowKey = rowIdentity(rawItem, index);
+              return this.toPublicOutputRow(
                 resultsByKey.get(rowKey) ??
-                completedItemsByKey!.get(rowKey) ??
-                rawItem
+                  completedItemsByKey!.get(rowKey) ??
+                  rawItem,
               );
             });
           })()
-        : mapResults;
+        : mapResults.map((row) => this.toPublicOutputRow(row));
 
     return createDeferredPlayDataset({
       datasetKind: 'map',
@@ -1355,7 +1526,7 @@ export class PlayContextImpl {
         resolvedTableNamespace,
       ),
       count: results.length,
-      previewRows: results.slice(0, 10),
+      previewRows: results.slice(0, 5),
       tableNamespace: resolvedTableNamespace,
       resolvers: {
         count: async () => results.length,
@@ -1397,9 +1568,11 @@ export class PlayContextImpl {
     const normalizedTableNamespace = mapScope.artifactTableNamespace;
     const rowIdentity = (row: Record<string, unknown>, index = 0) =>
       mapScope.rowIdentity(
-        Object.fromEntries(
-          Object.entries(row).filter(
-            ([fieldName]) => !mapFieldNames.includes(fieldName),
+        stripCsvProjectedFields(
+          Object.fromEntries(
+            Object.entries(row).filter(
+              ([fieldName]) => !mapFieldNames.includes(fieldName),
+            ),
           ),
         ),
         index,
@@ -1441,13 +1614,52 @@ export class PlayContextImpl {
       completedRowKey?: string | null;
       pendingRowKey?: string | null;
       activeBoundaryId?: string | null;
+      failedDelta?: number;
       emitEventType?: PlayExecutionEvent['type'];
     }) => {
-      this.mapFrames.updateProgress({
-        ...input,
-        scope: mapScope,
-        totalRows,
-      });
+      const existing =
+        this.checkpoint.mapFrames?.[mapScope.mapInvocationId] ?? null;
+      if (!existing) {
+        return;
+      }
+      const completedRowKeys = new Set(existing.completedRowKeys);
+      const pendingRowKeys = new Set(existing.pendingRowKeys);
+      if (input.completedRowKey?.trim()) {
+        completedRowKeys.add(input.completedRowKey.trim());
+        pendingRowKeys.delete(input.completedRowKey.trim());
+      }
+      if (input.pendingRowKey?.trim()) {
+        pendingRowKeys.add(input.pendingRowKey.trim());
+      }
+      const nextFrame: MapExecutionFrame = {
+        ...existing,
+        status: input.status ?? existing.status,
+        completedRowKeys: [...completedRowKeys],
+        pendingRowKeys: [...pendingRowKeys],
+        ...(input.activeBoundaryId !== undefined
+          ? { activeBoundaryId: input.activeBoundaryId }
+          : {}),
+        updatedAt: Date.now(),
+      };
+      this.setMapFrame(nextFrame);
+      if (input.emitEventType) {
+        this.emitExecutionEvent({
+          type: input.emitEventType,
+          mapInvocationId: mapScope.mapInvocationId,
+          mapNodeId: mapScope.mapNodeId ?? null,
+          logicalNamespace: mapScope.logicalNamespace,
+          artifactTableNamespace: mapScope.artifactTableNamespace,
+          completedRows: nextFrame.completedRowKeys.length,
+          failedRows: Math.max(
+            0,
+            totalRows -
+              nextFrame.completedRowKeys.length -
+              nextFrame.pendingRowKeys.length,
+          ),
+          totalRows,
+          at: Date.now(),
+        } as PlayExecutionEvent);
+      }
     };
 
     if (this.canUsePureJsMapFastPath(definition)) {
@@ -1456,10 +1668,12 @@ export class PlayContextImpl {
         fieldEntries,
         visibleFields,
         normalizedTableNamespace,
+        (row, index) => mapScope.rowIdentity(row, index),
       );
-      for (const row of results) {
+      for (let index = 0; index < results.length; index += 1) {
+        const row = results[index]!;
         updateMapFrameProgress({
-          completedRowKey: rowIdentity(row),
+          completedRowKey: rowIdentity(row, index),
         });
       }
       if (emitTerminalEvent) {
@@ -1527,7 +1741,7 @@ export class PlayContextImpl {
               await this.resolveMapFieldValue(
                 resolver,
                 item,
-                { ...baseRow, ...computedFields },
+                cloneCsvAliasedRow(baseRow, computedFields),
                 idx,
               ),
           );
@@ -1544,7 +1758,7 @@ export class PlayContextImpl {
           });
         }
 
-        const merged = { ...baseRow, ...computedFields };
+        const merged = cloneCsvAliasedRow(baseRow, computedFields);
         activeFieldName = null;
         updateMapFrameProgress({
           completedRowKey: rowKey,
@@ -1557,11 +1771,7 @@ export class PlayContextImpl {
           error: null,
           dataPatch: {},
         });
-        return Object.fromEntries(
-          Object.entries(merged).filter(
-            ([fieldName]) => !fieldName.startsWith('_'),
-          ),
-        );
+        return this.toPublicOutputRow(merged);
       } catch (error) {
         if (isPlayRowExecutionSuspendedError(error)) {
           this.pendingRowEventBoundaries.push(error.boundary);
@@ -1620,17 +1830,17 @@ export class PlayContextImpl {
           items[index] as Record<string, unknown>,
         );
         if (result === WAITING_ROW) {
-          const key = rowIdentity(rawItem);
+          const key = rowIdentity(rawItem, index);
           if (key) {
             completedRowKeys.add(key);
           }
           continue;
         }
         const row = result as Record<string, unknown>;
-        const key = rowIdentity(row);
+        const key = rowIdentity(row, index);
         if (key) completedRowKeys.add(key);
       }
-      this.mapFrames.set({
+      this.setMapFrame({
         ...(this.checkpoint.mapFrames?.[mapScope.mapInvocationId] ?? {
           mapInvocationId: mapScope.mapInvocationId,
           logicalNamespace: mapScope.logicalNamespace,
@@ -1638,8 +1848,8 @@ export class PlayContextImpl {
           status: 'suspended' as const,
           totalRows,
           completedRowKeys: [...completedRowKeys],
-          pendingRowKeys: items.map((item) =>
-            rowIdentity(this.toOutputRow(item as Record<string, unknown>)),
+          pendingRowKeys: items.map((item, index) =>
+            rowIdentity(this.toOutputRow(item as Record<string, unknown>), index),
           ),
           startedAt: Date.now(),
           updatedAt: Date.now(),
@@ -1666,9 +1876,10 @@ export class PlayContextImpl {
     const results = settledResults.filter(
       (result): result is Record<string, unknown> => result !== WAITING_ROW,
     );
-    for (const row of results) {
+    for (let index = 0; index < results.length; index += 1) {
+      const row = results[index]!;
       updateMapFrameProgress({
-        completedRowKey: rowIdentity(row),
+        completedRowKey: rowIdentity(row, index),
       });
     }
     if (emitTerminalEvent) {
@@ -1714,7 +1925,7 @@ export class PlayContextImpl {
     index: number,
     path: string[],
   ): Promise<unknown> {
-    let currentRow = { ...row };
+    let currentRow = cloneCsvAliasedRow(row);
     const produced: Record<string, unknown> = {};
     for (const step of program.steps) {
       const value = await this.executeStepProgramStep(step, currentRow, index, [
@@ -1722,7 +1933,7 @@ export class PlayContextImpl {
         step.name,
       ]);
       produced[step.name] = value;
-      currentRow = { ...currentRow, [step.name]: value };
+      currentRow = cloneCsvAliasedRow(currentRow, { [step.name]: value });
     }
     if (typeof program.returnResolver === 'function') {
       return await program.returnResolver(currentRow, this, index);
@@ -1804,7 +2015,6 @@ export class PlayContextImpl {
     ) {
       return false;
     }
-    const toolExecuteMarker = ['.tools', 'execute('].join('.');
     return Object.values(definition).every((resolver) => {
       if (typeof resolver !== 'function') {
         return true;
@@ -1812,7 +2022,7 @@ export class PlayContextImpl {
 
       const source = Function.prototype.toString.call(resolver);
       return (
-        !source.includes(toolExecuteMarker) && !source.includes('.waterfall(')
+        !source.includes('.tools.execute(') && !source.includes('.waterfall(')
       );
     });
   }
@@ -1822,13 +2032,11 @@ export class PlayContextImpl {
     fieldEntries: [string, MapFieldDefinition<T>[string]][],
     visibleFields: string[],
     tableNamespace: string,
+    rowIdentity: (row: Record<string, unknown>, index: number) => string,
   ): Promise<Array<Record<string, unknown>>> {
     const results: Array<Record<string, unknown>> = [];
     this.pureMapExecutionActive = true;
 
-    const rowIdentity = (row: Record<string, unknown>) =>
-      derivePlayRowIdentity(row, tableNamespace);
-
     try {
       for (let index = 0; index < items.length; index += 1) {
         const item = items[index]!;
@@ -1841,7 +2049,7 @@ export class PlayContextImpl {
             activeFieldName = fieldName;
             if (this.shouldReuseExistingFieldValue(baseRow, fieldName)) {
               computedFields[fieldName] = baseRow[fieldName];
-              this.emitScopedRowUpdate(rowIdentity(baseRow), tableNamespace, {
+              this.emitScopedRowUpdate(rowIdentity(baseRow, index), tableNamespace, {
                 rowId: index,
                 status: undefined,
                 stage: null,
@@ -1858,7 +2066,7 @@ export class PlayContextImpl {
               continue;
             }
 
-            this.emitScopedRowUpdate(rowIdentity(baseRow), tableNamespace, {
+            this.emitScopedRowUpdate(rowIdentity(baseRow, index), tableNamespace, {
               rowId: index,
               status: 'running',
               stage: fieldName,
@@ -1876,10 +2084,10 @@ export class PlayContextImpl {
             computedFields[fieldName] = await this.resolveMapFieldValue(
               resolver,
               item,
-              { ...baseRow, ...computedFields },
+              cloneCsvAliasedRow(baseRow, computedFields),
               index,
             );
-            this.emitScopedRowUpdate(rowIdentity(baseRow), tableNamespace, {
+            this.emitScopedRowUpdate(rowIdentity(baseRow, index), tableNamespace, {
               rowId: index,
               status: undefined,
               stage: 'completed',
@@ -1897,16 +2105,13 @@ export class PlayContextImpl {
             });
           }
 
-          const merged = { ...baseRow, ...computedFields };
           results.push(
-            Object.fromEntries(
-              Object.entries(merged).filter(
-                ([fieldName]) => !fieldName.startsWith('_'),
-              ),
+            this.toPublicOutputRow(
+              cloneCsvAliasedRow(baseRow, computedFields),
             ),
           );
 
-          const rowKey = rowIdentity(baseRow);
+          const rowKey = rowIdentity(baseRow, index);
           activeFieldName = null;
           this.emitScopedRowUpdate(rowKey, tableNamespace, {
             rowId: index,
@@ -1917,7 +2122,7 @@ export class PlayContextImpl {
             dataPatch: {},
           });
         } catch (error) {
-          const rowKey = rowIdentity(baseRow);
+          const rowKey = rowIdentity(baseRow, index);
           this.emitScopedRowUpdate(rowKey, tableNamespace, {
             rowId: index,
             status: 'failed',
@@ -1964,7 +2169,7 @@ export class PlayContextImpl {
   private async drainQueuedWork<T>(promises: Promise<T>[]): Promise<void> {
     // Drain loop: each pass resolves queued waterfalls/tool calls.
     // When a batch resolves, rows resume and may queue MORE calls
-    // (e.g. row executes one tool request, then queues another sequentially).
+    // (e.g. row does tools.execute('a') then tools.execute('b') sequentially).
     // We keep looping until nothing new is queued and all rows finish.
     //
     // Important: an unresolved Promise by itself does not keep Node alive. The
@@ -2041,6 +2246,13 @@ export class PlayContextImpl {
     return { value: item };
   }
 
+  private toPublicOutputRow(row: Record<string, unknown>): Record<string, unknown> {
+    const stripped = stripCsvProjectedFields(row);
+    return Object.fromEntries(
+      Object.entries(stripped).filter(([fieldName]) => !fieldName.startsWith('_')),
+    );
+  }
+
   async waterfall(
     toolNameOrSpec: string | InlineWaterfallSpec,
     input: Record<string, unknown>,
@@ -2081,13 +2293,10 @@ export class PlayContextImpl {
     }
 
     // Check if this was already resolved in a previous attempt (checkpoint)
-    const resolved = this.waterfallReplay.getResolved(queueKey, {
-      rowId,
-      rowKey: store.rowKey ?? null,
-    });
-    if (resolved.found) {
+    const resolved = this.checkpoint.resolvedWaterfalls[queueKey];
+    if (resolved && rowId in resolved) {
       this.log(`  Row ${rowId} ${toolName}: recovered from checkpoint`);
-      return resolved.value;
+      return resolved[rowId];
     }
 
     return new Promise((resolve) => {
@@ -2137,9 +2346,13 @@ export class PlayContextImpl {
     });
   }
 
-  private async executeTool(request: ToolExecutionRequest): Promise<unknown> {
-    const { tool: toolId, input } = request;
-    const normalizedKey = this.normalizeContextKey(request.id, 'tool');
+  private async executeTool(
+    key: string,
+    toolId: string,
+    input: Record<string, unknown>,
+    options?: ToolCallOptions,
+  ): Promise<unknown> {
+    const normalizedKey = this.normalizeContextKey(key, 'tool');
 
     const eventWaitHandler =
       (await this.options.getIntegrationEventWaitHandler?.(toolId)) ?? null;
@@ -2160,16 +2373,14 @@ export class PlayContextImpl {
 
       if (this.pureMapExecutionActive && !store) {
         throw new Error(
-          'Tool execution cannot run inside the pure-JS fast path. Call ctx.tools.execute({ id, tool, input }) directly in the map definition so the batching runtime can stay enabled.',
+          'ctx.tools.execute() cannot run inside the pure-JS fast path. Call it directly in the map definition so the batching runtime can stay enabled.',
         );
       }
 
       if (!store) {
         const directRowId = -(this.directToolCallIndex + 1);
         this.directToolCallIndex += 1;
-        const directCacheKey = this.buildToolResultCacheKey({
-          rowId: directRowId,
-        });
+        const directCacheKey = this.buildToolResultCacheKey({ rowId: directRowId });
         const cached = this.getCachedToolResult(toolId, directCacheKey);
         if (cached?.done) {
           this.log(`Calling tool: ${toolId} recovered from checkpoint`);
@@ -2209,9 +2420,15 @@ export class PlayContextImpl {
       const callId = [
         store.tableNamespace?.trim() || 'map',
         store.rowKey?.trim() || String(rowId),
-        fieldName?.trim() || 'field',
         normalizedKey,
+        toolId,
       ].join(':');
+      if (this.toolCallResolvers.has(callId)) {
+        throw new Error(
+          `ctx.tools.execute("${normalizedKey}") was called more than once concurrently for the same row. ` +
+            'Use a unique id for each row-scoped tool call.',
+        );
+      }
 
       const cached = this.getCachedToolResult(
         toolId,
@@ -2240,12 +2457,7 @@ export class PlayContextImpl {
       }
 
       return new Promise((resolve) => {
-        const existingResolvers = this.toolCallResolvers.get(callId);
-        if (existingResolvers) {
-          existingResolvers.push(resolve);
-          return;
-        }
-        this.toolCallResolvers.set(callId, [resolve]);
+        this.toolCallResolvers.set(callId, resolve);
         this.emitScopedFieldMetaUpdate({
           rowId,
           key: store.rowKey ?? null,
@@ -2266,7 +2478,7 @@ export class PlayContextImpl {
           input,
           tableNamespace: store.tableNamespace,
           rowKey: store.rowKey ?? null,
-          description: normalizeStepDescription(request.description),
+          description: normalizeStepDescription(options?.description),
         });
       });
     };
@@ -2282,7 +2494,7 @@ export class PlayContextImpl {
       {
         markSkipped: () => {
           this.log(
-            `ctx.tools.execute({ id: ${normalizedKey}, tool: ${toolId} }): no-op due completed receipt`,
+            `ctx.tools.execute(${toolId}): no-op due completed receipt ${normalizedKey}`,
           );
         },
         execute: executeTool,
@@ -2602,7 +2814,7 @@ export class PlayContextImpl {
     const normalizedKey = this.normalizeContextKey(key, 'fetch');
     if (rowContext.getStore()) {
       throw new Error(
-        'ctx.fetch() must run outside ctx.map(); use ctx.tools.execute({ id, tool, input }) for row-level external requests so Deepline can batch and checkpoint them.',
+        'ctx.fetch() must run outside ctx.map(); use ctx.tools.execute(...) for row-level external requests so Deepline can batch and checkpoint them.',
       );
     }
 
@@ -2685,9 +2897,7 @@ export class PlayContextImpl {
     }
 
     const rowStore = rowContext.getStore();
-    const scope = rowStore
-      ? `row-${rowStore.tableNamespace?.trim() || 'map'}:${rowStore.rowKey?.trim() || String(rowStore.rowId)}`
-      : 'workflow';
+    const scope = rowStore ? `row-${rowStore.rowId}` : 'workflow';
     const callIndexKey = `${scope}:${normalizedKey}`;
     const callIndex = this.stepCallIndexByKey.get(callIndexKey) ?? 0;
     this.stepCallIndexByKey.set(callIndexKey, callIndex + 1);
@@ -2829,18 +3039,20 @@ export class PlayContextImpl {
           }),
         getCachedResults: (provider) => {
           const batchKey = `${queueKey}:${provider}`;
-          const recovered = this.waterfallReplay.readProviderBatch({
-            batchKey,
-            requests,
-          });
-          if (recovered) {
-            this.log(`  ${provider}: skipping (recovered from checkpoint)`);
-          }
-          return recovered;
+          const cached = this.checkpoint.completedBatches[batchKey];
+          if (!cached) return null;
+          this.log(`  ${provider}: skipping (recovered from checkpoint)`);
+          return cached.map((entry) => ({
+            request: requests.find((request) => request.rowId === entry.rowId)!,
+            result: entry.result,
+          }));
         },
         storeCachedResults: (provider, results) => {
           const batchKey = `${queueKey}:${provider}`;
-          this.waterfallReplay.writeProviderBatch(batchKey, results);
+          this.checkpoint.completedBatches[batchKey] = results.map((entry) => ({
+            rowId: entry.request.rowId,
+            result: entry.result,
+          }));
         },
         executeProviderRequests: async (provider, pending) => {
           const providerToolId = resolveWaterfallToolId(provider, toolName);
@@ -2971,7 +3183,7 @@ export class PlayContextImpl {
         if (wState?.status === 'pending') {
           wState.status = 'failed';
           wState.error = 'All providers exhausted';
-          this.waterfallReplay.setResolved(queueKey, req, null);
+          this.checkpoint.resolvedWaterfalls[queueKey]![req.rowId] = null;
 
           const resolver = this.resolvers.get(`${req.rowId}-${queueKey}`);
           if (resolver) {
@@ -3080,8 +3292,26 @@ export class PlayContextImpl {
           execute: async (request) => {
             const codeStepCtx = {
               tools: {
-                execute: async (request: ToolExecutionRequest) =>
-                  await this.callToolAPI(request.tool, request.input),
+                execute: async (
+                  requestOrKey:
+                    | { tool: string; input: Record<string, unknown> }
+                    | string,
+                  toolId?: string,
+                  payload?: Record<string, unknown>,
+                ) => {
+                  if (typeof requestOrKey === 'object') {
+                    return await this.callToolAPI(
+                      requestOrKey.tool,
+                      requestOrKey.input,
+                    );
+                  }
+                  if (!toolId || !payload) {
+                    throw new Error(
+                      'inline waterfall ctx.tools.execute requires a tool and input.',
+                    );
+                  }
+                  return await this.callToolAPI(toolId, payload);
+                },
               },
             };
             return await step.run(request.input, codeStepCtx);
@@ -3447,7 +3677,7 @@ export class PlayContextImpl {
       if (wState?.status === 'pending') {
         wState.status = 'failed';
         wState.error = 'All waterfall steps exhausted';
-        this.waterfallReplay.setResolved(queueKey, req, null);
+        this.checkpoint.resolvedWaterfalls[queueKey]![req.rowId] = null;
         const resolver = this.resolvers.get(`${req.rowId}-${queueKey}`);
         if (resolver) {
           resolver(null);
@@ -3499,14 +3729,7 @@ export class PlayContextImpl {
 
     wState.status = 'complete';
     wState.result = result;
-    this.waterfallReplay.setResolved(
-      queueKey,
-      {
-        rowId,
-        rowKey,
-      },
-      result,
-    );
+    this.checkpoint.resolvedWaterfalls[queueKey]![rowId] = result;
 
     const resolver = this.resolvers.get(`${rowId}-${queueKey}`);
     if (resolver) {
@@ -3558,11 +3781,9 @@ export class PlayContextImpl {
           );
           if (cached?.done) {
             this.log(`  Row ${req.rowId} ${toolId}: recovered from checkpoint`);
-            const resolvers = this.toolCallResolvers.get(req.callId);
-            if (resolvers) {
-              for (const resolver of resolvers) {
-                resolver(cached.result);
-              }
+            const resolver = this.toolCallResolvers.get(req.callId);
+            if (resolver) {
+              resolver(cached.result);
               this.toolCallResolvers.delete(req.callId);
             }
           } else {
@@ -3620,10 +3841,7 @@ export class PlayContextImpl {
               },
             });
           } else {
-            await executeChunkedRequests<
-              ToolCallRequest,
-              ToolExecutionResponse
-            >({
+            await executeChunkedRequests<ToolCallRequest, ToolExecutionResponse>({
               requests: pendingRequests,
               batchSize: await this.rateLimitScheduler.getSuggestedParallelism(
                 toolId,
@@ -3772,8 +3990,26 @@ export class PlayContextImpl {
               toolNameOrSpec.output,
               await step.run(input, {
                 tools: {
-                  execute: async (request: ToolExecutionRequest) =>
-                    await this.callToolAPI(request.tool, request.input),
+                  execute: async (
+                    requestOrKey:
+                      | { tool: string; input: Record<string, unknown> }
+                      | string,
+                    toolId?: string,
+                    payload?: Record<string, unknown>,
+                  ) => {
+                    if (typeof requestOrKey === 'object') {
+                      return await this.callToolAPI(
+                        requestOrKey.tool,
+                        requestOrKey.input,
+                      );
+                    }
+                    if (!toolId || !payload) {
+                      throw new Error(
+                        'inline waterfall ctx.tools.execute requires a tool and input.',
+                      );
+                    }
+                    return await this.callToolAPI(toolId, payload);
+                  },
                 },
               }),
             )
@@ -3830,7 +4066,13 @@ export class PlayContextImpl {
     toolId: string,
     input: Record<string, unknown>,
   ): Promise<unknown> {
-    return (await this.callToolExecutionAPI(toolId, input)).result;
+    const execution = await this.callToolExecutionAPI(toolId, input);
+    return execution.result != null
+      && typeof execution.result === 'object'
+      && !Array.isArray(execution.result)
+      && 'data' in execution.result
+      ? execution.result.data
+      : execution.result;
   }
 
   private async callToolExecutionAPI(
@@ -3895,7 +4137,8 @@ export class PlayContextImpl {
               if (!response.ok) {
                 const text = await response.text();
                 if (
-                  isRetryableTransientToolHttpStatus(toolId, response.status) &&
+                  response.status >= 500 &&
+                  response.status < 600 &&
                   rateLimitAttempt + 1 < TOOL_TRANSIENT_HTTP_MAX_ATTEMPTS
                 ) {
                   rateLimitAttempt += 1;
@@ -3947,24 +4190,24 @@ export class PlayContextImpl {
               }
 
               const data = (await response.json()) as Record<string, unknown>;
-              const normalized = normalizePlayToolResult(data.result ?? data);
+              const result = data.result ?? data;
               const status =
                 typeof data.status === 'string'
                   ? data.status
-                  : normalized == null
+                  : result == null
                     ? 'no_result'
                     : 'completed';
               setSpanAttributes(span, {
                 'plays.tool_result_kind':
-                  normalized == null
+                  result == null
                     ? 'null'
-                    : Array.isArray(normalized)
+                    : Array.isArray(result)
                       ? 'array'
-                      : typeof normalized,
+                      : typeof result,
               });
               return {
                 status,
-                result: normalized,
+                result,
                 metadata: parseExecuteToolMetadata(toolId, data),
               };
             }