deepline 0.1.12 → 0.1.19

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

@@ -1,4242 +0,0 @@
-/**
- * PlayContextImpl — the cloud execution engine.
- *
- * Batching model:
- * 1. ctx.map("table_key", rows, { field: resolver }) starts all row field resolvers concurrently
- * 2. ctx.waterfall() calls inside field resolvers QUEUE requests (don't execute)
- * 3. ctx.tools.execute() 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 {
-  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,
-  derivePlayRowIdentityFromKey,
-  MAP_KEY_NAMESPACE_MAX_LENGTH,
-  normalizeTableNamespace,
-  resolveStaleMapTableNamespace,
-} from '@shared_libs/plays/row-identity';
-import { cloneCsvAliasedRow, stripCsvProjectedFields } from './csv-rename';
-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,
-  MapOptions,
-  ToolCallRequest,
-  ToolBatchResult,
-  ContextOptions,
-  PlayCallOptions,
-  PlayCheckpoint,
-  PlayStep,
-  PlayStepRowResult,
-  PlayRowUpdate,
-  MapFieldDefinition,
-  MapFieldResolver,
-  ToolCallOptions,
-  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 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'
-  );
-}
-
-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>,
-  ) {}
-
-  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?: MapOptions<T>): Promise<PlayDataset<Record<string, unknown>>> {
-    return this.ctx.runStepProgramMap(
-      this.key,
-      this.items,
-      this.program,
-      options,
-    );
-  }
-}
-
-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 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 cloneMapFrame(frame: MapExecutionFrame): MapExecutionFrame {
-  return {
-    ...frame,
-    completedRowKeys: [...frame.completedRowKeys],
-    pendingRowKeys: [...frame.pendingRowKeys],
-  };
-}
-
-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, (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 mapInvocationIndex = 0;
-  private readonly stepCallIndexByKey = new Map<string, number>();
-  private readonly waterfallMatchLogCounts = new Map<string, number>();
-  private readonly rateLimitScheduler: PlayRateLimitScheduler;
-  private readonly governance: PlayExecutionGovernanceState;
-  readonly tools = {
-    execute: <TOutput = unknown>(
-      requestOrKey:
-        | {
-            id: string;
-            tool: string;
-            input: Record<string, unknown>;
-            description?: string;
-          }
-        | string,
-      toolId?: string,
-      input?: Record<string, unknown>,
-      options?: ToolCallOptions,
-    ): Promise<TOutput> => {
-      if (typeof requestOrKey === 'object') {
-        return this.executeTool(
-          requestOrKey.id,
-          requestOrKey.tool,
-          requestOrKey.input,
-          requestOrKey.description
-            ? { description: requestOrKey.description }
-            : undefined,
-        ) as Promise<TOutput>;
-      }
-      if (!toolId || !input) {
-        throw new Error(
-          'ctx.tools.execute(key, toolId, input) requires a tool ID and input.',
-        );
-      }
-      return this.executeTool(
-        requestOrKey,
-        toolId,
-        input,
-        options,
-      ) as Promise<TOutput>;
-    },
-  };
-
-  tool<TOutput = unknown>(
-    key: string,
-    toolId: string,
-    input: Record<string, unknown>,
-    options?: ToolCallOptions,
-  ): Promise<TOutput> {
-    return this.tools.execute<TOutput>(key, toolId, input, options);
-  }
-
-  constructor(options: ContextOptions) {
-    this.options = options;
-    this.rateLimitScheduler = new PlayRateLimitScheduler({
-      getQueueHints: options.getToolQueueHints,
-    });
-    this.checkpoint = options.checkpoint ?? emptyCheckpoint();
-    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 {
-    const rowScope = rowContext.getStore()?.mapScope;
-    if (rowScope && key) {
-      this.emitExecutionEvent({
-        type: 'map.row.updated',
-        mapInvocationId: rowScope.mapInvocationId,
-        mapNodeId: rowScope.mapNodeId ?? null,
-        logicalNamespace: rowScope.logicalNamespace,
-        artifactTableNamespace: rowScope.artifactTableNamespace,
-        rowKey: key,
-        rowStatus: update.status,
-        fieldName: rowContext.getStore()?.fieldName ?? null,
-        stage: update.stage ?? null,
-        provider: update.provider ?? null,
-        at: Date.now(),
-      });
-    }
-    if (!key || !this.options.onRowUpdate) {
-      return;
-    }
-    void this.options.onRowUpdate({
-      ...update,
-      key,
-      tableNamespace,
-    });
-  }
-
-  private emitExecutionEvent(event: PlayExecutionEvent): void {
-    if (!this.options.onExecutionEvent) {
-      return;
-    }
-    void this.options.onExecutionEvent(event);
-  }
-
-  private setMapFrame(frame: MapExecutionFrame): void {
-    this.checkpoint.mapFrames = {
-      ...(this.checkpoint.mapFrames ?? {}),
-      [frame.mapInvocationId]: cloneMapFrame(frame),
-    };
-  }
-
-  private createMapExecutionScope(input: {
-    logicalNamespace: string;
-    artifactTableNamespace: string;
-    mapNodeId?: string | null;
-    explicitKey?:
-      | ((row: Record<string, unknown>, index: number) => string)
-      | null;
-  }): MapExecutionScope {
-    const mapInvocationId = `${input.logicalNamespace}:${this.mapInvocationIndex}`;
-    this.mapInvocationIndex += 1;
-    const explicitKey = input.explicitKey ?? null;
-    return {
-      mapInvocationId,
-      mapNodeId: input.mapNodeId ?? null,
-      logicalNamespace: input.logicalNamespace,
-      artifactTableNamespace: input.artifactTableNamespace,
-      rowIdentity: (row, index) =>
-        explicitKey
-          ? derivePlayRowIdentityFromKey(
-              explicitKey(row, index ?? 0),
-              input.artifactTableNamespace,
-            )
-          : derivePlayRowIdentity(
-              stripCsvProjectedFields(row),
-              input.artifactTableNamespace,
-            ),
-    };
-  }
-
-  private normalizeContextKey(key: string, operation: string): string {
-    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 {
-    if (!input.fieldName) {
-      this.emitScopedRowUpdate(input.key, input.tableNamespace, {
-        rowId: input.rowId,
-        status: input.rowStatus,
-        stage: input.stage ?? null,
-        provider: input.provider ?? null,
-        error: input.error ?? null,
-        dataPatch: input.dataPatch ?? {},
-      });
-      return;
-    }
-
-    this.emitScopedRowUpdate(input.key, input.tableNamespace, {
-      rowId: input.rowId,
-      status: input.rowStatus,
-      stage: input.stage ?? null,
-      provider: input.provider ?? null,
-      error: input.error ?? null,
-      dataPatch: input.dataPatch ?? {},
-      cellMetaPatch: {
-        [input.fieldName]: {
-          status: input.status,
-          stage: input.stage ?? null,
-          provider: input.provider ?? null,
-          error: input.error ?? null,
-          ...(input.reused !== undefined ? { reused: input.reused } : {}),
-        },
-      },
-    });
-  }
-
-  private emitCellUpdate(input: {
-    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.emitScopedRowUpdate(input.key, input.tableNamespace, {
-      rowId: input.rowId,
-      status: input.rowStatus,
-      stage: input.stage ?? null,
-      provider: input.provider ?? null,
-      error: input.error ?? null,
-      dataPatch:
-        input.value === undefined ? {} : { [input.columnName]: input.value },
-      cellMetaPatch: {
-        [input.columnName]: {
-          status: input.status,
-          stage: input.stage ?? null,
-          provider: input.provider ?? null,
-          error: input.error ?? null,
-        },
-      },
-    });
-  }
-
-  private emitQueuedInlineWaterfallSteps(
-    rowId: number,
-    key: string | null,
-    tableNamespace: string | null,
-    spec: InlineWaterfallSpec,
-  ): void {
-    for (const step of spec.steps) {
-      this.emitCellUpdate({
-        rowId,
-        key,
-        tableNamespace,
-        columnName: sqlSafePlayColumnName(`${spec.id}.${step.id}`),
-        status: 'queued',
-        stage: step.id,
-        provider: isInlineWaterfallToolStep(step) ? step.toolId : 'code',
-        value: null,
-      });
-    }
-  }
-
-  private isCompletedFieldValue(value: unknown): boolean {
-    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 resolver = this.toolCallResolvers.get(request.callId);
-    if (resolver) {
-      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>,
-  ): 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,
-    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) {
-      return new RuntimeMapBuilder(this, key, items);
-    }
-
-    if (isRuntimeStepProgram(input)) {
-      return this.runStepProgramMap(key, items, input, options);
-    }
-
-    throw new Error(
-      'ctx.map(key, rows, fields, options) was removed. Use ctx.map(key, rows).step(...).run(options).',
-    );
-  }
-
-  async runStepProgramMap<T extends Record<string, unknown>>(
-    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, { company: ... }, { staleAfterSeconds: 86400 }).`
-          : `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 stripFieldOutputs = (row: Record<string, unknown>) =>
-      Object.fromEntries(
-        Object.entries(row).filter(
-          ([fieldName]) => !mapFieldNames.includes(fieldName),
-        ),
-      );
-
-    const userKeyOption = options?.key;
-    let explicitKeyResolver:
-      | ((row: Record<string, unknown>, index: number) => string)
-      | null = null;
-    if (userKeyOption !== undefined) {
-      explicitKeyResolver = (row, index) => {
-        const inputRow = stripFieldOutputs(row);
-        const raw =
-          typeof userKeyOption === 'function'
-            ? (
-                userKeyOption as (
-                  row: Record<string, unknown>,
-                  index: number,
-                ) => string | number | readonly unknown[]
-              )(inputRow, index)
-            : Array.isArray(userKeyOption)
-              ? userKeyOption.map((fieldName) => inputRow[fieldName])
-              : inputRow[String(userKeyOption)];
-        const parts = Array.isArray(raw) ? raw : [raw];
-        if (parts.some((part) => part === null || part === undefined)) {
-          throw new Error(
-            `ctx.map("${normalizedMapNamespace}") key returned null or undefined for row ${index}. ` +
-              'Return a non-empty string or number derived from a stable input column (e.g. row.email ?? row.domain).',
-          );
-        }
-        const normalizedParts = parts.map((part) => {
-          if (typeof part === 'number') {
-            return Number.isFinite(part) ? String(part) : '';
-          }
-          return String(part).trim();
-        });
-        if (normalizedParts.some((part) => !part)) {
-          throw new Error(
-            `ctx.map("${normalizedMapNamespace}") key returned an empty value for row ${index}. ` +
-              'Return a non-empty string or finite number derived from a stable input column.',
-          );
-        }
-        return normalizedParts.length === 1
-          ? normalizedParts[0]!
-          : JSON.stringify(normalizedParts);
-      };
-    }
-
-    const rowIdentity = (row: Record<string, unknown>, index = 0) =>
-      explicitKeyResolver
-        ? derivePlayRowIdentityFromKey(
-            explicitKeyResolver(row, index),
-            resolvedTableNamespace,
-          )
-        : derivePlayRowIdentity(
-            stripCsvProjectedFields(stripFieldOutputs(row)),
-            resolvedTableNamespace,
-          );
-
-    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>),
-    );
-
-    if (explicitKeyResolver) {
-      const seenKeys = new Map<string, number>();
-      for (let index = 0; index < rawItems.length; index += 1) {
-        const keyValue = explicitKeyResolver(rawItems[index]!, index);
-        const previousIndex = seenKeys.get(keyValue);
-        if (previousIndex !== undefined) {
-          throw new Error(
-            `ctx.map("${normalizedMapNamespace}") key function produced duplicate value "${keyValue}" for rows ${previousIndex} and ${index}. ` +
-              'Each row must produce a unique key. Combine columns (e.g. `${row.email}|${row.company}`) or pick a column that is unique per row.',
-          );
-        }
-        seenKeys.set(keyValue, index);
-      }
-    }
-    if (this.options.onMapStart) {
-      const mapStartRows = explicitKeyResolver
-        ? rawItems.map((row, index) => ({
-            ...row,
-            __deeplineRowKey: rowIdentity(row, index),
-          }))
-        : rawItems;
-      const mapStartResult = await this.options.onMapStart(
-        mapStartRows,
-        resolvedTableNamespace,
-        {
-          playName: this.options.playName,
-          playId: this.options.playId,
-          runId: this.options.runId,
-          staticPipeline: this.options.staticPipeline,
-        },
-      );
-      resolvedTableNamespace = normalizeTableNamespace(
-        mapStartResult.tableNamespace,
-      );
-      const persistedRowIdentity = (
-        row: Record<string, unknown>,
-        index = 0,
-      ) =>
-        typeof row.__deeplineRowKey === 'string'
-          ? row.__deeplineRowKey
-          : rowIdentity(row, index);
-      const pendingKeys = new Set(
-        mapStartResult.pendingRows.map((row, index) =>
-          persistedRowIdentity(row, index),
-        ),
-      );
-      itemsToProcess = materializedItems
-        .map((item, index) => ({
-          row: this.toOutputRow(item as Record<string, unknown>),
-          index,
-        }))
-        .filter(({ row, index }) => pendingKeys.has(rowIdentity(row, index)))
-        .map(({ row }) => row);
-      if (mapStartResult.completedRows.length > 0) {
-        completedItemsByKey = new Map();
-        for (let index = 0; index < mapStartResult.completedRows.length; index += 1) {
-          const row = mapStartResult.completedRows[index]!;
-          const rowKey = persistedRowIdentity(row, index);
-          if (rowKey) completedItemsByKey.set(rowKey, row);
-        }
-        this.log(
-          `Resuming: ${mapStartResult.completedRows.length} already completed, ${itemsToProcess.length} pending`,
-        );
-      }
-    }
-
-    const mapScope = this.createMapExecutionScope({
-      logicalNamespace: normalizedMapNamespace,
-      artifactTableNamespace: resolvedTableNamespace,
-      explicitKey: explicitKeyResolver,
-    });
-    const completedRowKeys =
-      completedItemsByKey != null ? [...completedItemsByKey.keys()] : [];
-    const pendingRowKeys = itemsToProcess.map((item, index) =>
-      mapScope.rowIdentity(this.toOutputRow(item), index),
-    );
-    this.setMapFrame({
-      mapInvocationId: mapScope.mapInvocationId,
-      mapNodeId: mapScope.mapNodeId ?? null,
-      logicalNamespace: mapScope.logicalNamespace,
-      artifactTableNamespace: mapScope.artifactTableNamespace,
-      status: 'running',
-      totalRows: totalInputCount,
-      completedRowKeys,
-      pendingRowKeys,
-      startedAt: Date.now(),
-      updatedAt: Date.now(),
-    });
-    this.emitExecutionEvent({
-      type: 'map.started',
-      mapInvocationId: mapScope.mapInvocationId,
-      mapNodeId: mapScope.mapNodeId ?? null,
-      logicalNamespace: mapScope.logicalNamespace,
-      artifactTableNamespace: mapScope.artifactTableNamespace,
-      totalRows: totalInputCount,
-      completedRows: completedRowKeys.length,
-      pendingRows: pendingRowKeys.length,
-      at: Date.now(),
-    });
-
-    const mapResults = await this.runFieldMap(
-      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, index);
-              if (rowKey) resultsByKey.set(rowKey, row);
-            }
-            return rawItems.map((rawItem, index) => {
-              const rowKey = rowIdentity(rawItem, index);
-              return this.toPublicOutputRow(
-                resultsByKey.get(rowKey) ??
-                  completedItemsByKey!.get(rowKey) ??
-                  rawItem,
-              );
-            });
-          })()
-        : mapResults.map((row) => this.toPublicOutputRow(row));
-
-    return createDeferredPlayDataset({
-      datasetKind: 'map',
-      datasetId: createRuntimeDatasetId(
-        this.options.playName ?? this.options.playId ?? 'play',
-        resolvedTableNamespace,
-      ),
-      count: results.length,
-      previewRows: results.slice(0, 5),
-      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(
-        stripCsvProjectedFields(
-          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;
-      failedDelta?: number;
-      emitEventType?: PlayExecutionEvent['type'];
-    }) => {
-      const existing =
-        this.checkpoint.mapFrames?.[mapScope.mapInvocationId] ?? null;
-      if (!existing) {
-        return;
-      }
-      const completedRowKeys = new Set(existing.completedRowKeys);
-      const pendingRowKeys = new Set(existing.pendingRowKeys);
-      if (input.completedRowKey?.trim()) {
-        completedRowKeys.add(input.completedRowKey.trim());
-        pendingRowKeys.delete(input.completedRowKey.trim());
-      }
-      if (input.pendingRowKey?.trim()) {
-        pendingRowKeys.add(input.pendingRowKey.trim());
-      }
-      const nextFrame: MapExecutionFrame = {
-        ...existing,
-        status: input.status ?? existing.status,
-        completedRowKeys: [...completedRowKeys],
-        pendingRowKeys: [...pendingRowKeys],
-        ...(input.activeBoundaryId !== undefined
-          ? { activeBoundaryId: input.activeBoundaryId }
-          : {}),
-        updatedAt: Date.now(),
-      };
-      this.setMapFrame(nextFrame);
-      if (input.emitEventType) {
-        this.emitExecutionEvent({
-          type: input.emitEventType,
-          mapInvocationId: mapScope.mapInvocationId,
-          mapNodeId: mapScope.mapNodeId ?? null,
-          logicalNamespace: mapScope.logicalNamespace,
-          artifactTableNamespace: mapScope.artifactTableNamespace,
-          completedRows: nextFrame.completedRowKeys.length,
-          failedRows: Math.max(
-            0,
-            totalRows -
-              nextFrame.completedRowKeys.length -
-              nextFrame.pendingRowKeys.length,
-          ),
-          totalRows,
-          at: Date.now(),
-        } as PlayExecutionEvent);
-      }
-    };
-
-    if (this.canUsePureJsMapFastPath(definition)) {
-      const results = await this.runPureFieldMap(
-        items,
-        fieldEntries,
-        visibleFields,
-        normalizedTableNamespace,
-        (row, index) => mapScope.rowIdentity(row, index),
-      );
-      for (let index = 0; index < results.length; index += 1) {
-        const row = results[index]!;
-        updateMapFrameProgress({
-          completedRowKey: rowIdentity(row, index),
-        });
-      }
-      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,
-                cloneCsvAliasedRow(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 = cloneCsvAliasedRow(baseRow, computedFields);
-        activeFieldName = null;
-        updateMapFrameProgress({
-          completedRowKey: rowKey,
-        });
-        this.emitScopedRowUpdate(rowKey, normalizedTableNamespace, {
-          rowId: idx,
-          status: 'completed',
-          stage: 'completed',
-          provider: null,
-          error: null,
-          dataPatch: {},
-        });
-        return this.toPublicOutputRow(merged);
-      } 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, index);
-          if (key) {
-            completedRowKeys.add(key);
-          }
-          continue;
-        }
-        const row = result as Record<string, unknown>;
-        const key = rowIdentity(row, index);
-        if (key) completedRowKeys.add(key);
-      }
-      this.setMapFrame({
-        ...(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, index) =>
-            rowIdentity(this.toOutputRow(item as Record<string, unknown>), index),
-          ),
-          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 (let index = 0; index < results.length; index += 1) {
-      const row = results[index]!;
-      updateMapFrameProgress({
-        completedRowKey: rowIdentity(row, index),
-      });
-    }
-    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 = cloneCsvAliasedRow(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 = cloneCsvAliasedRow(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;
-    }
-    return Object.values(definition).every((resolver) => {
-      if (typeof resolver !== 'function') {
-        return true;
-      }
-
-      const source = Function.prototype.toString.call(resolver);
-      return (
-        !source.includes('.tools.execute(') && !source.includes('.waterfall(')
-      );
-    });
-  }
-
-  private async runPureFieldMap<T>(
-    items: T[],
-    fieldEntries: [string, MapFieldDefinition<T>[string]][],
-    visibleFields: string[],
-    tableNamespace: string,
-    rowIdentity: (row: Record<string, unknown>, index: number) => string,
-  ): Promise<Array<Record<string, unknown>>> {
-    const results: Array<Record<string, unknown>> = [];
-    this.pureMapExecutionActive = true;
-
-    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, index), tableNamespace, {
-                rowId: index,
-                status: undefined,
-                stage: null,
-                provider: null,
-                error: null,
-                dataPatch: {},
-                cellMetaPatch: {
-                  [fieldName]: {
-                    status: 'cached',
-                    reused: true,
-                  },
-                },
-              });
-              continue;
-            }
-
-            this.emitScopedRowUpdate(rowIdentity(baseRow, index), 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,
-              cloneCsvAliasedRow(baseRow, computedFields),
-              index,
-            );
-            this.emitScopedRowUpdate(rowIdentity(baseRow, index), tableNamespace, {
-              rowId: index,
-              status: undefined,
-              stage: 'completed',
-              provider: null,
-              error: null,
-              dataPatch: fieldName.startsWith('_')
-                ? {}
-                : { [fieldName]: computedFields[fieldName] },
-              cellMetaPatch: {
-                [fieldName]: {
-                  status: 'completed',
-                  stage: 'completed',
-                },
-              },
-            });
-          }
-
-          results.push(
-            this.toPublicOutputRow(
-              cloneCsvAliasedRow(baseRow, computedFields),
-            ),
-          );
-
-          const rowKey = rowIdentity(baseRow, index);
-          activeFieldName = null;
-          this.emitScopedRowUpdate(rowKey, tableNamespace, {
-            rowId: index,
-            status: 'completed',
-            stage: 'completed',
-            provider: null,
-            error: null,
-            dataPatch: {},
-          });
-        } catch (error) {
-          const rowKey = rowIdentity(baseRow, index);
-          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 does tools.execute('a') then tools.execute('b') sequentially).
-    // We keep looping until nothing new is queued and all rows finish.
-    //
-    // Important: an unresolved Promise by itself does not keep Node alive. The
-    // 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 };
-  }
-
-  private toPublicOutputRow(row: Record<string, unknown>): Record<string, unknown> {
-    const stripped = stripCsvProjectedFields(row);
-    return Object.fromEntries(
-      Object.entries(stripped).filter(([fieldName]) => !fieldName.startsWith('_')),
-    );
-  }
-
-  async waterfall(
-    toolNameOrSpec: string | InlineWaterfallSpec,
-    input: Record<string, unknown>,
-    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.checkpoint.resolvedWaterfalls[queueKey];
-    if (resolved && rowId in resolved) {
-      this.log(`  Row ${rowId} ${toolName}: recovered from checkpoint`);
-      return resolved[rowId];
-    }
-
-    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(
-    key: string,
-    toolId: string,
-    input: Record<string, unknown>,
-    options?: ToolCallOptions,
-  ): Promise<unknown> {
-    const normalizedKey = this.normalizeContextKey(key, 'tool');
-
-    const eventWaitHandler =
-      (await this.options.getIntegrationEventWaitHandler?.(toolId)) ?? null;
-    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(
-          'ctx.tools.execute() cannot run inside the pure-JS fast path. Call it directly in the map definition so the batching runtime can stay enabled.',
-        );
-      }
-
-      if (!store) {
-        const directRowId = -(this.directToolCallIndex + 1);
-        this.directToolCallIndex += 1;
-        const directCacheKey = this.buildToolResultCacheKey({ rowId: directRowId });
-        const 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),
-        normalizedKey,
-        toolId,
-      ].join(':');
-      if (this.toolCallResolvers.has(callId)) {
-        throw new Error(
-          `ctx.tools.execute("${normalizedKey}") was called more than once concurrently for the same row. ` +
-            'Use a unique id for each row-scoped tool call.',
-        );
-      }
-
-      const cached = this.getCachedToolResult(
-        toolId,
-        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) => {
-        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(options?.description),
-        });
-      });
-    };
-
-    if (store) {
-      return await executeTool();
-    }
-
-    return this.executeWithRuntimeReceipt(
-      'tool',
-      normalizedKey,
-      this.currentRunId,
-      {
-        markSkipped: () => {
-          this.log(
-            `ctx.tools.execute(${toolId}): no-op due completed receipt ${normalizedKey}`,
-          );
-        },
-        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(...) 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.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 cached = this.checkpoint.completedBatches[batchKey];
-          if (!cached) return null;
-          this.log(`  ${provider}: skipping (recovered from checkpoint)`);
-          return cached.map((entry) => ({
-            request: requests.find((request) => request.rowId === entry.rowId)!,
-            result: entry.result,
-          }));
-        },
-        storeCachedResults: (provider, results) => {
-          const batchKey = `${queueKey}:${provider}`;
-          this.checkpoint.completedBatches[batchKey] = results.map((entry) => ({
-            rowId: entry.request.rowId,
-            result: entry.result,
-          }));
-        },
-        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.checkpoint.resolvedWaterfalls[queueKey]![req.rowId] = 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 (
-                  requestOrKey:
-                    | { tool: string; input: Record<string, unknown> }
-                    | string,
-                  toolId?: string,
-                  payload?: Record<string, unknown>,
-                ) => {
-                  if (typeof requestOrKey === 'object') {
-                    return await this.callToolAPI(
-                      requestOrKey.tool,
-                      requestOrKey.input,
-                    );
-                  }
-                  if (!toolId || !payload) {
-                    throw new Error(
-                      'inline waterfall ctx.tools.execute requires a tool and input.',
-                    );
-                  }
-                  return await this.callToolAPI(toolId, payload);
-                },
-              },
-            };
-            return await step.run(request.input, codeStepCtx);
-          },
-          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.checkpoint.resolvedWaterfalls[queueKey]![req.rowId] = 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.checkpoint.resolvedWaterfalls[queueKey]![rowId] = 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 resolver = this.toolCallResolvers.get(req.callId);
-            if (resolver) {
-              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 (
-                    requestOrKey:
-                      | { tool: string; input: Record<string, unknown> }
-                      | string,
-                    toolId?: string,
-                    payload?: Record<string, unknown>,
-                  ) => {
-                    if (typeof requestOrKey === 'object') {
-                      return await this.callToolAPI(
-                        requestOrKey.tool,
-                        requestOrKey.input,
-                      );
-                    }
-                    if (!toolId || !payload) {
-                      throw new Error(
-                        'inline waterfall ctx.tools.execute requires a tool and input.',
-                      );
-                    }
-                    return await this.callToolAPI(toolId, payload);
-                  },
-                },
-              }),
-            )
-          : 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> {
-    const execution = await this.callToolExecutionAPI(toolId, input);
-    return execution.result != null
-      && typeof execution.result === 'object'
-      && !Array.isArray(execution.result)
-      && 'data' in execution.result
-      ? execution.result.data
-      : execution.result;
-  }
-
-  private async callToolExecutionAPI(
-    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 (
-                  response.status >= 500 &&
-                  response.status < 600 &&
-                  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 result = data.result ?? data;
-              const status =
-                typeof data.status === 'string'
-                  ? data.status
-                  : result == null
-                    ? 'no_result'
-                    : 'completed';
-              setSpanAttributes(span, {
-                'plays.tool_result_kind':
-                  result == null
-                    ? 'null'
-                    : Array.isArray(result)
-                      ? 'array'
-                      : typeof result,
-              });
-              return {
-                status,
-                result,
-                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);
-}