deepline 0.1.0 → 0.1.2

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

@@ -0,0 +1,3999 @@
+/**
+ * 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
+ * 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
+ * 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
+ *
+ * Temporal integration:
+ * - checkpoint: recovered from heartbeatDetails on retry (skip completed batches)
+ * - onBatchComplete: called after each provider batch (heartbeat checkpoint to Temporal)
+ */
+import { AsyncLocalStorage } from 'async_hooks';
+import {
+  createDeferredPlayDataset,
+  materializePlayDatasetInput,
+} from '@shared_libs/plays/dataset';
+import type { PlayDataset, PlayDatasetInput } from '@shared_libs/plays/dataset';
+import {
+  compileRequestsWithStrategy,
+  executeChunkedRequests,
+  executeWaterfallProviders,
+  resolveWaterfallToolId,
+} from './batch-runtime';
+import { PlayRateLimitScheduler } from '@shared_libs/plays/rate-limit-scheduler';
+import { normalizePlayToolResult } from './result-normalization';
+import {
+  cloneToolExecuteResultWithExecution,
+  createToolExecuteResult,
+  isToolExecuteResult,
+  type ToolExecuteResult,
+  type ToolResultMetadataInput,
+} from './tool-result';
+import { sqlSafePlayColumnName } from '@shared_libs/plays/static-pipeline';
+import { createRuntimeDatasetId } from './dataset-id';
+import {
+  derivePlayRowIdentity,
+  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 { setSpanAttributes, withActiveSpan } from './tracing';
+import { DISALLOWED_RUN_JAVASCRIPT_TOOL_MESSAGE } from './runtime-constraints';
+import {
+  PlayExecutionSuspendedError,
+  PlayRowExecutionSuspendedError,
+  isPlayRowExecutionSuspendedError,
+} from './suspension';
+import type {
+  CsvOptions,
+  RowState,
+  WaterfallRequest,
+  WaterfallOptions,
+  InlineWaterfallSpec,
+  MapDefinitionOptions,
+  MapOptions,
+  MapRunOptions,
+  ToolCallRequest,
+  ToolBatchResult,
+  ToolExecutionRequest,
+  ContextOptions,
+  PlayCallOptions,
+  PlayCheckpoint,
+  PlayStep,
+  PlayStepRowResult,
+  PlayRowUpdate,
+  MapFieldDefinition,
+  MapFieldResolver,
+  PlayExecutionGovernanceLimits,
+  PlayExecutionGovernanceState,
+  ResolvedPlayExecution,
+  PlayFetchResponse,
+  MapExecutionScope,
+  MapExecutionFrame,
+  PlayExecutionEvent,
+  IntegrationEventWaitHandler,
+  RuntimeStepReceipt,
+  RuntimeStepProgram,
+  RuntimeStepProgramStep,
+  RuntimeConditionalStepResolver,
+} from './ctx-types';
+
+/**
+ * SECURITY: AsyncLocalStorage is per async execution, not a cross-run cache.
+ *
+ * Keep only row-scoped metadata here. Do not expand this store with credentials,
+ * provider responses, org-wide mutable caches, or anything that must not cross
+ * workflow boundaries if worker scheduling/interleaving changes.
+ */
+const rowContext = new AsyncLocalStorage<{
+  rowId: number;
+  fieldName?: string;
+  tableNamespace?: string;
+  rowKey?: string;
+  mapScope?: MapExecutionScope;
+}>();
+const PROGRESS_HEARTBEAT_INTERVAL_MS = 1_000;
+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;
+const WATERFALL_ROW_MATCH_LOG_INTERVAL = 1_000;
+const BATCH_SIZE_LOG_SAMPLE_LIMIT = 10;
+const DEFAULT_GOVERNANCE_LIMITS: PlayExecutionGovernanceLimits = {
+  maxPlayCallDepth: 6,
+  maxPlayCallCount: 32,
+  maxToolCallCount: 500,
+  maxWaterfallStepExecutions: null,
+  maxRetryCount: 200,
+  maxDescendants: 64,
+  maxChildPlayCallsPerParent: 16,
+  maxConcurrentPlayCalls: 16,
+  maxConcurrentToolCalls: 32,
+};
+const STEP_PROGRAM_MAP_DEFINITION = Symbol('deepline.stepProgramMapDefinition');
+
+function stableFetchHash(value: string): string {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = (hash * 31 + value.charCodeAt(index)) >>> 0;
+  }
+  return hash.toString(36);
+}
+
+function compactRowResultsPreview<T>(rows: T[]): T[] {
+  if (rows.length <= IN_MEMORY_STEP_RESULT_PREVIEW_LIMIT) {
+    return rows;
+  }
+  return rows.slice(0, IN_MEMORY_STEP_RESULT_PREVIEW_LIMIT);
+}
+
+function isRuntimeStepProgram(value: unknown): value is RuntimeStepProgram {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    (value as { kind?: unknown }).kind === 'steps' &&
+    Array.isArray((value as { steps?: unknown }).steps)
+  );
+}
+
+function isRuntimeConditionalStepResolver(
+  value: unknown,
+): value is RuntimeConditionalStepResolver {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    (value as { kind?: unknown }).kind === 'conditional' &&
+    typeof (value as { when?: unknown }).when === 'function' &&
+    typeof (value as { run?: unknown }).run === 'function'
+  );
+}
+
+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',
+    steps: [],
+  };
+
+  constructor(
+    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 {
+    if (!name.trim()) {
+      throw new Error(
+        'ctx.map(...).step(name, ...) requires a non-empty step name.',
+      );
+    }
+    this.program.steps = [...this.program.steps, { name, resolver }];
+    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>);
+  }
+}
+
+const WAITING_ROW = Symbol('deepline.waiting_row');
+
+function normalizeFetchHeaders(
+  headers: RequestInit['headers'],
+): Record<string, string> {
+  if (!headers) return {};
+  if (headers instanceof Headers) {
+    return Object.fromEntries(
+      [...headers.entries()].map(([key, value]) => [key.toLowerCase(), value]),
+    );
+  }
+  if (Array.isArray(headers)) {
+    return Object.fromEntries(
+      headers.map(([key, value]) => [key.toLowerCase(), value]),
+    );
+  }
+  return Object.fromEntries(
+    Object.entries(headers).map(([key, value]) => [
+      key.toLowerCase(),
+      String(value),
+    ]),
+  );
+}
+
+function parseRetryAfterMs(header: string | null): number {
+  if (!header) {
+    return TOOL_RETRY_AFTER_FALLBACK_MS;
+  }
+
+  const seconds = Number(header);
+  if (Number.isFinite(seconds) && seconds > 0) {
+    return Math.ceil(seconds * 1000);
+  }
+
+  const retryAt = Date.parse(header);
+  if (Number.isFinite(retryAt)) {
+    return Math.max(1, retryAt - Date.now());
+  }
+
+  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 {
+    return JSON.parse(bodyText) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+type ToolExecutionResponse = {
+  status: string;
+  result: unknown;
+  metadata: ToolResultMetadataInput | null;
+};
+
+function parseExecuteToolMetadata(
+  toolId: string,
+  data: Record<string, unknown>,
+): ToolResultMetadataInput | null {
+  const metadata = data._metadata;
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+    return null;
+  }
+  const tool = (metadata as Record<string, unknown>).tool;
+  if (!tool || typeof tool !== 'object' || Array.isArray(tool)) return null;
+  const record = tool as Record<string, unknown>;
+  const metadataToolId =
+    typeof record.toolId === 'string' && record.toolId.trim()
+      ? record.toolId
+      : toolId;
+  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]] : [];
+        },
+      ),
+    );
+  };
+  const listExtractorPaths = Array.isArray(record.listExtractorPaths)
+    ? record.listExtractorPaths.filter(
+        (path): path is string =>
+          typeof path === 'string' && path.trim().length > 0,
+      )
+    : [];
+  return {
+    toolId: metadataToolId,
+    resultIdentityGetters: readGetters(record.resultIdentityGetters),
+    listExtractorPaths,
+    listIdentityGetters: readGetters(record.listIdentityGetters),
+  };
+}
+
+function assertJsonSerializableStepOutput(
+  stepId: string,
+  output: unknown,
+): void {
+  try {
+    JSON.stringify(output);
+  } catch (error) {
+    throw new Error(
+      `ctx.step(${stepId}) returned a value that cannot be checkpointed as JSON: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}
+
+function normalizeStepDescription(
+  value: string | undefined,
+): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function emptyCheckpoint(): PlayCheckpoint {
+  return {
+    completedBatches: {},
+    completedToolBatches: {},
+    resolvedWaterfalls: {},
+    mapFrames: {},
+  };
+}
+
+function createDefaultGovernanceState(
+  options: ContextOptions,
+): PlayExecutionGovernanceState {
+  const playId = options.playId ?? options.workflowId ?? 'anonymous-play';
+  const runId = options.runId ?? options.workflowId ?? 'anonymous-run';
+  return {
+    rootPlayId: playId,
+    rootRunId: runId,
+    currentPlayId: playId,
+    currentRunId: runId,
+    ancestryPlayIds: [playId],
+    ancestryRunIds: [runId],
+    callDepth: 0,
+    playCallCount: 0,
+    toolCallCount: 0,
+    waterfallStepExecutions: 0,
+    retryCount: 0,
+    descendantCount: 0,
+    parentChildCalls: {},
+    inFlightPlayCalls: 0,
+    inFlightPlayCallsByPlayId: {},
+    inFlightToolCalls: 0,
+    limits: DEFAULT_GOVERNANCE_LIMITS,
+  };
+}
+
+function isInlineWaterfallSpec(value: unknown): value is InlineWaterfallSpec {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const candidate = value as InlineWaterfallSpec;
+  return (
+    typeof candidate.id === 'string' &&
+    typeof candidate.output === 'string' &&
+    typeof candidate.minResults === 'number' &&
+    candidate.minResults >= 1 &&
+    Array.isArray(candidate.steps) &&
+    candidate.steps.length > 0
+  );
+}
+
+function isInlineWaterfallCodeStep(
+  step: InlineWaterfallSpec['steps'][number],
+): step is Extract<InlineWaterfallSpec['steps'][number], { kind: 'code' }> {
+  return step.kind === 'code';
+}
+
+function isInlineWaterfallToolStep(
+  step: InlineWaterfallSpec['steps'][number],
+): step is Extract<InlineWaterfallSpec['steps'][number], { toolId: string }> {
+  return !isInlineWaterfallCodeStep(step);
+}
+
+function extractInlineWaterfallCodeStepValue(
+  output: string,
+  result: unknown,
+): unknown {
+  if (
+    result &&
+    typeof result === 'object' &&
+    !Array.isArray(result) &&
+    output in result
+  ) {
+    return (result as Record<string, unknown>)[output] ?? null;
+  }
+  return result ?? null;
+}
+
+function isMeaningfulValue(value: unknown): boolean {
+  if (value == null) return false;
+  if (typeof value === 'string') return value.trim().length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === 'object') return Object.keys(value).length > 0;
+  return true;
+}
+
+function getValueAtPath(value: unknown, path: string): unknown {
+  let current = value;
+  for (const part of path.split('.').filter(Boolean)) {
+    if (!current || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+async function extractWaterfallOutputValue(
+  toolId: string,
+  output: string,
+  result: unknown,
+  getToolResultIdentityGetters?: (
+    toolId: string,
+    output: string,
+  ) => Promise<readonly string[]>,
+): Promise<unknown> {
+  const getters = getToolResultIdentityGetters
+    ? await getToolResultIdentityGetters(toolId, output)
+    : [];
+  for (const getter of getters) {
+    const value = getValueAtPath(result, getter);
+    if (isMeaningfulValue(value)) {
+      return value;
+    }
+  }
+
+  const directOutputValue = getValueAtPath(result, output);
+  if (directOutputValue !== undefined) {
+    return isMeaningfulValue(directOutputValue) ? directOutputValue : null;
+  }
+
+  if (output === 'people' || output === 'companies') {
+    if (Array.isArray(result)) return result;
+    const direct = getValueAtPath(result, output);
+    if (Array.isArray(direct)) return direct;
+  }
+
+  return isMeaningfulValue(result) ? result : null;
+}
+
+export class PlayContextImpl {
+  private rowStates = new Map<number, RowState>();
+  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 options: ContextOptions;
+  private logBuffer: string[] = [];
+  private checkpoint: PlayCheckpoint;
+  private steps: PlayStep[] = [];
+  private explicitMapInvocationKeys = new Set<string>();
+  /** The map step currently being built — substeps go here instead of top-level. */
+  private activeMapStep: Extract<PlayStep, { type: 'map' }> | null = null;
+  /** Last completed map step — for post-map recordStep calls (e.g. run_javascript). */
+  private lastMapStep: Extract<PlayStep, { type: 'map' }> | null = null;
+  private pureMapExecutionActive = false;
+  private lastProgressHeartbeatAt = 0;
+  private pendingRowEventBoundaries: Array<{
+    boundaryId: string;
+    eventKey: string;
+    timeoutMs: number;
+  }> = [];
+  private processedRowCount = 0;
+  private directToolCallIndex = 0;
+  private sleepBoundaryIndex = 0;
+  private fetchCallIndex = 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>,
+  };
+
+  tool<TOutput = unknown>(request: ToolExecutionRequest): Promise<TOutput> {
+    return this.tools.execute<TOutput>(request);
+  }
+
+  constructor(options: ContextOptions) {
+    this.options = options;
+    this.rateLimitScheduler = new PlayRateLimitScheduler({
+      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:
+        options.governance?.inFlightPlayCallsByPlayId ?? {},
+    };
+  }
+
+  private durableBoundaryId(localId: string): string {
+    // Durable boundaries live in one checkpoint for the whole root execution.
+    // Nested plays and concurrent child calls therefore need a stable run scope
+    // in the key, otherwise two children can both produce e.g. "sleep-0-25"
+    // and replay the wrong boundary or never observe completion.
+    return `${this.governance.currentRunId}:${localId}`;
+  }
+
+  private emitScopedRowUpdate(
+    key: string | null,
+    tableNamespace: string | null,
+    update: Omit<PlayRowUpdate, 'key'>,
+  ): void {
+    this.progress.rowUpdate(key, tableNamespace, update);
+  }
+
+  private emitExecutionEvent(event: PlayExecutionEvent): void {
+    if (!this.options.onExecutionEvent) {
+      return;
+    }
+    this.progress.executionEvent(event);
+  }
+
+  private normalizeContextKey(key: string, operation: string): string {
+    const normalizedKey = key.trim();
+    if (!normalizedKey) {
+      throw new Error(`ctx.${operation} requires a non-empty key.`);
+    }
+    return normalizedKey;
+  }
+
+  private async getRuntimeStepReceipt(
+    key: string,
+  ): Promise<RuntimeStepReceipt | null> {
+    if (!this.options.getRuntimeStepReceipt) {
+      return null;
+    }
+    const receipt = await this.options.getRuntimeStepReceipt({ key });
+    if (receipt && typeof receipt.key === 'string' && receipt.key.trim()) {
+      return {
+        ...receipt,
+        key: receipt.key.trim(),
+        runId: receipt.runId ?? null,
+      };
+    }
+    return receipt
+      ? {
+          key: key.trim(),
+          status: 'pending',
+        }
+      : null;
+  }
+
+  private async claimRuntimeStepReceipt(
+    key: string,
+    runId: string,
+  ): Promise<RuntimeStepReceipt | null> {
+    if (!this.options.claimRuntimeStepReceipt) {
+      return null;
+    }
+    const claimed = await this.options.claimRuntimeStepReceipt({
+      key,
+      runId,
+    });
+    if (!claimed || typeof claimed.key !== 'string' || !claimed.key.trim()) {
+      return null;
+    }
+    return {
+      ...claimed,
+      key: claimed.key.trim(),
+      runId: claimed.runId ?? null,
+    };
+  }
+
+  private async completeRuntimeStepReceipt(
+    key: string,
+    runId: string,
+    output: unknown | null,
+  ): Promise<RuntimeStepReceipt | null> {
+    if (!this.options.completeRuntimeStepReceipt) {
+      return null;
+    }
+    const completed = await this.options.completeRuntimeStepReceipt({
+      key,
+      runId,
+      output,
+    });
+    if (
+      !completed ||
+      typeof completed.key !== 'string' ||
+      !completed.key.trim()
+    ) {
+      return null;
+    }
+    return {
+      ...completed,
+      key: completed.key.trim(),
+      runId: completed.runId ?? null,
+    };
+  }
+
+  private async failRuntimeStepReceipt(
+    key: string,
+    runId: string,
+    error: string,
+  ): Promise<RuntimeStepReceipt | null> {
+    if (!this.options.failRuntimeStepReceipt) {
+      return null;
+    }
+    const failed = await this.options.failRuntimeStepReceipt({
+      key,
+      runId,
+      error,
+    });
+    if (!failed || typeof failed.key !== 'string' || !failed.key.trim()) {
+      return null;
+    }
+    return {
+      ...failed,
+      key: failed.key.trim(),
+      runId: failed.runId ?? null,
+    };
+  }
+
+  private async executeWithRuntimeReceipt<T>(
+    operation: string,
+    key: string,
+    runId: string,
+    opts: {
+      markSkipped?: (output: T) => Promise<void> | void;
+      execute: () => Promise<T>;
+    },
+  ): Promise<T> {
+    const existing = await this.getRuntimeStepReceipt(key);
+    if (existing?.status === 'completed' || existing?.status === 'skipped') {
+      this.log(`ctx.${operation}(${key}): recovered result from receipt`);
+      if (existing.output === undefined) {
+        return existing.output as T;
+      }
+      if (opts.markSkipped) {
+        await opts.markSkipped(existing.output as T);
+      }
+      return existing.output as T;
+    }
+
+    const claimed = await this.claimRuntimeStepReceipt(key, runId);
+    if (!claimed) {
+      if (existing?.status === 'running' || existing?.status === 'failed') {
+        const runningRun = existing.runId?.trim() ?? 'unknown';
+        if (existing.status === 'running' && existing.runId === runId) {
+          // Fall through and attempt execution; likely a replay of the same run
+          // where row-level checkpoints already recorded but external receipt
+          // state was not visible.
+        } else {
+          throw new Error(
+            `ctx.${operation}(${key}): another run is already executing this key (${runningRun}).`,
+          );
+        }
+      }
+    }
+
+    try {
+      const result = await opts.execute();
+      await this.completeRuntimeStepReceipt(key, runId, result);
+      return result;
+    } catch (error) {
+      await this.failRuntimeStepReceipt(
+        key,
+        runId,
+        this.formatRuntimeError(error),
+      );
+      throw error;
+    }
+  }
+
+  private get currentRunId(): string {
+    return this.options.runId ?? this.governance.currentRunId ?? 'unknown';
+  }
+
+  private emitScopedFieldMetaUpdate(input: {
+    rowId: number;
+    key: string | null;
+    tableNamespace: string | null;
+    fieldName?: string | null;
+    status:
+      | 'queued'
+      | 'running'
+      | 'completed'
+      | 'failed'
+      | 'cached'
+      | 'missed'
+      | 'skipped';
+    rowStatus?: PlayRowUpdate['status'];
+    stage?: string | null;
+    provider?: string | null;
+    error?: string | null;
+    reused?: boolean;
+    dataPatch?: Record<string, unknown>;
+  }): void {
+    this.progress.fieldMetaUpdate(input);
+  }
+
+  private emitCellUpdate(input: {
+    rowId: number;
+    key: string | null;
+    tableNamespace: string | null;
+    columnName: string;
+    status:
+      | 'queued'
+      | 'running'
+      | 'completed'
+      | 'failed'
+      | 'cached'
+      | 'missed'
+      | 'skipped';
+    rowStatus?: PlayRowUpdate['status'];
+    stage?: string | null;
+    provider?: string | null;
+    error?: string | null;
+    value?: unknown;
+  }): void {
+    this.progress.cellUpdate(input);
+  }
+
+  private emitQueuedInlineWaterfallSteps(
+    rowId: number,
+    key: string | null,
+    tableNamespace: string | null,
+    spec: InlineWaterfallSpec,
+  ): void {
+    this.progress.queuedInlineWaterfallSteps({
+      rowId,
+      key,
+      tableNamespace,
+      spec,
+    });
+  }
+
+  private isCompletedFieldValue(value: unknown): boolean {
+    return (
+      value !== null &&
+      value !== undefined &&
+      !(typeof value === 'string' && value.length === 0)
+    );
+  }
+
+  private shouldReuseExistingFieldValue(
+    row: Record<string, unknown>,
+    fieldName: string,
+  ): boolean {
+    return (
+      Object.prototype.hasOwnProperty.call(row, fieldName) &&
+      this.isCompletedFieldValue(row[fieldName])
+    );
+  }
+
+  private toVisibleDataPatch(
+    fields: Record<string, unknown>,
+  ): Record<string, unknown> {
+    return Object.fromEntries(
+      Object.entries(fields).filter(
+        ([fieldName]) => !fieldName.startsWith('_'),
+      ),
+    );
+  }
+
+  private formatRuntimeError(error: unknown): string {
+    if (error instanceof Error) {
+      return error.message;
+    }
+    return String(error);
+  }
+
+  private logWaterfallMatch(input: {
+    queueKey: string;
+    rowId: number;
+    provider: string;
+  }): void {
+    const count = (this.waterfallMatchLogCounts.get(input.queueKey) ?? 0) + 1;
+    this.waterfallMatchLogCounts.set(input.queueKey, count);
+
+    if (count <= WATERFALL_ROW_MATCH_LOG_SAMPLE_LIMIT) {
+      this.log(
+        `    Row ${input.rowId}: found with ${input.provider} (${count}/${WATERFALL_ROW_MATCH_LOG_SAMPLE_LIMIT} sample)`,
+      );
+      if (count === WATERFALL_ROW_MATCH_LOG_SAMPLE_LIMIT) {
+        this.log(
+          `    Further per-row matches for ${input.queueKey} will be summarized every ${WATERFALL_ROW_MATCH_LOG_INTERVAL.toLocaleString()} hits.`,
+        );
+      }
+      return;
+    }
+
+    if (count % WATERFALL_ROW_MATCH_LOG_INTERVAL === 0) {
+      this.log(
+        `    ${count.toLocaleString()} rows matched for ${input.queueKey}; latest row ${input.rowId} with ${input.provider}`,
+      );
+    }
+  }
+
+  private summarizeBatchSizes(sizes: readonly number[]): string {
+    if (sizes.length <= BATCH_SIZE_LOG_SAMPLE_LIMIT) {
+      return sizes.join(', ');
+    }
+    const sample = sizes.slice(0, BATCH_SIZE_LOG_SAMPLE_LIMIT).join(', ');
+    const remaining = sizes.length - BATCH_SIZE_LOG_SAMPLE_LIMIT;
+    return `${sample}, ... +${remaining} more`;
+  }
+
+  private bumpCounter(
+    field:
+      | 'playCallCount'
+      | 'toolCallCount'
+      | 'waterfallStepExecutions'
+      | 'retryCount'
+      | 'descendantCount',
+    amount = 1,
+  ): void {
+    this.governance[field] += amount;
+    const limits = this.governance.limits;
+    if (
+      field === 'playCallCount' &&
+      this.governance.playCallCount > limits.maxPlayCallCount
+    ) {
+      throw new Error(
+        `Root play-call budget exceeded (${this.governance.playCallCount}/${limits.maxPlayCallCount}).`,
+      );
+    }
+    if (
+      field === 'toolCallCount' &&
+      this.governance.toolCallCount > limits.maxToolCallCount
+    ) {
+      throw new Error(
+        `Root tool-call budget exceeded (${this.governance.toolCallCount}/${limits.maxToolCallCount}).`,
+      );
+    }
+    if (
+      field === 'waterfallStepExecutions' &&
+      typeof limits.maxWaterfallStepExecutions === 'number' &&
+      this.governance.waterfallStepExecutions >
+        limits.maxWaterfallStepExecutions
+    ) {
+      throw new Error(
+        `Root waterfall-step budget exceeded (${this.governance.waterfallStepExecutions}/${limits.maxWaterfallStepExecutions}).`,
+      );
+    }
+    if (
+      field === 'retryCount' &&
+      this.governance.retryCount > limits.maxRetryCount
+    ) {
+      throw new Error(
+        `Root retry budget exceeded (${this.governance.retryCount}/${limits.maxRetryCount}).`,
+      );
+    }
+    if (
+      field === 'descendantCount' &&
+      this.governance.descendantCount > limits.maxDescendants
+    ) {
+      throw new Error(
+        `Root descendant budget exceeded (${this.governance.descendantCount}/${limits.maxDescendants}).`,
+      );
+    }
+  }
+
+  private acquirePlayConcurrency(playId: string): void {
+    this.governance.inFlightPlayCalls += 1;
+    const inFlightByPlayId = (this.governance.inFlightPlayCallsByPlayId ??= {});
+    inFlightByPlayId[playId] = (inFlightByPlayId[playId] ?? 0) + 1;
+  }
+
+  private releasePlayConcurrency(playId: string): void {
+    this.governance.inFlightPlayCalls = Math.max(
+      0,
+      this.governance.inFlightPlayCalls - 1,
+    );
+    const inFlightByPlayId = (this.governance.inFlightPlayCallsByPlayId ??= {});
+    const nextPlayCount = Math.max(0, (inFlightByPlayId[playId] ?? 0) - 1);
+    if (nextPlayCount === 0) {
+      delete inFlightByPlayId[playId];
+    } else {
+      inFlightByPlayId[playId] = nextPlayCount;
+    }
+  }
+
+  private assertNoDuplicateConcurrentMapBackedPlay(): void {
+    if (this.governance.callDepth === 0) {
+      return;
+    }
+    const inFlightCount =
+      this.governance.inFlightPlayCallsByPlayId?.[
+        this.governance.currentPlayId
+      ] ?? 0;
+    if (inFlightCount <= 1) {
+      return;
+    }
+    throw new Error(
+      `Concurrent map-backed play call blocked for ${this.governance.currentPlayId}. ` +
+        'A child play that uses ctx.map() cannot run more than once at the same time because its map tables share durable row identity. ' +
+        'Run these child play calls sequentially, or give each concurrent branch a different child play/table contract.',
+    );
+  }
+
+  private acquireToolConcurrency(): void {
+    this.governance.inFlightToolCalls += 1;
+    if (
+      this.governance.inFlightToolCalls >
+      this.governance.limits.maxConcurrentToolCalls
+    ) {
+      this.governance.inFlightToolCalls -= 1;
+      throw new Error(
+        `Concurrent tool-call limit exceeded (${this.governance.limits.maxConcurrentToolCalls}).`,
+      );
+    }
+  }
+
+  private releaseToolConcurrency(): void {
+    this.governance.inFlightToolCalls = Math.max(
+      0,
+      this.governance.inFlightToolCalls - 1,
+    );
+  }
+
+  private getCachedToolResult(
+    toolId: string,
+    rowCacheKey: string,
+  ): ToolBatchResult | undefined {
+    return this.checkpoint.completedToolBatches[toolId]?.[rowCacheKey];
+  }
+
+  private cacheToolResult(
+    toolId: string,
+    rowCacheKey: string,
+    result: unknown | null,
+  ): void {
+    if (!this.checkpoint.completedToolBatches[toolId]) {
+      this.checkpoint.completedToolBatches[toolId] = {};
+    }
+    this.checkpoint.completedToolBatches[toolId]![rowCacheKey] = {
+      done: true,
+      result,
+    };
+  }
+
+  private buildToolResultCacheKey(input: {
+    rowId: number;
+    tableNamespace?: string;
+    rowKey?: string;
+    callId?: string;
+  }): string {
+    const scope = this.governance.currentRunId || this.options.runId || 'run';
+    if (input.callId?.trim()) {
+      return `${scope}:${input.callId.trim()}`;
+    }
+    if (input.rowKey?.trim()) {
+      return `${scope}:${input.rowKey.trim()}`;
+    }
+    if (input.tableNamespace?.trim()) {
+      return `${scope}:${input.tableNamespace.trim()}:${input.rowId}`;
+    }
+    return `${scope}:direct:${input.rowId}`;
+  }
+
+  private async resolveToolResultMetadata(
+    toolId: string,
+  ): Promise<ToolResultMetadataInput> {
+    const metadata = await this.options.getToolResultMetadata?.(toolId);
+    return {
+      toolId,
+      resultIdentityGetters: metadata?.resultIdentityGetters ?? {},
+      listExtractorPaths: metadata?.listExtractorPaths ?? [],
+      listIdentityGetters: metadata?.listIdentityGetters ?? {},
+    };
+  }
+
+  private async wrapToolExecutionResult(input: {
+    toolId: string;
+    status: string;
+    result: unknown;
+    metadata?: ToolResultMetadataInput | null;
+    cached: boolean;
+    source: 'live' | 'checkpoint' | 'cache';
+    cacheKey?: string;
+  }): Promise<ToolExecuteResult> {
+    if (isToolExecuteResult(input.result)) {
+      return cloneToolExecuteResultWithExecution(input.result, {
+        idempotent: true,
+        cached: input.cached,
+        source: input.source,
+        ...(input.cacheKey ? { cacheKey: input.cacheKey } : {}),
+      });
+    }
+    return createToolExecuteResult({
+      status: input.status,
+      result: input.result,
+      metadata:
+        input.metadata ?? (await this.resolveToolResultMetadata(input.toolId)),
+      execution: {
+        idempotent: true,
+        cached: input.cached,
+        source: input.source,
+        ...(input.cacheKey ? { cacheKey: input.cacheKey } : {}),
+      },
+    });
+  }
+
+  private async resolveToolCall(
+    toolId: string,
+    request: ToolCallRequest,
+    result: unknown | null,
+    metadata?: ToolResultMetadataInput | null,
+  ): Promise<void> {
+    const cacheKey = this.buildToolResultCacheKey({
+      rowId: request.rowId,
+      tableNamespace: request.tableNamespace,
+      rowKey: request.rowKey ?? undefined,
+      callId: request.callId,
+    });
+    const wrapped = await this.wrapToolExecutionResult({
+      toolId,
+      status: result == null ? 'no_result' : 'completed',
+      result,
+      metadata,
+      cached: false,
+      source: 'live',
+      cacheKey,
+    });
+    this.cacheToolResult(toolId, cacheKey, wrapped);
+
+    const resolvers = this.toolCallResolvers.get(request.callId);
+    if (resolvers) {
+      for (const resolver of resolvers) {
+        resolver(wrapped);
+      }
+      this.toolCallResolvers.delete(request.callId);
+    }
+
+    this.emitScopedFieldMetaUpdate({
+      rowId: request.rowId,
+      key: request.rowKey ?? null,
+      tableNamespace: request.tableNamespace ?? null,
+      fieldName: request.fieldName,
+      status: 'running',
+      rowStatus: 'running',
+      stage: toolId,
+      provider: null,
+      error: null,
+      dataPatch: {},
+    });
+  }
+
+  private pulseProgressHeartbeat(force = false): void {
+    if (!this.options.onBatchComplete) {
+      return;
+    }
+    const now = Date.now();
+    if (
+      !force &&
+      now - this.lastProgressHeartbeatAt < PROGRESS_HEARTBEAT_INTERVAL_MS
+    ) {
+      return;
+    }
+    this.lastProgressHeartbeatAt = now;
+    this.options.onBatchComplete(this.checkpoint);
+  }
+
+  // ——— Public ctx API ———
+
+  async csv(
+    path: string,
+    _options?: CsvOptions,
+  ): Promise<PlayDataset<Record<string, unknown>>> {
+    void _options;
+    // In cloud mode, CSV data is passed in — path is just a label
+    // The activity loads the actual data before creating the ctx
+    throw new Error(
+      `ctx.csv("${path}") is handled by the workflow. ` +
+        `CSV data is loaded as a Temporal activity and passed to your play via input.`,
+    );
+  }
+
+  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>,
+  ): RuntimeMapBuilder<T>;
+  map<T extends Record<string, unknown>>(
+    key: string,
+    items: PlayDatasetInput<T>,
+    input: RuntimeStepProgram,
+    options?: MapOptions<T>,
+  ): Promise<PlayDataset<Record<string, unknown>>>;
+  map<
+    T extends Record<string, unknown>,
+    TColumns extends Record<string, unknown> = Record<string, unknown>,
+  >(
+    key: string,
+    items: PlayDatasetInput<T>,
+    input?:
+      | MapFieldDefinition<T, TColumns>
+      | RuntimeStepProgram
+      | MapDefinitionOptions<T>,
+    options?: MapOptions<T>,
+  ): RuntimeMapBuilder<T> | Promise<PlayDataset<Record<string, unknown>>> {
+    if (rowContext.getStore()) {
+      throw new Error(
+        'Nested ctx.map() is not supported. Flatten your fields into one map, or keep custom per-row logic inside a single map field.',
+      );
+    }
+    this.assertNoDuplicateConcurrentMapBackedPlay();
+
+    if (input === undefined || isMapDefinitionOptions(input)) {
+      return new RuntimeMapBuilder(
+        this,
+        key,
+        items,
+        input as MapDefinitionOptions<T> | undefined,
+      );
+    }
+
+    if (isRuntimeStepProgram(input)) {
+      return this.runStepProgramMap(key, items, input, options);
+    }
+
+    throw new Error('ctx.map() accepts key, rows, and map options only.');
+  }
+
+  async runStepProgramMap<T extends Record<string, unknown>>(
+    key: string,
+    items: PlayDatasetInput<T>,
+    program: RuntimeStepProgram,
+    options?: MapOptions<T>,
+  ): Promise<PlayDataset<Record<string, unknown>>> {
+    return this.runMapDefinition(
+      key,
+      items,
+      this.stepProgramToMapDefinition(program),
+      options,
+    );
+  }
+
+  private async runMapDefinition<
+    T extends Record<string, unknown>,
+    TColumns extends Record<string, unknown> = Record<string, unknown>,
+  >(
+    key: string,
+    items: PlayDatasetInput<T>,
+    input: MapFieldDefinition<T, TColumns>,
+    options?: MapOptions<T>,
+  ): Promise<PlayDataset<Record<string, unknown>>> {
+    if (rowContext.getStore()) {
+      throw new Error(
+        'Nested ctx.map() is not supported. Flatten your fields into one map, or keep custom per-row logic inside a single map field.',
+      );
+    }
+    this.assertNoDuplicateConcurrentMapBackedPlay();
+
+    const normalizedMapKey = this.normalizeContextKey(key, 'map');
+
+    const normalizedMapNamespace = normalizeTableNamespace(normalizedMapKey);
+    const staleAfterSeconds = options?.staleAfterSeconds ?? null;
+    try {
+      resolveStaleMapTableNamespace(normalizedMapNamespace, staleAfterSeconds);
+    } 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: "..." }).`
+          : `ctx.map() key must normalize to <= ${MAP_KEY_NAMESPACE_MAX_LENGTH} characters.`,
+      );
+    }
+    if (this.explicitMapInvocationKeys.has(normalizedMapNamespace)) {
+      throw new Error(
+        `Duplicate ctx.map() key "${normalizedMapNamespace}" in the same play. ` +
+          'Each ctx.map() call must use a distinct idempotency key.',
+      );
+    }
+    this.explicitMapInvocationKeys.add(normalizedMapNamespace);
+
+    let resolvedTableNamespace = resolveStaleMapTableNamespace(
+      normalizedMapNamespace,
+      staleAfterSeconds,
+    );
+    let totalInputCount = 0;
+    let rawItems: Record<string, unknown>[] = [];
+    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 rowIdentity = (row: Record<string, unknown>, index = 0) =>
+      deriveMapRowIdentity({
+        row,
+        index,
+        artifactTableNamespace: resolvedTableNamespace,
+        fieldNames: mapFieldNames,
+        explicitKey: explicitKeyResolver,
+      });
+
+    const materializedItems = await materializePlayDatasetInput(items);
+    totalInputCount = materializedItems.length;
+    rawItems = materializedItems.map((item) => this.toOutputRow(item));
+    itemsToProcess = materializedItems.map((item) =>
+      this.toOutputRow(item as Record<string, unknown>),
+    );
+
+    assertUniqueExplicitMapKeys({
+      mapNamespace: normalizedMapNamespace,
+      rows: rawItems,
+      resolver: explicitKeyResolver,
+    });
+    if (this.options.onMapStart) {
+      const mapStartResult = await this.options.onMapStart(
+        rawItems,
+        resolvedTableNamespace,
+        {
+          playName: this.options.playName,
+          playId: this.options.playId,
+          runId: this.options.runId,
+          staticPipeline: this.options.staticPipeline,
+        },
+      );
+      resolvedTableNamespace = normalizeTableNamespace(
+        mapStartResult.tableNamespace,
+      );
+      const pendingKeys = new Set(
+        mapStartResult.pendingRows.map((row) => rowIdentity(row)),
+      );
+      itemsToProcess = materializedItems
+        .map((item) => this.toOutputRow(item as Record<string, unknown>))
+        .filter((row) => pendingKeys.has(rowIdentity(row)));
+      if (mapStartResult.completedRows.length > 0) {
+        completedItemsByKey = new Map();
+        for (const row of mapStartResult.completedRows) {
+          const rowKey = rowIdentity(row);
+          if (rowKey) completedItemsByKey.set(rowKey, row);
+        }
+        this.log(
+          `Resuming: ${mapStartResult.completedRows.length} already completed, ${itemsToProcess.length} pending`,
+        );
+      }
+    }
+
+    const mapScope = this.mapRowIdentity.createScope({
+      logicalNamespace: normalizedMapNamespace,
+      artifactTableNamespace: resolvedTableNamespace,
+      explicitKey: explicitKeyResolver,
+      fieldNames: mapFieldNames,
+    });
+    const completedRowKeys =
+      completedItemsByKey != null ? [...completedItemsByKey.keys()] : [];
+    const pendingRowKeys = itemsToProcess.map((item) =>
+      mapScope.rowIdentity(this.toOutputRow(item)),
+    );
+    this.mapFrames.start({
+      scope: mapScope,
+      totalRows: totalInputCount,
+      completedRowKeys,
+      pendingRowKeys,
+    });
+
+    const mapResults = await this.runFieldMap(
+      itemsToProcess,
+      mapScope,
+      input as MapFieldDefinition<Record<string, unknown>>,
+      options?.description,
+      {
+        totalRows: totalInputCount,
+        completedRows: completedItemsByKey?.size ?? 0,
+      },
+    );
+
+    const results =
+      completedItemsByKey && completedItemsByKey.size > 0
+        ? (() => {
+            const resultsByKey = new Map<string, Record<string, unknown>>();
+            for (let index = 0; index < mapResults.length; index += 1) {
+              const row = mapResults[index]!;
+              const rowIdentityRow = this.toOutputRow(
+                itemsToProcess[index] as Record<string, unknown>,
+              );
+              const rowKey = rowIdentity(rowIdentityRow);
+              if (rowKey) resultsByKey.set(rowKey, row);
+            }
+            return rawItems.map((rawItem) => {
+              const rowKey = rowIdentity(rawItem);
+              return (
+                resultsByKey.get(rowKey) ??
+                completedItemsByKey!.get(rowKey) ??
+                rawItem
+              );
+            });
+          })()
+        : mapResults;
+
+    return createDeferredPlayDataset({
+      datasetKind: 'map',
+      datasetId: createRuntimeDatasetId(
+        this.options.playName ?? this.options.playId ?? 'play',
+        resolvedTableNamespace,
+      ),
+      count: results.length,
+      previewRows: results.slice(0, 10),
+      tableNamespace: resolvedTableNamespace,
+      resolvers: {
+        count: async () => results.length,
+        peek: async (limit) => results.slice(0, Math.max(0, limit)),
+        materialize: async (limit) =>
+          limit === undefined
+            ? [...results]
+            : results.slice(0, Math.max(0, limit)),
+        iterate: () =>
+          ({
+            async *[Symbol.asyncIterator]() {
+              for (const row of results) {
+                yield row;
+              }
+            },
+          }) as AsyncIterable<Record<string, unknown>>,
+      },
+    });
+  }
+
+  private async runFieldMap<T extends Record<string, unknown>>(
+    items: T[],
+    mapScope: MapExecutionScope,
+    definition: MapFieldDefinition<T>,
+    description?: string,
+    executionSummary?: {
+      totalRows: number;
+      completedRows: number;
+    },
+    runtimeOptions?: {
+      emitTerminalEvent?: boolean;
+    },
+  ): Promise<Array<Record<string, unknown>>> {
+    const fieldEntries = Object.entries(definition);
+    const mapFieldNames = fieldEntries.map(([fieldName]) => fieldName);
+    const visibleFields = fieldEntries
+      .map(([fieldName]) => fieldName)
+      .filter((fieldName) => !fieldName.startsWith('_'));
+    const normalizedTableNamespace = mapScope.artifactTableNamespace;
+    const rowIdentity = (row: Record<string, unknown>, index = 0) =>
+      mapScope.rowIdentity(
+        Object.fromEntries(
+          Object.entries(row).filter(
+            ([fieldName]) => !mapFieldNames.includes(fieldName),
+          ),
+        ),
+        index,
+      );
+
+    const totalRows = Math.max(
+      executionSummary?.totalRows ?? items.length,
+      items.length,
+    );
+    const completedRows = Math.min(
+      executionSummary?.completedRows ?? 0,
+      totalRows,
+    );
+    const pendingRows = Math.max(0, items.length);
+    const emitTerminalEvent = runtimeOptions?.emitTerminalEvent !== false;
+
+    if (completedRows > 0 || pendingRows !== totalRows) {
+      this.log(
+        `Starting map over ${totalRows} items with ${visibleFields.length} fields (key: ${normalizedTableNamespace}; ${completedRows} already satisfied; ${pendingRows} pending)`,
+      );
+    } else {
+      this.log(
+        `Starting map over ${items.length} items with ${visibleFields.length} fields (key: ${normalizedTableNamespace})`,
+      );
+    }
+    this.processedRowCount = items.length;
+    const mapStep: Extract<PlayStep, { type: 'map' }> = {
+      type: 'map',
+      items: items.length,
+      fields: visibleFields,
+      substeps: [],
+      description: normalizeStepDescription(description),
+    };
+    this.steps.push(mapStep);
+    this.activeMapStep = mapStep;
+
+    const updateMapFrameProgress = (input: {
+      status?: MapExecutionFrame['status'];
+      completedRowKey?: string | null;
+      pendingRowKey?: string | null;
+      activeBoundaryId?: string | null;
+      emitEventType?: PlayExecutionEvent['type'];
+    }) => {
+      this.mapFrames.updateProgress({
+        ...input,
+        scope: mapScope,
+        totalRows,
+      });
+    };
+
+    if (this.canUsePureJsMapFastPath(definition)) {
+      const results = await this.runPureFieldMap(
+        items,
+        fieldEntries,
+        visibleFields,
+        normalizedTableNamespace,
+      );
+      for (const row of results) {
+        updateMapFrameProgress({
+          completedRowKey: rowIdentity(row),
+        });
+      }
+      if (emitTerminalEvent) {
+        updateMapFrameProgress({
+          status: 'completed',
+          activeBoundaryId: null,
+          emitEventType: 'map.completed',
+        });
+      }
+      this.lastMapStep = mapStep;
+      this.activeMapStep = null;
+      this.log(
+        `Map completed: ${results.length + completedRows} results (${results.length} executed, ${completedRows} already satisfied)`,
+      );
+      return results;
+    }
+
+    this.initializeRowStates(items);
+
+    const promises = items.map(async (item, idx) => {
+      const baseRow = this.toOutputRow(item);
+      const rowKey = rowIdentity(baseRow, idx);
+      const computedFields: Record<string, unknown> = {};
+      let activeFieldName: string | null = null;
+
+      try {
+        for (const [fieldName, resolver] of fieldEntries) {
+          activeFieldName = fieldName;
+          if (this.shouldReuseExistingFieldValue(baseRow, fieldName)) {
+            const reusedValue = baseRow[fieldName];
+            computedFields[fieldName] = reusedValue;
+            this.rowStates.get(idx)?.results.set(fieldName, reusedValue);
+            this.emitScopedFieldMetaUpdate({
+              rowId: idx,
+              key: rowKey,
+              tableNamespace: normalizedTableNamespace,
+              fieldName,
+              status: 'cached',
+              reused: true,
+              dataPatch: {},
+            });
+            continue;
+          }
+
+          this.emitScopedFieldMetaUpdate({
+            rowId: idx,
+            key: rowKey,
+            tableNamespace: normalizedTableNamespace,
+            fieldName,
+            status: 'running',
+            rowStatus: 'running',
+            stage: fieldName,
+            dataPatch: {},
+          });
+
+          const value = await rowContext.run(
+            {
+              rowId: idx,
+              fieldName,
+              tableNamespace: normalizedTableNamespace,
+              rowKey,
+              mapScope,
+            },
+            async () =>
+              await this.resolveMapFieldValue(
+                resolver,
+                item,
+                { ...baseRow, ...computedFields },
+                idx,
+              ),
+          );
+          computedFields[fieldName] = value;
+          this.rowStates.get(idx)?.results.set(fieldName, value);
+          this.emitScopedFieldMetaUpdate({
+            rowId: idx,
+            key: rowKey,
+            tableNamespace: normalizedTableNamespace,
+            fieldName,
+            status: 'completed',
+            stage: 'completed',
+            dataPatch: fieldName.startsWith('_') ? {} : { [fieldName]: value },
+          });
+        }
+
+        const merged = { ...baseRow, ...computedFields };
+        activeFieldName = null;
+        updateMapFrameProgress({
+          completedRowKey: rowKey,
+        });
+        this.emitScopedRowUpdate(rowKey, normalizedTableNamespace, {
+          rowId: idx,
+          status: 'completed',
+          stage: 'completed',
+          provider: null,
+          error: null,
+          dataPatch: {},
+        });
+        return Object.fromEntries(
+          Object.entries(merged).filter(
+            ([fieldName]) => !fieldName.startsWith('_'),
+          ),
+        );
+      } catch (error) {
+        if (isPlayRowExecutionSuspendedError(error)) {
+          this.pendingRowEventBoundaries.push(error.boundary);
+          this.rowStates.get(idx)!.status = 'waiting';
+          updateMapFrameProgress({
+            pendingRowKey: rowKey,
+            activeBoundaryId: error.boundary.boundaryId,
+            emitEventType: 'map.suspended',
+          });
+          const fieldName = rowContext.getStore()?.fieldName ?? activeFieldName;
+          this.emitScopedFieldMetaUpdate({
+            rowId: idx,
+            key: rowKey,
+            tableNamespace: normalizedTableNamespace,
+            fieldName,
+            status: 'running',
+            rowStatus: 'running',
+            stage: 'waiting_for_event',
+            provider: null,
+            error: null,
+            dataPatch: {},
+          });
+          return WAITING_ROW;
+        }
+        const fieldName = rowContext.getStore()?.fieldName;
+        updateMapFrameProgress({
+          status: 'failed',
+          emitEventType: 'map.failed',
+        });
+        this.emitScopedFieldMetaUpdate({
+          rowId: idx,
+          key: rowKey,
+          tableNamespace: normalizedTableNamespace,
+          fieldName: fieldName ?? activeFieldName,
+          status: 'failed',
+          rowStatus: 'failed',
+          stage: 'failed',
+          provider: null,
+          error: this.formatRuntimeError(error),
+          dataPatch: {},
+        });
+        throw error;
+      }
+    });
+
+    await this.drainQueuedWork(promises);
+    this.lastMapStep = mapStep;
+    this.activeMapStep = null;
+
+    const settledResults = await Promise.all(promises);
+    if (this.pendingRowEventBoundaries.length > 0) {
+      const completedRowKeys = new Set<string>();
+      for (let index = 0; index < settledResults.length; index += 1) {
+        const result = settledResults[index];
+        const rawItem = this.toOutputRow(
+          items[index] as Record<string, unknown>,
+        );
+        if (result === WAITING_ROW) {
+          const key = rowIdentity(rawItem);
+          if (key) {
+            completedRowKeys.add(key);
+          }
+          continue;
+        }
+        const row = result as Record<string, unknown>;
+        const key = rowIdentity(row);
+        if (key) completedRowKeys.add(key);
+      }
+      this.mapFrames.set({
+        ...(this.checkpoint.mapFrames?.[mapScope.mapInvocationId] ?? {
+          mapInvocationId: mapScope.mapInvocationId,
+          logicalNamespace: mapScope.logicalNamespace,
+          artifactTableNamespace: mapScope.artifactTableNamespace,
+          status: 'suspended' as const,
+          totalRows,
+          completedRowKeys: [...completedRowKeys],
+          pendingRowKeys: items.map((item) =>
+            rowIdentity(this.toOutputRow(item as Record<string, unknown>)),
+          ),
+          startedAt: Date.now(),
+          updatedAt: Date.now(),
+        }),
+        status: 'suspended',
+        completedRowKeys: [...completedRowKeys],
+        updatedAt: Date.now(),
+      });
+      const uniqueBoundaries = [
+        ...new Map(
+          this.pendingRowEventBoundaries.map((boundary) => [
+            boundary.boundaryId,
+            boundary,
+          ]),
+        ).values(),
+      ];
+      this.pendingRowEventBoundaries = [];
+      this.options.onBatchComplete?.(this.checkpoint);
+      throw new PlayExecutionSuspendedError({
+        kind: 'integration_event_batch',
+        boundaries: uniqueBoundaries,
+      });
+    }
+    const results = settledResults.filter(
+      (result): result is Record<string, unknown> => result !== WAITING_ROW,
+    );
+    for (const row of results) {
+      updateMapFrameProgress({
+        completedRowKey: rowIdentity(row),
+      });
+    }
+    if (emitTerminalEvent) {
+      updateMapFrameProgress({
+        status: 'completed',
+        activeBoundaryId: null,
+        emitEventType: 'map.completed',
+      });
+    }
+    this.log(
+      `Map completed: ${results.length + completedRows} results (${results.length} executed, ${completedRows} already satisfied)`,
+    );
+    return results;
+  }
+
+  private stepProgramToMapDefinition(
+    program: RuntimeStepProgram,
+  ): MapFieldDefinition<Record<string, unknown>> {
+    const definition: MapFieldDefinition<Record<string, unknown>> = {};
+    for (const step of program.steps) {
+      const resolver: MapFieldResolver<
+        Record<string, unknown>,
+        Record<string, unknown>
+      > = async (
+        _row: Record<string, unknown>,
+        _ctx: unknown,
+        currentRow: Record<string, unknown>,
+        index: number,
+      ) =>
+        await this.executeStepProgramStep(step, currentRow, index, [step.name]);
+      definition[step.name] = resolver;
+    }
+    Object.defineProperty(definition, STEP_PROGRAM_MAP_DEFINITION, {
+      value: true,
+      enumerable: false,
+    });
+    return definition;
+  }
+
+  private async executeStepProgram(
+    program: RuntimeStepProgram,
+    row: Record<string, unknown>,
+    index: number,
+    path: string[],
+  ): Promise<unknown> {
+    let currentRow = { ...row };
+    const produced: Record<string, unknown> = {};
+    for (const step of program.steps) {
+      const value = await this.executeStepProgramStep(step, currentRow, index, [
+        ...path,
+        step.name,
+      ]);
+      produced[step.name] = value;
+      currentRow = { ...currentRow, [step.name]: value };
+    }
+    if (typeof program.returnResolver === 'function') {
+      return await program.returnResolver(currentRow, this, index);
+    }
+    return produced;
+  }
+
+  private async executeStepProgramStep(
+    step: RuntimeStepProgramStep,
+    currentRow: Record<string, unknown>,
+    index: number,
+    path: string[],
+  ): Promise<unknown> {
+    const resolver = step.resolver;
+    const store = rowContext.getStore();
+    const nestedFieldName = path.join('.');
+    const runWithStepScope = async (run: () => Promise<unknown>) => {
+      if (!store) return await run();
+      return await rowContext.run(
+        {
+          ...store,
+          fieldName: nestedFieldName,
+        },
+        run,
+      );
+    };
+
+    if (isRuntimeStepProgram(resolver)) {
+      return await runWithStepScope(
+        async () =>
+          await this.executeStepProgram(resolver, currentRow, index, path),
+      );
+    }
+
+    if (isRuntimeConditionalStepResolver(resolver)) {
+      const shouldRun = await resolver.when(currentRow, index);
+      if (!shouldRun) {
+        const elseValue = Object.prototype.hasOwnProperty.call(
+          resolver,
+          'elseValue',
+        )
+          ? resolver.elseValue
+          : null;
+        if (store) {
+          this.emitScopedFieldMetaUpdate({
+            rowId: store.rowId,
+            key: store.rowKey ?? null,
+            tableNamespace: store.tableNamespace ?? null,
+            fieldName: nestedFieldName,
+            status: 'skipped',
+            rowStatus: 'running',
+            stage: 'skipped',
+            provider: null,
+            error: null,
+            dataPatch: {},
+          });
+        }
+        return elseValue;
+      }
+      return await runWithStepScope(
+        async () => await resolver.run(currentRow, this, index),
+      );
+    }
+
+    if (typeof resolver !== 'function') {
+      return resolver;
+    }
+
+    return await runWithStepScope(
+      async () => await resolver(currentRow, this, index),
+    );
+  }
+
+  private canUsePureJsMapFastPath<T>(
+    definition: MapFieldDefinition<T>,
+  ): boolean {
+    if (
+      (definition as Record<PropertyKey, unknown>)[STEP_PROGRAM_MAP_DEFINITION]
+    ) {
+      return false;
+    }
+    const toolExecuteMarker = ['.tools', 'execute('].join('.');
+    return Object.values(definition).every((resolver) => {
+      if (typeof resolver !== 'function') {
+        return true;
+      }
+
+      const source = Function.prototype.toString.call(resolver);
+      return (
+        !source.includes(toolExecuteMarker) && !source.includes('.waterfall(')
+      );
+    });
+  }
+
+  private async runPureFieldMap<T>(
+    items: T[],
+    fieldEntries: [string, MapFieldDefinition<T>[string]][],
+    visibleFields: string[],
+    tableNamespace: 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]!;
+        const baseRow = this.toOutputRow(item);
+        const computedFields: Record<string, unknown> = {};
+        let activeFieldName: string | null = null;
+
+        try {
+          for (const [fieldName, resolver] of fieldEntries) {
+            activeFieldName = fieldName;
+            if (this.shouldReuseExistingFieldValue(baseRow, fieldName)) {
+              computedFields[fieldName] = baseRow[fieldName];
+              this.emitScopedRowUpdate(rowIdentity(baseRow), tableNamespace, {
+                rowId: index,
+                status: undefined,
+                stage: null,
+                provider: null,
+                error: null,
+                dataPatch: {},
+                cellMetaPatch: {
+                  [fieldName]: {
+                    status: 'cached',
+                    reused: true,
+                  },
+                },
+              });
+              continue;
+            }
+
+            this.emitScopedRowUpdate(rowIdentity(baseRow), tableNamespace, {
+              rowId: index,
+              status: 'running',
+              stage: fieldName,
+              provider: null,
+              error: null,
+              dataPatch: {},
+              cellMetaPatch: {
+                [fieldName]: {
+                  status: 'running',
+                  stage: fieldName,
+                },
+              },
+            });
+
+            computedFields[fieldName] = await this.resolveMapFieldValue(
+              resolver,
+              item,
+              { ...baseRow, ...computedFields },
+              index,
+            );
+            this.emitScopedRowUpdate(rowIdentity(baseRow), tableNamespace, {
+              rowId: index,
+              status: undefined,
+              stage: 'completed',
+              provider: null,
+              error: null,
+              dataPatch: fieldName.startsWith('_')
+                ? {}
+                : { [fieldName]: computedFields[fieldName] },
+              cellMetaPatch: {
+                [fieldName]: {
+                  status: 'completed',
+                  stage: 'completed',
+                },
+              },
+            });
+          }
+
+          const merged = { ...baseRow, ...computedFields };
+          results.push(
+            Object.fromEntries(
+              Object.entries(merged).filter(
+                ([fieldName]) => !fieldName.startsWith('_'),
+              ),
+            ),
+          );
+
+          const rowKey = rowIdentity(baseRow);
+          activeFieldName = null;
+          this.emitScopedRowUpdate(rowKey, tableNamespace, {
+            rowId: index,
+            status: 'completed',
+            stage: 'completed',
+            provider: null,
+            error: null,
+            dataPatch: {},
+          });
+        } catch (error) {
+          const rowKey = rowIdentity(baseRow);
+          this.emitScopedRowUpdate(rowKey, tableNamespace, {
+            rowId: index,
+            status: 'failed',
+            stage: 'failed',
+            provider: null,
+            error: this.formatRuntimeError(error),
+            dataPatch: {},
+            cellMetaPatch: {
+              [String(activeFieldName ?? '__unknown')]: {
+                status: 'failed',
+                stage: 'failed',
+                error: this.formatRuntimeError(error),
+              },
+            },
+          });
+          throw error;
+        }
+
+        if ((index + 1) % PURE_JS_HEARTBEAT_ROW_INTERVAL === 0) {
+          this.pulseProgressHeartbeat();
+        }
+      }
+    } finally {
+      this.pulseProgressHeartbeat(true);
+      this.pureMapExecutionActive = false;
+    }
+
+    return results;
+  }
+
+  private initializeRowStates<T>(items: T[]): void {
+    items.forEach((item, idx) => {
+      this.rowStates.set(idx, {
+        id: idx,
+        input: item,
+        status: 'pending',
+        waterfalls: new Map(),
+        toolCalls: new Map(),
+        results: new Map(),
+      });
+    });
+  }
+
+  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).
+    // We keep looping until nothing new is queued and all rows finish.
+    //
+    // Important: an unresolved Promise by itself does not keep Node alive. The
+    // play runner is a short-lived child process, so parking on
+    // Promise.allSettled(promises) while there is no timer/socket/file handle can
+    // let Node exit 0 before main() emits the result envelope. That presents as
+    // "Local play runner produced no result" even though the real bug was a
+    // map row waiting for queued tool/waterfall work. Always race row settlement
+    // against a small timer and re-check the queues instead of blocking forever
+    // on promises that may be waiting for this drain loop to do the next batch.
+    const raceSettled = () =>
+      Promise.race([
+        Promise.allSettled(promises).then(() => 'done' as const),
+        new Promise<'pending'>((r) => setTimeout(() => r('pending'), 50)),
+      ]);
+
+    let pass = 0;
+    while (true) {
+      const hasPendingWork =
+        this.waterfallQueue.size > 0 || this.toolCallQueue.length > 0;
+
+      if (!hasPendingWork) {
+        const status = await raceSettled();
+        if (
+          status === 'done' &&
+          this.waterfallQueue.size === 0 &&
+          this.toolCallQueue.length === 0
+        ) {
+          break;
+        }
+
+        // Promises are still running, or they settled while scheduling one last
+        // batch. Give resolver microtasks a turn, then loop back and drain any
+        // newly queued work. This timer is deliberately tiny; it is here for
+        // correctness/liveness, not throughput throttling.
+        await new Promise((r) => setTimeout(r, 10));
+        continue;
+      }
+
+      pass++;
+      this.log(`  Batch pass ${pass}`);
+      this.log(
+        `  Queue depth before drain: waterfalls=${this.waterfallQueue.size} tool_calls=${this.toolCallQueue.length}`,
+      );
+
+      if (this.waterfallQueue.size > 0) {
+        await this.executeBatchedWaterfalls();
+      }
+
+      if (this.toolCallQueue.length > 0) {
+        await this.executeBatchedToolCalls();
+      }
+    }
+  }
+
+  private async resolveMapFieldValue<T>(
+    resolver: MapFieldResolver<T>,
+    row: T,
+    fields: Record<string, unknown>,
+    index: number,
+  ): Promise<unknown> {
+    if (typeof resolver !== 'function') {
+      return resolver;
+    }
+
+    return await resolver(row, this, fields, index);
+  }
+
+  private toOutputRow<T>(item: T): Record<string, unknown> {
+    if (item != null && typeof item === 'object' && !Array.isArray(item)) {
+      return item as Record<string, unknown>;
+    }
+
+    return { value: item };
+  }
+
+  async waterfall(
+    toolNameOrSpec: string | InlineWaterfallSpec,
+    input: Record<string, unknown>,
+    opts?: WaterfallOptions,
+  ): Promise<unknown | null> {
+    const store = rowContext.getStore();
+    const toolName =
+      typeof toolNameOrSpec === 'string' ? toolNameOrSpec : toolNameOrSpec.id;
+    const baseQueueKey =
+      typeof toolNameOrSpec === 'string'
+        ? toolNameOrSpec
+        : `inline:${toolNameOrSpec.id}`;
+    const inlineSpec = isInlineWaterfallSpec(toolNameOrSpec)
+      ? toolNameOrSpec
+      : undefined;
+
+    if (this.pureMapExecutionActive && !store) {
+      throw new Error(
+        'ctx.waterfall() cannot run inside the pure-JS fast path. Call it directly in the map definition so the batching runtime can stay enabled.',
+      );
+    }
+
+    if (!store) {
+      return this.executeWaterfallDirect(toolNameOrSpec, input, opts);
+    }
+
+    const rowId = store.rowId;
+    const fieldName = store.fieldName;
+    const queueKey = store.tableNamespace?.trim()
+      ? `${baseQueueKey}:${store.tableNamespace.trim()}`
+      : baseQueueKey;
+    const rowState = this.rowStates.get(rowId);
+    if (rowState && !rowState.waterfalls.has(toolName)) {
+      rowState.waterfalls.set(toolName, {
+        status: 'pending',
+        providerIndex: 0,
+      });
+    }
+
+    // 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) {
+      this.log(`  Row ${rowId} ${toolName}: recovered from checkpoint`);
+      return resolved.value;
+    }
+
+    return new Promise((resolve) => {
+      const resolverId = `${rowId}-${queueKey}`;
+      this.resolvers.set(resolverId, resolve);
+
+      this.emitScopedFieldMetaUpdate({
+        rowId,
+        key: store?.rowKey ?? null,
+        tableNamespace: store?.tableNamespace ?? null,
+        fieldName,
+        status: 'running',
+        rowStatus: 'running',
+        stage: toolName,
+        provider: null,
+        error: null,
+        dataPatch: {},
+      });
+      if (inlineSpec) {
+        // Inline waterfalls have fully compiled child stages, so we can publish a
+        // real queued state for each step immediately instead of forcing the grid
+        // to guess from the row's broader status.
+        this.emitQueuedInlineWaterfallSteps(
+          rowId,
+          store?.rowKey ?? null,
+          store?.tableNamespace ?? null,
+          inlineSpec,
+        );
+      }
+
+      if (!this.waterfallQueue.has(queueKey)) {
+        this.waterfallQueue.set(queueKey, []);
+      }
+      this.waterfallQueue.get(queueKey)!.push({
+        rowId,
+        fieldName,
+        tableNamespace: store?.tableNamespace,
+        rowKey: store?.rowKey ?? null,
+        key: queueKey,
+        toolName,
+        input,
+        providerIndex: 0,
+        opts,
+        description: normalizeStepDescription(opts?.description),
+        ...(inlineSpec ? { spec: inlineSpec } : {}),
+      });
+    });
+  }
+
+  private async executeTool(request: ToolExecutionRequest): Promise<unknown> {
+    const { tool: toolId, input } = request;
+    const normalizedKey = this.normalizeContextKey(request.id, 'tool');
+
+    const eventWaitHandler =
+      (await this.options.getIntegrationEventWaitHandler?.(toolId)) ?? null;
+    const store = rowContext.getStore();
+
+    const executeTool = async (): Promise<unknown> => {
+      if (eventWaitHandler) {
+        return this.executeIntegrationEventWaitTool(
+          toolId,
+          input,
+          eventWaitHandler,
+        );
+      }
+      if (toolId === 'run_javascript') {
+        throw new Error(DISALLOWED_RUN_JAVASCRIPT_TOOL_MESSAGE);
+      }
+      this.bumpCounter('toolCallCount');
+
+      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.',
+        );
+      }
+
+      if (!store) {
+        const directRowId = -(this.directToolCallIndex + 1);
+        this.directToolCallIndex += 1;
+        const directCacheKey = this.buildToolResultCacheKey({
+          rowId: directRowId,
+        });
+        const cached = this.getCachedToolResult(toolId, directCacheKey);
+        if (cached?.done) {
+          this.log(`Calling tool: ${toolId} recovered from checkpoint`);
+          return await this.wrapToolExecutionResult({
+            toolId,
+            status: cached.result == null ? 'no_result' : 'completed',
+            result: cached.result,
+            cached: true,
+            source: 'checkpoint',
+            cacheKey: directCacheKey,
+          });
+        }
+        this.log(`Calling tool: ${toolId}`);
+        const execution = await this.callToolExecutionAPI(toolId, input);
+        const wrapped = await this.wrapToolExecutionResult({
+          toolId,
+          status: execution.status,
+          result: execution.result,
+          metadata: execution.metadata,
+          cached: false,
+          source: 'live',
+          cacheKey: directCacheKey,
+        });
+        this.checkpoint.completedToolBatches[toolId] = {
+          ...(this.checkpoint.completedToolBatches[toolId] ?? {}),
+          [directCacheKey]: {
+            done: true,
+            result: wrapped,
+          },
+        };
+        this.options.onBatchComplete?.(this.checkpoint);
+        return wrapped;
+      }
+
+      const rowId = store.rowId;
+      const fieldName = store.fieldName;
+      const callId = [
+        store.tableNamespace?.trim() || 'map',
+        store.rowKey?.trim() || String(rowId),
+        fieldName?.trim() || 'field',
+        normalizedKey,
+      ].join(':');
+
+      const cached = this.getCachedToolResult(
+        toolId,
+        this.buildToolResultCacheKey({
+          rowId,
+          tableNamespace: store.tableNamespace,
+          rowKey: store.rowKey,
+          callId,
+        }),
+      );
+      if (cached?.done) {
+        this.log(`  Row ${rowId} ${toolId}: recovered from checkpoint`);
+        return await this.wrapToolExecutionResult({
+          toolId,
+          status: cached.result == null ? 'no_result' : 'completed',
+          result: cached.result,
+          cached: true,
+          source: 'checkpoint',
+          cacheKey: this.buildToolResultCacheKey({
+            rowId,
+            tableNamespace: store.tableNamespace,
+            rowKey: store.rowKey,
+            callId,
+          }),
+        });
+      }
+
+      return new Promise((resolve) => {
+        const existingResolvers = this.toolCallResolvers.get(callId);
+        if (existingResolvers) {
+          existingResolvers.push(resolve);
+          return;
+        }
+        this.toolCallResolvers.set(callId, [resolve]);
+        this.emitScopedFieldMetaUpdate({
+          rowId,
+          key: store.rowKey ?? null,
+          tableNamespace: store.tableNamespace ?? null,
+          fieldName,
+          status: 'running',
+          rowStatus: 'running',
+          stage: toolId,
+          provider: null,
+          error: null,
+          dataPatch: {},
+        });
+        this.toolCallQueue.push({
+          callId,
+          rowId,
+          fieldName,
+          toolId,
+          input,
+          tableNamespace: store.tableNamespace,
+          rowKey: store.rowKey ?? null,
+          description: normalizeStepDescription(request.description),
+        });
+      });
+    };
+
+    if (store) {
+      return await executeTool();
+    }
+
+    return this.executeWithRuntimeReceipt(
+      'tool',
+      normalizedKey,
+      this.currentRunId,
+      {
+        markSkipped: () => {
+          this.log(
+            `ctx.tools.execute({ id: ${normalizedKey}, tool: ${toolId} }): no-op due completed receipt`,
+          );
+        },
+        execute: executeTool,
+      },
+    );
+  }
+
+  private async executeIntegrationEventWaitTool(
+    toolId: string,
+    input: Record<string, unknown>,
+    handler: IntegrationEventWaitHandler,
+  ): Promise<unknown> {
+    if (!this.options.durableBoundaries) {
+      throw new Error(`${toolId} requires durable play boundaries.`);
+    }
+
+    const rowScope = rowContext.getStore();
+    const eventContext = {
+      playId: this.options.playId,
+      runId: this.options.runId,
+      workflowId: this.options.workflowId,
+      orgId: this.options.orgId,
+      executorToken: this.options.executorToken,
+    };
+    const basePreparedBoundary = await handler.prepare({
+      payload: input,
+      context: eventContext,
+    });
+    const preparedBoundary = rowScope
+      ? {
+          ...basePreparedBoundary,
+          boundaryId: `map-row-${stableFetchHash(
+            JSON.stringify({
+              tableNamespace: rowScope.tableNamespace,
+              rowKey: rowScope.rowKey,
+              fieldName: rowScope.fieldName,
+              boundaryId: basePreparedBoundary.boundaryId,
+              eventKey: basePreparedBoundary.eventKey,
+            }),
+          )}`,
+        }
+      : basePreparedBoundary;
+
+    const existing =
+      this.checkpoint.resolvedBoundaries?.[preparedBoundary.boundaryId];
+    if (existing?.kind === 'integration_event' && 'output' in existing) {
+      this.log(
+        `Integration event ${preparedBoundary.boundaryId}: recovered response from checkpoint`,
+      );
+      return existing.output;
+    }
+
+    const boundary = await handler.arm({
+      payload: input,
+      context: eventContext,
+      boundary: preparedBoundary,
+    });
+
+    this.log(
+      `Armed ${handler.provider} integration event wait: ${boundary.eventKey}`,
+    );
+    this.checkpoint.resolvedBoundaries = {
+      ...(this.checkpoint.resolvedBoundaries ?? {}),
+      [boundary.boundaryId]: {
+        kind: 'integration_event',
+        eventKey: boundary.eventKey,
+        timeoutMs: boundary.timeoutMs,
+        provider: boundary.provider,
+        toolId: boundary.toolId,
+        ...(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 } : {}),
+      },
+    };
+    this.options.onBatchComplete?.(this.checkpoint);
+
+    if (rowScope) {
+      throw new PlayRowExecutionSuspendedError({
+        boundaryId: boundary.boundaryId,
+        eventKey: boundary.eventKey,
+        timeoutMs: boundary.timeoutMs,
+      });
+    }
+
+    throw new PlayExecutionSuspendedError({
+      kind: 'integration_event',
+      boundaryId: boundary.boundaryId,
+      eventKey: boundary.eventKey,
+      timeoutMs: boundary.timeoutMs,
+    });
+  }
+
+  async runPlay(
+    key: string,
+    playRef: string | { playName?: string; name?: string },
+    input: Record<string, unknown>,
+    options?: PlayCallOptions,
+  ): Promise<unknown> {
+    const normalizedKey = this.normalizeContextKey(key, 'runPlay');
+    const resolvedName =
+      typeof playRef === 'string'
+        ? playRef
+        : typeof playRef.playName === 'string'
+          ? playRef.playName
+          : (playRef.name ?? '');
+
+    if (!resolvedName.trim()) {
+      throw new Error('ctx.runPlay(...) requires a resolvable play name.');
+    }
+
+    if (!this.options.resolvePlay) {
+      throw new Error(
+        'ctx.runPlay(...) is unavailable because no play resolver was configured.',
+      );
+    }
+
+    if (this.governance.ancestryPlayIds.includes(resolvedName)) {
+      const chain = [...this.governance.ancestryPlayIds, resolvedName].join(
+        ' -> ',
+      );
+      throw new Error(`Recursive play graph detected: ${chain}`);
+    }
+
+    const nextDepth = this.governance.callDepth + 1;
+    if (nextDepth > this.governance.limits.maxPlayCallDepth) {
+      throw new Error(
+        `Play-call depth exceeded (${nextDepth}/${this.governance.limits.maxPlayCallDepth}) while calling ${resolvedName}.`,
+      );
+    }
+
+    const parentKey = this.governance.currentPlayId;
+    const nextParentCalls =
+      (this.governance.parentChildCalls[parentKey] ?? 0) + 1;
+    if (nextParentCalls > this.governance.limits.maxChildPlayCallsPerParent) {
+      throw new Error(
+        `Child play-call cap exceeded for ${parentKey} (${nextParentCalls}/${this.governance.limits.maxChildPlayCallsPerParent}).`,
+      );
+    }
+
+    const executePlayCall = async (): Promise<unknown> => {
+      this.bumpCounter('playCallCount');
+      this.bumpCounter('descendantCount');
+      this.governance.parentChildCalls[parentKey] = nextParentCalls;
+      this.acquirePlayConcurrency(resolvedName);
+
+      try {
+        const resolvePlay = this.options.resolvePlay;
+        if (!resolvePlay) {
+          throw new Error(
+            'ctx.runPlay(...) is unavailable because no play resolver was configured.',
+          );
+        }
+        const resolvedPlay = await resolvePlay(resolvedName);
+        if (!resolvedPlay) {
+          throw new Error(
+            `Unable to resolve play "${resolvedName}" for ctx.runPlay(...).`,
+          );
+        }
+
+        const childGovernance: PlayExecutionGovernanceState = {
+          ...this.governance,
+          currentPlayId: resolvedName,
+          currentRunId: `${this.governance.rootRunId}:${resolvedName}:${this.governance.playCallCount}`,
+          ancestryPlayIds: [...this.governance.ancestryPlayIds, resolvedName],
+          ancestryRunIds: [
+            ...this.governance.ancestryRunIds,
+            `${this.governance.rootRunId}:${resolvedName}:${this.governance.playCallCount}`,
+          ],
+          callDepth: nextDepth,
+        };
+        const childContext = createPlayContext({
+          ...this.options,
+          playId: resolvedName,
+          playName: resolvedName,
+          runId: childGovernance.currentRunId,
+          staticPipeline: resolvedPlay.staticPipeline ?? null,
+          checkpoint: this.checkpoint,
+          governance: childGovernance,
+          getRuntimeStepReceipt: undefined,
+          claimRuntimeStepReceipt: undefined,
+          completeRuntimeStepReceipt: undefined,
+          failRuntimeStepReceipt: undefined,
+          skipRuntimeStepReceipt: undefined,
+        });
+        const childExecution = this.executeResolvedPlay(
+          resolvedPlay,
+          childContext,
+          input,
+        );
+        await childContext.drainQueuedWork([childExecution]);
+        const result = await childExecution;
+        const step = {
+          type: 'play_call' as const,
+          playId: resolvedName,
+          nestedSteps: childContext.getSteps(),
+          description: normalizeStepDescription(options?.description),
+        };
+        if (this.activeMapStep) {
+          this.activeMapStep.substeps.push(step);
+        } else {
+          this.steps.push(step);
+        }
+        return result;
+      } finally {
+        this.releasePlayConcurrency(resolvedName);
+      }
+    };
+
+    if (rowContext.getStore()) {
+      return await executePlayCall();
+    }
+
+    return this.executeWithRuntimeReceipt<unknown>(
+      'runPlay',
+      normalizedKey,
+      this.currentRunId,
+      {
+        markSkipped: () => {
+          this.log(
+            `ctx.runPlay(${normalizedKey}): no-op due completed receipt`,
+          );
+        },
+        execute: executePlayCall,
+      },
+    );
+  }
+
+  /**
+   * Extract a list from a tool result.
+   * e.g. ctx.extractList(result, 'people', ['first_name', 'last_name', 'email'])
+   */
+  extractList(
+    result: unknown,
+    listPath: string,
+    fields?: string[],
+  ): Record<string, unknown>[] {
+    if (result == null || typeof result !== 'object') return [];
+
+    let list: unknown = result;
+    for (const key of listPath.split('.')) {
+      if (list == null || typeof list !== 'object') return [];
+      list = (list as Record<string, unknown>)[key];
+    }
+
+    if (!Array.isArray(list)) return [];
+
+    if (!fields || fields.length === 0) {
+      return list.filter(
+        (item): item is Record<string, unknown> =>
+          item != null && typeof item === 'object',
+      );
+    }
+
+    return list
+      .filter(
+        (item): item is Record<string, unknown> =>
+          item != null && typeof item === 'object',
+      )
+      .map((item) => {
+        const picked: Record<string, unknown> = {};
+        for (const field of fields) {
+          if (field in item) picked[field] = item[field];
+        }
+        return picked;
+      });
+  }
+
+  log(msg: string): void {
+    const line = `[${new Date().toISOString()}] ${msg}`;
+    this.logBuffer.push(line);
+    this.options.onLog?.(line);
+    if (this.options.verbose) console.log(line);
+  }
+
+  async sleep(ms: number): Promise<void> {
+    if (this.options.durableBoundaries) {
+      const delayMs = Math.max(0, Math.round(ms));
+      const boundaryId = this.durableBoundaryId(
+        `sleep-${this.sleepBoundaryIndex}-${delayMs}`,
+      );
+      this.sleepBoundaryIndex += 1;
+      const existing = this.checkpoint.resolvedBoundaries?.[boundaryId];
+      if (existing?.kind === 'sleep' && existing.completedAt !== undefined) {
+        return;
+      }
+      this.checkpoint.resolvedBoundaries = {
+        ...(this.checkpoint.resolvedBoundaries ?? {}),
+        [boundaryId]: {
+          kind: 'sleep',
+          delayMs,
+        },
+      };
+      this.options.onBatchComplete?.(this.checkpoint);
+      throw new PlayExecutionSuspendedError({
+        kind: 'sleep',
+        boundaryId,
+        delayMs,
+      });
+    }
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  async fetch(
+    key: string,
+    input: string | URL,
+    init: RequestInit = {},
+  ): Promise<PlayFetchResponse> {
+    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.',
+      );
+    }
+
+    return this.executeWithRuntimeReceipt<PlayFetchResponse>(
+      'fetch',
+      normalizedKey,
+      this.currentRunId,
+      {
+        execute: async () => {
+          const url = input.toString();
+          const method = (init.method ?? 'GET').toUpperCase();
+          const headers = normalizeFetchHeaders(init.headers);
+          const boundaryId = this.durableBoundaryId(
+            `fetch-${this.fetchCallIndex}-${stableFetchHash(
+              JSON.stringify({
+                url,
+                method,
+                headers,
+                body: typeof init.body === 'string' ? init.body : null,
+              }),
+            )}`,
+          );
+          this.fetchCallIndex += 1;
+
+          const existing = this.checkpoint.resolvedBoundaries?.[boundaryId];
+          if (existing?.kind === 'fetch' && 'output' in existing) {
+            this.log(`ctx.fetch(${url}): recovered response from checkpoint`);
+            return existing.output as PlayFetchResponse;
+          }
+
+          if (!['GET', 'HEAD', 'OPTIONS'].includes(method)) {
+            const hasIdempotencyKey =
+              headers['idempotency-key'] !== undefined ||
+              headers['x-idempotency-key'] !== undefined;
+            if (!hasIdempotencyKey) {
+              throw new Error(
+                `ctx.fetch(${method} ${url}) needs an Idempotency-Key header. Durable plays can replay after waits/retries; add an idempotency key or wrap the side effect in a Deepline integration tool.`,
+              );
+            }
+          }
+
+          const response = await fetch(url, init);
+          const bodyText = await response.text();
+          const output: PlayFetchResponse = {
+            ok: response.ok,
+            status: response.status,
+            statusText: response.statusText,
+            url: response.url,
+            headers: Object.fromEntries(response.headers.entries()),
+            bodyText,
+            json: parseJsonOrNull(bodyText),
+          };
+
+          this.checkpoint.resolvedBoundaries = {
+            ...(this.checkpoint.resolvedBoundaries ?? {}),
+            [boundaryId]: {
+              kind: 'fetch',
+              url,
+              method,
+              output,
+              completedAt: Date.now(),
+            },
+          };
+          this.options.onBatchComplete?.(this.checkpoint);
+          return output;
+        },
+        markSkipped: (output) => {
+          this.log(
+            `ctx.fetch(${output?.url ?? ''}): no-op due completed receipt`,
+          );
+        },
+      },
+    );
+  }
+
+  async step<T>(key: string, run: () => T | Promise<T>): Promise<T> {
+    const normalizedKey = this.normalizeContextKey(key, 'step');
+    if (!normalizedKey.trim()) {
+      throw new Error('ctx.step(key, fn) requires a non-empty stable step id.');
+    }
+
+    const rowStore = rowContext.getStore();
+    const scope = rowStore
+      ? `row-${rowStore.tableNamespace?.trim() || 'map'}:${rowStore.rowKey?.trim() || String(rowStore.rowId)}`
+      : 'workflow';
+    const callIndexKey = `${scope}:${normalizedKey}`;
+    const callIndex = this.stepCallIndexByKey.get(callIndexKey) ?? 0;
+    this.stepCallIndexByKey.set(callIndexKey, callIndex + 1);
+    const boundarySuffix = callIndex === 0 ? '' : `:${callIndex}`;
+    const boundaryId = this.durableBoundaryId(
+      `step-${scope}:${normalizedKey}${boundarySuffix}`,
+    );
+    const executeStep = async (): Promise<T> => {
+      const existing = this.checkpoint.resolvedBoundaries?.[boundaryId];
+      if (existing?.kind === 'step' && 'output' in existing) {
+        this.log(
+          `ctx.step(${normalizedKey}): recovered result from checkpoint`,
+        );
+        return existing.output as T;
+      }
+
+      const output = await run();
+      assertJsonSerializableStepOutput(normalizedKey, output);
+      this.checkpoint.resolvedBoundaries = {
+        ...(this.checkpoint.resolvedBoundaries ?? {}),
+        [boundaryId]: {
+          kind: 'step',
+          stepId: normalizedKey,
+          output,
+          completedAt: Date.now(),
+        },
+      };
+      this.options.onBatchComplete?.(this.checkpoint);
+      return output;
+    };
+
+    if (rowStore) {
+      return await executeStep();
+    }
+
+    return this.executeWithRuntimeReceipt<T>(
+      'step',
+      normalizedKey,
+      this.currentRunId,
+      {
+        markSkipped: (output) => {
+          this.log(`ctx.step(${normalizedKey}): no-op due completed receipt`);
+          assertJsonSerializableStepOutput(normalizedKey, output);
+        },
+        execute: executeStep,
+      },
+    );
+  }
+
+  getLogs(): string[] {
+    return this.logBuffer;
+  }
+
+  getCheckpoint(): PlayCheckpoint {
+    return this.checkpoint;
+  }
+
+  getSteps(): PlayStep[] {
+    return this.steps;
+  }
+
+  recordStep(step: PlayStep): void {
+    const isSubstepType =
+      step.type === 'waterfall' ||
+      step.type === 'tool' ||
+      step.type === 'run_javascript';
+    const targetMap = this.activeMapStep ?? this.lastMapStep;
+    if (targetMap && isSubstepType) {
+      targetMap.substeps.push(step);
+    } else {
+      this.steps.push(step);
+    }
+  }
+
+  recordReturn(outputRows: number): void {
+    this.lastMapStep = null; // No more substeps expected
+    this.steps.push({ type: 'return', outputRows });
+  }
+
+  getStats(): Record<string, unknown> {
+    const stats: Record<
+      string,
+      { total: number; complete: number; failed: number }
+    > = {};
+    for (const [, rowState] of this.rowStates) {
+      for (const [toolName, wState] of rowState.waterfalls) {
+        if (!stats[toolName])
+          stats[toolName] = { total: 0, complete: 0, failed: 0 };
+        stats[toolName].total++;
+        if (wState.status === 'complete') stats[toolName].complete++;
+        if (wState.status === 'failed') stats[toolName].failed++;
+      }
+    }
+    return {
+      rowsProcessed: Math.max(this.rowStates.size, this.processedRowCount),
+      waterfalls: stats,
+    };
+  }
+
+  // ——— Batched waterfall execution (the core engine) ———
+
+  private async executeBatchedWaterfalls(): Promise<void> {
+    const queuedWaterfalls = this.waterfallQueue;
+    this.waterfallQueue = new Map();
+    this.log(`Executing batched waterfalls for ${queuedWaterfalls.size} tools`);
+
+    for (const [queueKey, requests] of queuedWaterfalls) {
+      const inlineSpec = requests[0]?.spec;
+      if (inlineSpec) {
+        await this.executeInlineWaterfall(queueKey, inlineSpec, requests);
+        continue;
+      }
+
+      const toolName = requests[0]?.toolName ?? queueKey;
+      const providers = requests[0]?.opts?.providers ?? [
+        'hunter',
+        'leadmagic',
+        'pdl',
+        'dropcontact',
+        'prospeo',
+      ];
+
+      this.log(
+        `Processing waterfall ${toolName}: ${requests.length} rows, providers: ${providers.join(', ')}`,
+      );
+
+      if (!this.checkpoint.resolvedWaterfalls[queueKey]) {
+        this.checkpoint.resolvedWaterfalls[queueKey] = {};
+      }
+
+      await executeWaterfallProviders<WaterfallRequest, unknown>({
+        providers,
+        getPendingRequests: () =>
+          requests.filter((req) => {
+            const wState = this.rowStates
+              .get(req.rowId)
+              ?.waterfalls.get(toolName);
+            return wState?.status === 'pending';
+          }),
+        getCachedResults: (provider) => {
+          const batchKey = `${queueKey}:${provider}`;
+          const recovered = this.waterfallReplay.readProviderBatch({
+            batchKey,
+            requests,
+          });
+          if (recovered) {
+            this.log(`  ${provider}: skipping (recovered from checkpoint)`);
+          }
+          return recovered;
+        },
+        storeCachedResults: (provider, results) => {
+          const batchKey = `${queueKey}:${provider}`;
+          this.waterfallReplay.writeProviderBatch(batchKey, results);
+        },
+        executeProviderRequests: async (provider, pending) => {
+          const providerToolId = resolveWaterfallToolId(provider, toolName);
+          const strategy =
+            this.options.getBatchOperationStrategy?.(providerToolId) ?? null;
+          this.log(`  ${provider}: ${pending.length} pending rows`);
+          this.bumpCounter('retryCount', pending.length);
+
+          if (strategy) {
+            const compiledBatches = compileRequestsWithStrategy({
+              requests: pending,
+              strategy,
+              getPayload: (request: WaterfallRequest) => request.input,
+            });
+            const flattenedResults: Array<{
+              request: WaterfallRequest;
+              result: unknown | null;
+            }> = [];
+
+            await executeChunkedRequests({
+              requests: compiledBatches,
+              batchSize:
+                compiledBatches.length > 0
+                  ? await this.rateLimitScheduler.getSuggestedParallelism(
+                      compiledBatches[0]!.batchOperation,
+                      4,
+                    )
+                  : 4,
+              execute: async (batch) =>
+                await this.callToolAPI(
+                  batch.batchOperation,
+                  batch.batchPayload,
+                ),
+              onChunkComplete: async (chunkResults) => {
+                for (const entry of chunkResults) {
+                  const splitResults =
+                    entry.result != null
+                      ? entry.request.splitResults(entry.result)
+                      : entry.request.memberRequests.map(() => null);
+
+                  for (
+                    let index = 0;
+                    index < entry.request.memberRequests.length;
+                    index += 1
+                  ) {
+                    flattenedResults.push({
+                      request: entry.request.memberRequests[index]!,
+                      result: splitResults[index] ?? null,
+                    });
+                  }
+                }
+                this.options.onBatchComplete?.(this.checkpoint);
+              },
+            });
+
+            return flattenedResults;
+          }
+
+          const chunkResults: Array<{
+            request: WaterfallRequest;
+            result: unknown | null;
+          }> = [];
+          await executeChunkedRequests<WaterfallRequest, unknown>({
+            requests: pending,
+            batchSize: await this.rateLimitScheduler.getSuggestedParallelism(
+              providerToolId,
+              50,
+            ),
+            execute: async (request) =>
+              await this.callToolAPI(providerToolId, request.input),
+            onChunkComplete: async (results) => {
+              chunkResults.push(...results);
+              this.options.onBatchComplete?.(this.checkpoint);
+            },
+          });
+          return chunkResults;
+        },
+        onHit: (provider, request, result) => {
+          this.resolveWaterfall(
+            queueKey,
+            toolName,
+            request.rowId,
+            result,
+            provider,
+            request.rowKey ?? null,
+            request.tableNamespace ?? null,
+            request.fieldName,
+          );
+        },
+        onMiss: (_provider, request) => {
+          const wState = this.rowStates
+            .get(request.rowId)
+            ?.waterfalls.get(toolName);
+          if (wState) wState.providerIndex++;
+          this.log(`    Row ${request.rowId}: miss`);
+        },
+        onProviderComplete: () => {
+          this.options.onBatchComplete?.(this.checkpoint);
+        },
+      });
+
+      const stepResults: PlayStepRowResult[] = requests.map((req) => {
+        const wState = this.rowStates.get(req.rowId)?.waterfalls.get(toolName);
+        const success = wState?.status === 'complete';
+        return {
+          rowId: req.rowId,
+          status: success ? 'completed' : 'missed',
+          success,
+          value: wState?.result,
+          error: success ? null : (wState?.error ?? null),
+        };
+      });
+      const waterfallStep = {
+        type: 'waterfall' as const,
+        tool: toolName,
+        providers,
+        results: stepResults,
+        description: normalizeStepDescription(requests[0]?.description),
+      };
+      if (this.activeMapStep) {
+        this.activeMapStep.substeps.push(waterfallStep);
+      } else {
+        this.steps.push(waterfallStep);
+      }
+
+      for (const req of requests) {
+        const wState = this.rowStates.get(req.rowId)?.waterfalls.get(toolName);
+        if (wState?.status === 'pending') {
+          wState.status = 'failed';
+          wState.error = 'All providers exhausted';
+          this.waterfallReplay.setResolved(queueKey, req, null);
+
+          const resolver = this.resolvers.get(`${req.rowId}-${queueKey}`);
+          if (resolver) {
+            resolver(null);
+            this.resolvers.delete(`${req.rowId}-${queueKey}`);
+          }
+          this.emitScopedFieldMetaUpdate({
+            rowId: req.rowId,
+            key: req.rowKey ?? null,
+            tableNamespace: req.tableNamespace ?? null,
+            fieldName: req.fieldName,
+            status: 'failed',
+            rowStatus: 'running',
+            stage: toolName,
+            provider: null,
+            error: 'All providers exhausted',
+            dataPatch: {},
+          });
+          this.log(`    Row ${req.rowId}: all providers exhausted`);
+        }
+      }
+    }
+  }
+
+  private async executeInlineWaterfall(
+    queueKey: string,
+    spec: InlineWaterfallSpec,
+    requests: WaterfallRequest[],
+  ): Promise<void> {
+    if (!this.checkpoint.resolvedWaterfalls[queueKey]) {
+      this.checkpoint.resolvedWaterfalls[queueKey] = {};
+    }
+
+    const pendingRows = new Set<number>(
+      requests
+        .filter(
+          (req) =>
+            this.rowStates.get(req.rowId)?.waterfalls.get(spec.id)?.status ===
+            'pending',
+        )
+        .map((req) => req.rowId),
+    );
+    const resultsByRow = new Map<number, unknown[]>();
+    const stepResults: Array<{
+      id: string;
+      kind?: 'tool' | 'code';
+      toolId?: string;
+      results: PlayStepRowResult[];
+    }> = [];
+    const stepColumnNames = spec.steps.map((s) =>
+      sqlSafePlayColumnName(`${spec.id}.${s.id}`),
+    );
+    const resolvedInChunkRowIds = new Set<number>();
+    let stepIdx = 0;
+
+    for (const step of spec.steps) {
+      const stepColumnName = sqlSafePlayColumnName(`${spec.id}.${step.id}`);
+      const stepProvider = isInlineWaterfallToolStep(step)
+        ? step.toolId
+        : 'code';
+      if (pendingRows.size === 0) {
+        const skippedResults: PlayStepRowResult[] = requests.map((request) => {
+          this.emitCellUpdate({
+            rowId: request.rowId,
+            key: request.rowKey ?? null,
+            tableNamespace: request.tableNamespace ?? null,
+            columnName: stepColumnName,
+            status: 'skipped',
+            stage: step.id,
+            provider: stepProvider,
+            value: null,
+          });
+          return {
+            rowId: request.rowId,
+            status: 'skipped',
+            success: false,
+            value: null,
+            error: null,
+          };
+        });
+        stepResults.push({
+          id: step.id,
+          kind: isInlineWaterfallCodeStep(step) ? 'code' : 'tool',
+          toolId: stepProvider,
+          results: skippedResults,
+        });
+        stepIdx++;
+        continue;
+      }
+      this.bumpCounter('waterfallStepExecutions', pendingRows.size);
+      const pendingRowIds = new Set<number>(pendingRows);
+      const stepRequests = requests.filter((req) =>
+        pendingRowIds.has(req.rowId),
+      );
+      const perRowResultsByRowId = new Map<number, PlayStepRowResult>();
+      if (isInlineWaterfallCodeStep(step)) {
+        this.log(
+          `  Inline waterfall ${spec.id} -> ${step.id}: ${stepRequests.length} pending rows (code)`,
+        );
+        await executeChunkedRequests<WaterfallRequest, unknown>({
+          requests: stepRequests,
+          batchSize: await this.rateLimitScheduler.getSuggestedParallelism(
+            `code:${spec.id}:${step.id}`,
+            20,
+          ),
+          execute: async (request) => {
+            const codeStepCtx = {
+              tools: {
+                execute: async (request: ToolExecutionRequest) =>
+                  await this.callToolAPI(request.tool, request.input),
+              },
+            };
+            return await step.run(request.input, codeStepCtx);
+          },
+          onChunkComplete: async (chunkResults) => {
+            for (const entry of chunkResults) {
+              const matchedValue = extractInlineWaterfallCodeStepValue(
+                spec.output,
+                entry.result,
+              );
+              const bucket = resultsByRow.get(entry.request.rowId) ?? [];
+              const nextBucket = Array.isArray(matchedValue)
+                ? [...bucket, ...matchedValue]
+                : matchedValue != null
+                  ? [...bucket, matchedValue]
+                  : bucket;
+              resultsByRow.set(entry.request.rowId, nextBucket);
+              const satisfied = nextBucket.length >= spec.minResults;
+              perRowResultsByRowId.set(entry.request.rowId, {
+                rowId: entry.request.rowId,
+                status: matchedValue != null ? 'completed' : 'missed',
+                success: matchedValue != null,
+                value: matchedValue,
+                provider: matchedValue != null ? 'code' : undefined,
+                error: null,
+              });
+              if (satisfied) {
+                const finalValue =
+                  spec.minResults === 1 ? (nextBucket[0] ?? null) : nextBucket;
+                this.resolveWaterfall(
+                  queueKey,
+                  spec.id,
+                  entry.request.rowId,
+                  finalValue,
+                  'code',
+                  entry.request.rowKey ?? null,
+                  entry.request.tableNamespace ?? null,
+                  entry.request.fieldName,
+                );
+                pendingRows.delete(entry.request.rowId);
+                this.emitCellUpdate({
+                  rowId: entry.request.rowId,
+                  key: entry.request.rowKey ?? null,
+                  tableNamespace: entry.request.tableNamespace ?? null,
+                  columnName: stepColumnName,
+                  status: 'completed',
+                  stage: step.id,
+                  provider: 'code',
+                  value: matchedValue,
+                });
+                for (let ri = stepIdx + 1; ri < spec.steps.length; ri++) {
+                  const skippedStep = spec.steps[ri]!;
+                  this.emitCellUpdate({
+                    rowId: entry.request.rowId,
+                    key: entry.request.rowKey ?? null,
+                    tableNamespace: entry.request.tableNamespace ?? null,
+                    columnName: stepColumnNames[ri]!,
+                    status: 'skipped',
+                    stage: skippedStep.id,
+                    provider: isInlineWaterfallToolStep(skippedStep)
+                      ? skippedStep.toolId
+                      : 'code',
+                    value: null,
+                  });
+                }
+                resolvedInChunkRowIds.add(entry.request.rowId);
+              }
+            }
+            this.options.onBatchComplete?.(this.checkpoint);
+          },
+        });
+      } else {
+        const strategy =
+          this.options.getBatchOperationStrategy?.(step.toolId) ?? null;
+        this.log(
+          `  Inline waterfall ${spec.id} -> ${step.id}: ${stepRequests.length} pending rows`,
+        );
+        for (const request of stepRequests) {
+          this.emitCellUpdate({
+            rowId: request.rowId,
+            key: request.rowKey ?? null,
+            tableNamespace: request.tableNamespace ?? null,
+            columnName: stepColumnName,
+            status: 'running',
+            stage: step.id,
+            provider: step.toolId,
+            value: null,
+          });
+        }
+
+        if (strategy) {
+          const compiledBatches = compileRequestsWithStrategy({
+            requests: stepRequests,
+            strategy,
+            getPayload: (request: WaterfallRequest) =>
+              step.mapInput(request.input),
+          });
+          this.log(
+            `    ${step.toolId}: compiled ${compiledBatches.length} batch request(s)` +
+              ` (${this.summarizeBatchSizes(
+                compiledBatches.map((batch) => batch.memberRequests.length),
+              )})`,
+          );
+          await executeChunkedRequests({
+            requests: compiledBatches,
+            batchSize:
+              compiledBatches.length > 0
+                ? await this.rateLimitScheduler.getSuggestedParallelism(
+                    compiledBatches[0]!.batchOperation,
+                    4,
+                  )
+                : 4,
+            execute: async (batch) =>
+              await this.callToolAPI(batch.batchOperation, batch.batchPayload),
+            onChunkComplete: async (chunkResults) => {
+              for (const entry of chunkResults) {
+                const splitResults =
+                  entry.result != null
+                    ? entry.request.splitResults(entry.result)
+                    : entry.request.memberRequests.map(() => null);
+                for (
+                  let index = 0;
+                  index < entry.request.memberRequests.length;
+                  index += 1
+                ) {
+                  const request = entry.request.memberRequests[index]!;
+                  const rawResult = splitResults[index] ?? null;
+                  const matchedValue = await extractWaterfallOutputValue(
+                    step.toolId,
+                    spec.output,
+                    rawResult,
+                    this.options.getToolResultIdentityGetters,
+                  );
+                  const bucket = resultsByRow.get(request.rowId) ?? [];
+                  const nextBucket = Array.isArray(matchedValue)
+                    ? [...bucket, ...matchedValue]
+                    : matchedValue != null
+                      ? [...bucket, matchedValue]
+                      : bucket;
+                  resultsByRow.set(request.rowId, nextBucket);
+                  const satisfied = nextBucket.length >= spec.minResults;
+                  perRowResultsByRowId.set(request.rowId, {
+                    rowId: request.rowId,
+                    status: matchedValue != null ? 'completed' : 'missed',
+                    success: matchedValue != null,
+                    value: matchedValue,
+                    provider: matchedValue != null ? step.toolId : undefined,
+                    error: null,
+                  });
+                  if (satisfied) {
+                    const finalValue =
+                      spec.minResults === 1
+                        ? (nextBucket[0] ?? null)
+                        : nextBucket;
+                    this.resolveWaterfall(
+                      queueKey,
+                      spec.id,
+                      request.rowId,
+                      finalValue,
+                      step.toolId,
+                      request.rowKey ?? null,
+                      request.tableNamespace ?? null,
+                      request.fieldName,
+                    );
+                    pendingRows.delete(request.rowId);
+                    this.emitCellUpdate({
+                      rowId: request.rowId,
+                      key: request.rowKey ?? null,
+                      tableNamespace: request.tableNamespace ?? null,
+                      columnName: stepColumnNames[stepIdx]!,
+                      status: 'completed',
+                      stage: step.id,
+                      provider: step.toolId,
+                      value: matchedValue,
+                    });
+                    for (let ri = stepIdx + 1; ri < spec.steps.length; ri++) {
+                      const skippedStep = spec.steps[ri]!;
+                      this.emitCellUpdate({
+                        rowId: request.rowId,
+                        key: request.rowKey ?? null,
+                        tableNamespace: request.tableNamespace ?? null,
+                        columnName: stepColumnNames[ri]!,
+                        status: 'skipped',
+                        stage: skippedStep.id,
+                        provider: isInlineWaterfallToolStep(skippedStep)
+                          ? skippedStep.toolId
+                          : 'code',
+                        value: null,
+                      });
+                    }
+                    resolvedInChunkRowIds.add(request.rowId);
+                  }
+                }
+              }
+              this.options.onBatchComplete?.(this.checkpoint);
+            },
+          });
+        } else {
+          this.log(
+            `    ${step.toolId}: executing ${stepRequests.length} unbatched request(s)`,
+          );
+          await executeChunkedRequests<WaterfallRequest, unknown>({
+            requests: stepRequests,
+            batchSize: await this.rateLimitScheduler.getSuggestedParallelism(
+              step.toolId,
+              50,
+            ),
+            execute: async (request) =>
+              await this.callToolAPI(step.toolId, step.mapInput(request.input)),
+            onChunkComplete: async (chunkResults) => {
+              for (const entry of chunkResults) {
+                const matchedValue = await extractWaterfallOutputValue(
+                  step.toolId,
+                  spec.output,
+                  entry.result,
+                  this.options.getToolResultIdentityGetters,
+                );
+                const bucket = resultsByRow.get(entry.request.rowId) ?? [];
+                const nextBucket = Array.isArray(matchedValue)
+                  ? [...bucket, ...matchedValue]
+                  : matchedValue != null
+                    ? [...bucket, matchedValue]
+                    : bucket;
+                resultsByRow.set(entry.request.rowId, nextBucket);
+                const satisfied = nextBucket.length >= spec.minResults;
+                perRowResultsByRowId.set(entry.request.rowId, {
+                  rowId: entry.request.rowId,
+                  status: matchedValue != null ? 'completed' : 'missed',
+                  success: matchedValue != null,
+                  value: matchedValue,
+                  provider: matchedValue != null ? step.toolId : undefined,
+                  error: null,
+                });
+                if (satisfied) {
+                  const finalValue =
+                    spec.minResults === 1
+                      ? (nextBucket[0] ?? null)
+                      : nextBucket;
+                  this.resolveWaterfall(
+                    queueKey,
+                    spec.id,
+                    entry.request.rowId,
+                    finalValue,
+                    step.toolId,
+                    entry.request.rowKey ?? null,
+                    entry.request.tableNamespace ?? null,
+                    entry.request.fieldName,
+                  );
+                  pendingRows.delete(entry.request.rowId);
+                  this.emitCellUpdate({
+                    rowId: entry.request.rowId,
+                    key: entry.request.rowKey ?? null,
+                    tableNamespace: entry.request.tableNamespace ?? null,
+                    columnName: stepColumnNames[stepIdx]!,
+                    status: 'completed',
+                    stage: step.id,
+                    provider: step.toolId,
+                    value: matchedValue,
+                  });
+                  for (let ri = stepIdx + 1; ri < spec.steps.length; ri++) {
+                    const skippedStep = spec.steps[ri]!;
+                    this.emitCellUpdate({
+                      rowId: entry.request.rowId,
+                      key: entry.request.rowKey ?? null,
+                      tableNamespace: entry.request.tableNamespace ?? null,
+                      columnName: stepColumnNames[ri]!,
+                      status: 'skipped',
+                      stage: skippedStep.id,
+                      provider: isInlineWaterfallToolStep(skippedStep)
+                        ? skippedStep.toolId
+                        : 'code',
+                      value: null,
+                    });
+                  }
+                  resolvedInChunkRowIds.add(entry.request.rowId);
+                }
+              }
+              this.options.onBatchComplete?.(this.checkpoint);
+            },
+          });
+        }
+      }
+
+      const perRowResults: PlayStepRowResult[] = requests.map((request) => {
+        if (resolvedInChunkRowIds.has(request.rowId)) {
+          const existing = perRowResultsByRowId.get(request.rowId);
+          return (
+            existing ?? {
+              rowId: request.rowId,
+              status: 'completed' as const,
+              success: true,
+              value: null,
+              error: null,
+            }
+          );
+        }
+        const existing = perRowResultsByRowId.get(request.rowId);
+        if (existing) {
+          this.emitCellUpdate({
+            rowId: request.rowId,
+            key: request.rowKey ?? null,
+            tableNamespace: request.tableNamespace ?? null,
+            columnName: stepColumnName,
+            status: existing.status,
+            stage: step.id,
+            provider: existing.provider ?? stepProvider,
+            error: existing.error ?? null,
+            value: existing.value ?? null,
+          });
+          return existing;
+        }
+        if (!pendingRowIds.has(request.rowId)) {
+          this.emitCellUpdate({
+            rowId: request.rowId,
+            key: request.rowKey ?? null,
+            tableNamespace: request.tableNamespace ?? null,
+            columnName: stepColumnName,
+            status: 'skipped',
+            stage: step.id,
+            provider: stepProvider,
+            value: null,
+          });
+          return {
+            rowId: request.rowId,
+            status: 'skipped',
+            success: false,
+            value: null,
+            error: null,
+          };
+        }
+        this.emitCellUpdate({
+          rowId: request.rowId,
+          key: request.rowKey ?? null,
+          tableNamespace: request.tableNamespace ?? null,
+          columnName: stepColumnName,
+          status: 'missed',
+          stage: step.id,
+          provider: stepProvider,
+          value: null,
+        });
+        return {
+          rowId: request.rowId,
+          status: 'missed',
+          success: false,
+          value: null,
+          error: null,
+        };
+      });
+
+      stepResults.push({
+        id: step.id,
+        kind: isInlineWaterfallCodeStep(step) ? 'code' : 'tool',
+        toolId: stepProvider,
+        // Persist only a bounded preview in the in-memory execution trace.
+        // The authoritative per-row state already lives in Neon/live progress.
+        results: compactRowResultsPreview(perRowResults),
+      });
+      stepIdx++;
+    }
+
+    for (const req of requests) {
+      const wState = this.rowStates.get(req.rowId)?.waterfalls.get(spec.id);
+      if (wState?.status === 'pending') {
+        wState.status = 'failed';
+        wState.error = 'All waterfall steps exhausted';
+        this.waterfallReplay.setResolved(queueKey, req, null);
+        const resolver = this.resolvers.get(`${req.rowId}-${queueKey}`);
+        if (resolver) {
+          resolver(null);
+          this.resolvers.delete(`${req.rowId}-${queueKey}`);
+        }
+      }
+    }
+
+    const groupResults: PlayStepRowResult[] = requests.map((req) => {
+      const wState = this.rowStates.get(req.rowId)?.waterfalls.get(spec.id);
+      const success = wState?.status === 'complete';
+      return {
+        rowId: req.rowId,
+        status: success ? 'completed' : 'missed',
+        success,
+        value: wState?.result,
+        error: success ? null : (wState?.error ?? null),
+      };
+    });
+
+    const waterfallStep = {
+      type: 'waterfall' as const,
+      id: spec.id,
+      output: spec.output,
+      minResults: spec.minResults,
+      steps: stepResults,
+      results: compactRowResultsPreview(groupResults),
+      description: normalizeStepDescription(requests[0]?.description),
+    };
+    if (this.activeMapStep) {
+      this.activeMapStep.substeps.push(waterfallStep);
+    } else {
+      this.steps.push(waterfallStep);
+    }
+  }
+
+  private resolveWaterfall(
+    queueKey: string,
+    toolName: string,
+    rowId: number,
+    result: unknown,
+    provider: string,
+    rowKey: string | null,
+    tableNamespace: string | null,
+    fieldName?: string,
+  ): void {
+    const wState = this.rowStates.get(rowId)?.waterfalls.get(toolName);
+    if (!wState || wState.status !== 'pending') return;
+
+    wState.status = 'complete';
+    wState.result = result;
+    this.waterfallReplay.setResolved(
+      queueKey,
+      {
+        rowId,
+        rowKey,
+      },
+      result,
+    );
+
+    const resolver = this.resolvers.get(`${rowId}-${queueKey}`);
+    if (resolver) {
+      resolver(result);
+      this.resolvers.delete(`${rowId}-${queueKey}`);
+    }
+    this.emitScopedFieldMetaUpdate({
+      rowId,
+      key: rowKey,
+      tableNamespace,
+      fieldName,
+      status: 'running',
+      rowStatus: 'running',
+      stage: toolName,
+      provider,
+      error: null,
+      dataPatch: {},
+    });
+    this.logWaterfallMatch({ queueKey, rowId, provider });
+  }
+
+  // ——— Batched tool call execution ———
+
+  private async executeBatchedToolCalls(): Promise<void> {
+    const queuedToolCalls = this.toolCallQueue;
+    this.toolCallQueue = [];
+
+    // Group by toolId
+    const byTool = new Map<string, ToolCallRequest[]>();
+    for (const req of queuedToolCalls) {
+      if (!byTool.has(req.toolId)) byTool.set(req.toolId, []);
+      byTool.get(req.toolId)!.push(req);
+    }
+
+    await Promise.all(
+      [...byTool.entries()].map(async ([toolId, requests]) => {
+        this.log(`Executing tool batch ${toolId}: ${requests.length} calls`);
+
+        const pendingRequests: ToolCallRequest[] = [];
+        for (const req of requests) {
+          const cached = this.getCachedToolResult(
+            toolId,
+            this.buildToolResultCacheKey({
+              rowId: req.rowId,
+              tableNamespace: req.tableNamespace,
+              rowKey: req.rowKey ?? undefined,
+              callId: req.callId,
+            }),
+          );
+          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);
+              }
+              this.toolCallResolvers.delete(req.callId);
+            }
+          } else {
+            pendingRequests.push(req);
+          }
+        }
+
+        if (pendingRequests.length > 0) {
+          const strategy =
+            this.options.getBatchOperationStrategy?.(toolId) ?? null;
+
+          if (strategy) {
+            const compiledBatches = compileRequestsWithStrategy({
+              requests: pendingRequests,
+              strategy,
+              getPayload: (request: ToolCallRequest) => request.input,
+            });
+
+            await executeChunkedRequests({
+              requests: compiledBatches,
+              batchSize:
+                compiledBatches.length > 0
+                  ? await this.rateLimitScheduler.getSuggestedParallelism(
+                      compiledBatches[0]!.batchOperation,
+                      4,
+                    )
+                  : 4,
+              execute: async (batch) =>
+                await this.callToolAPI(
+                  batch.batchOperation,
+                  batch.batchPayload,
+                ),
+              onChunkComplete: async (chunkResults) => {
+                for (const entry of chunkResults) {
+                  const splitResults =
+                    entry.result != null
+                      ? entry.request.splitResults(entry.result)
+                      : entry.request.memberRequests.map(() => null);
+
+                  for (
+                    let index = 0;
+                    index < entry.request.memberRequests.length;
+                    index += 1
+                  ) {
+                    const request = entry.request.memberRequests[index]!;
+                    await this.resolveToolCall(
+                      toolId,
+                      request,
+                      splitResults[index] ?? null,
+                    );
+                  }
+                }
+
+                this.options.onBatchComplete?.(this.checkpoint);
+              },
+            });
+          } else {
+            await executeChunkedRequests<
+              ToolCallRequest,
+              ToolExecutionResponse
+            >({
+              requests: pendingRequests,
+              batchSize: await this.rateLimitScheduler.getSuggestedParallelism(
+                toolId,
+                50,
+              ),
+              execute: async (request) =>
+                await this.callToolExecutionAPI(toolId, request.input),
+              onChunkComplete: async (chunkResults) => {
+                for (const entry of chunkResults) {
+                  await this.resolveToolCall(
+                    toolId,
+                    entry.request,
+                    entry.result?.result ?? null,
+                    entry.result?.metadata ?? null,
+                  );
+                }
+
+                this.options.onBatchComplete?.(this.checkpoint);
+              },
+            });
+          }
+        }
+
+        // Record step — nest under map if inside one
+        const stepResults: PlayStepRowResult[] = requests.map((req) => {
+          const cachedResult = this.getCachedToolResult(
+            toolId,
+            this.buildToolResultCacheKey({
+              rowId: req.rowId,
+              tableNamespace: req.tableNamespace,
+              rowKey: req.rowKey ?? undefined,
+              callId: req.callId,
+            }),
+          );
+          return {
+            rowId: req.rowId,
+            status: cachedResult?.result != null ? 'completed' : 'failed',
+            success: cachedResult?.result != null,
+            value: cachedResult?.result,
+            error: cachedResult?.result != null ? null : 'Tool call failed',
+          };
+        });
+        const toolStep = {
+          type: 'tool' as const,
+          toolId,
+          // Keep the step trace preview-sized for large map pages.
+          results: compactRowResultsPreview(stepResults),
+          description: normalizeStepDescription(requests[0]?.description),
+        };
+        if (this.activeMapStep) {
+          this.activeMapStep.substeps.push(toolStep);
+        } else {
+          this.steps.push(toolStep);
+        }
+      }),
+    );
+  }
+
+  private async executeResolvedPlay(
+    resolvedPlay: ResolvedPlayExecution,
+    ctx: PlayContextImpl,
+    input: Record<string, unknown>,
+  ): Promise<unknown> {
+    if (resolvedPlay.definition) {
+      if (!this.options.executeStructuredPlayDefinition) {
+        throw new Error(
+          `Play "${resolvedPlay.playId}" is a structured play, but this runtime did not provide a structured play executor.`,
+        );
+      }
+      return await this.options.executeStructuredPlayDefinition({
+        definition: resolvedPlay.definition,
+        ctx,
+        rows: [],
+        playInput: input,
+      });
+    }
+
+    if (resolvedPlay.codeFormat === 'cjs_module') {
+      const artifact = resolvedPlay.artifact;
+      if (!artifact) {
+        throw new Error(
+          `Play "${resolvedPlay.playId}" is missing a bundled artifact.`,
+        );
+      }
+      const runtimeModule =
+        (await import('node:module')) as unknown as typeof import('node:module') & {
+          Module: typeof import('node:module').Module & {
+            _nodeModulePaths: (from: string) => string[];
+          };
+        };
+      const compiled = new runtimeModule.Module(artifact.virtualFilename);
+      compiled.filename = artifact.virtualFilename;
+      compiled.paths = runtimeModule.Module._nodeModulePaths(process.cwd());
+      (
+        compiled as import('node:module').Module & {
+          _compile: (code: string, filename: string) => void;
+        }
+      )._compile(artifact.bundledCode, artifact.virtualFilename);
+      const candidate =
+        typeof compiled.exports === 'function'
+          ? compiled.exports
+          : (compiled.exports as { default?: unknown }).default;
+      if (typeof candidate !== 'function') {
+        throw new Error(
+          `Play "${resolvedPlay.playId}" does not export a callable default.`,
+        );
+      }
+      return await (
+        candidate as (
+          ctx: unknown,
+          runtimeInput: Record<string, unknown>,
+        ) => Promise<unknown>
+      )(ctx, input);
+    }
+
+    const code = resolvedPlay.code ?? resolvedPlay.sourceCode;
+    if (!code?.trim()) {
+      throw new Error(
+        `Play "${resolvedPlay.playId}" is missing executable source.`,
+      );
+    }
+    return await new Function(
+      'ctx',
+      'input',
+      `
+      const __playFn = ${code};
+      return __playFn(ctx, input);
+    `,
+    )(ctx, input);
+  }
+
+  // ——— Direct execution (outside map context) ———
+
+  private async executeWaterfallDirect(
+    toolNameOrSpec: string | InlineWaterfallSpec,
+    input: Record<string, unknown>,
+    opts?: WaterfallOptions,
+  ): Promise<unknown | null> {
+    if (isInlineWaterfallSpec(toolNameOrSpec)) {
+      this.log(`Direct inline waterfall: ${toolNameOrSpec.id}`);
+      const collected: unknown[] = [];
+      for (const step of toolNameOrSpec.steps) {
+        this.bumpCounter('waterfallStepExecutions');
+        const matched = isInlineWaterfallCodeStep(step)
+          ? extractInlineWaterfallCodeStepValue(
+              toolNameOrSpec.output,
+              await step.run(input, {
+                tools: {
+                  execute: async (request: ToolExecutionRequest) =>
+                    await this.callToolAPI(request.tool, request.input),
+                },
+              }),
+            )
+          : await extractWaterfallOutputValue(
+              step.toolId,
+              toolNameOrSpec.output,
+              await this.callToolAPI(step.toolId, step.mapInput(input)),
+              this.options.getToolResultIdentityGetters,
+            );
+        if (Array.isArray(matched)) {
+          collected.push(...matched);
+        } else if (matched != null) {
+          collected.push(matched);
+        }
+        if (collected.length >= toolNameOrSpec.minResults) {
+          return toolNameOrSpec.minResults === 1
+            ? (collected[0] ?? null)
+            : collected;
+        }
+      }
+      return null;
+    }
+
+    const toolName = toolNameOrSpec;
+    this.log(`Direct waterfall: ${toolName}`);
+    const providers = opts?.providers ?? ['hunter', 'leadmagic', 'pdl'];
+
+    for (const provider of providers) {
+      this.log(`  Trying ${provider}`);
+      try {
+        this.bumpCounter('retryCount');
+        const result = await this.callToolAPI(
+          resolveWaterfallToolId(provider, toolName),
+          input,
+        );
+        if (
+          result != null &&
+          typeof result === 'object' &&
+          Object.keys(result as object).length > 0
+        ) {
+          this.log(`  Found with ${provider}`);
+          return result;
+        }
+      } catch {
+        this.log(`  Failed with ${provider}`);
+      }
+    }
+
+    this.log(`  All providers exhausted`);
+    return null;
+  }
+
+  private async callToolAPI(
+    toolId: string,
+    input: Record<string, unknown>,
+  ): Promise<unknown> {
+    return (await this.callToolExecutionAPI(toolId, input)).result;
+  }
+
+  private async callToolExecutionAPI(
+    toolId: string,
+    input: Record<string, unknown>,
+  ): Promise<ToolExecutionResponse> {
+    if (!this.options.executorToken || !this.options.baseUrl) {
+      throw new Error(
+        'executorToken and baseUrl are required for tool API calls (cloud execution only)',
+      );
+    }
+    const url = `${this.options.baseUrl}/api/v2/integrations/${encodeURIComponent(toolId)}/execute`;
+
+    this.acquireToolConcurrency();
+    try {
+      return await withActiveSpan(
+        'plays.tool.execute',
+        {
+          tracer: 'deepline.plays',
+          attributes: {
+            'plays.play_name': this.options.playId ?? 'anonymous-play',
+            'plays.workflow_id': this.options.workflowId ?? '',
+            'plays.run_id': this.options.runId ?? this.options.workflowId ?? '',
+            'plays.tool_id': toolId,
+          },
+        },
+        async (span) =>
+          await this.rateLimitScheduler.run(toolId, async () => {
+            let rateLimitAttempt = 0;
+
+            while (true) {
+              const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                  'Content-Type': 'application/json',
+                  Authorization: `Bearer ${this.options.executorToken}`,
+                  [EXECUTE_TOOL_METADATA_HEADER]: 'true',
+                },
+                body: JSON.stringify({ payload: input }),
+              });
+
+              span.setAttribute('plays.http_status_code', response.status);
+
+              if (response.status === 429) {
+                rateLimitAttempt += 1;
+                this.bumpCounter('retryCount');
+                const retryAfterMs = parseRetryAfterMs(
+                  response.headers.get('retry-after'),
+                );
+                span.setAttribute(
+                  'plays.rate_limit_retry_after_ms',
+                  retryAfterMs,
+                );
+                span.setAttribute('plays.rate_limit_attempt', rateLimitAttempt);
+                this.log(
+                  `Tool ${toolId} rate limited; retrying after ${retryAfterMs}ms`,
+                );
+                await this.sleepWithCheckpointHeartbeat(retryAfterMs);
+                continue;
+              }
+
+              if (!response.ok) {
+                const text = await response.text();
+                if (
+                  isRetryableTransientToolHttpStatus(toolId, response.status) &&
+                  rateLimitAttempt + 1 < TOOL_TRANSIENT_HTTP_MAX_ATTEMPTS
+                ) {
+                  rateLimitAttempt += 1;
+                  this.bumpCounter('retryCount');
+                  const retryAfterMs = parseRetryAfterMs(
+                    response.headers.get('retry-after'),
+                  );
+                  span.setAttribute(
+                    'plays.transient_http_retry_after_ms',
+                    retryAfterMs,
+                  );
+                  span.setAttribute(
+                    'plays.transient_http_attempt',
+                    rateLimitAttempt,
+                  );
+                  this.log(
+                    `Tool ${toolId} returned ${response.status}; retrying after ${retryAfterMs}ms`,
+                  );
+                  await this.sleepWithCheckpointHeartbeat(retryAfterMs);
+                  continue;
+                }
+                const failureDetail = (() => {
+                  try {
+                    const parsed = JSON.parse(text) as Record<string, unknown>;
+                    const detail =
+                      typeof parsed.message === 'string'
+                        ? parsed.message
+                        : typeof parsed.error === 'string'
+                          ? parsed.error
+                          : text;
+                    const code =
+                      typeof parsed.code === 'string'
+                        ? ` code=${parsed.code}`
+                        : '';
+                    const requestId =
+                      typeof parsed.request_id === 'string'
+                        ? ` requestId=${parsed.request_id}`
+                        : typeof parsed.requestId === 'string'
+                          ? ` requestId=${parsed.requestId}`
+                          : '';
+                    return `${detail}${code}${requestId}`;
+                  } catch {
+                    return text;
+                  }
+                })();
+                const message = `Tool ${toolId} failed (${response.status}): ${failureDetail}`;
+                this.log(message);
+                throw new Error(message);
+              }
+
+              const data = (await response.json()) as Record<string, unknown>;
+              const normalized = normalizePlayToolResult(data.result ?? data);
+              const status =
+                typeof data.status === 'string'
+                  ? data.status
+                  : normalized == null
+                    ? 'no_result'
+                    : 'completed';
+              setSpanAttributes(span, {
+                'plays.tool_result_kind':
+                  normalized == null
+                    ? 'null'
+                    : Array.isArray(normalized)
+                      ? 'array'
+                      : typeof normalized,
+              });
+              return {
+                status,
+                result: normalized,
+                metadata: parseExecuteToolMetadata(toolId, data),
+              };
+            }
+          }),
+      );
+    } finally {
+      this.releaseToolConcurrency();
+    }
+  }
+
+  private async sleepWithCheckpointHeartbeat(ms: number): Promise<void> {
+    const waitMs = Math.max(1, Math.ceil(ms));
+    const startedAt = Date.now();
+
+    while (Date.now() - startedAt < waitMs) {
+      this.options.onBatchComplete?.(this.checkpoint);
+      const remainingMs = waitMs - (Date.now() - startedAt);
+      await new Promise((resolve) =>
+        setTimeout(
+          resolve,
+          Math.min(TOOL_RETRY_HEARTBEAT_INTERVAL_MS, Math.max(1, remainingMs)),
+        ),
+      );
+    }
+
+    this.options.onBatchComplete?.(this.checkpoint);
+  }
+}
+
+export function createPlayContext(options: ContextOptions): PlayContextImpl {
+  return new PlayContextImpl(options);
+}