deepline 0.2.53 → 0.2.55

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

@@ -237,6 +237,12 @@ import {
   createSecretRedactionContext,
   type SecretRedactionContext,
 } from './secret-redaction';
+import {
+  buildPlayDocflowNodeErrorPreview,
+  buildPlayDocflowNodeInputPreviewMap,
+  type PlayDocflowNodeInputCapture,
+} from './docflow-node-io';
+import type { DocflowObservationUpsert } from './docflow-observation';
 import {
   assertNoSecretTaint,
   assertSecretAuthUsesTls,
@@ -277,7 +283,25 @@ import type {
   RuntimeStepProgram,
   RuntimeStepProgramStep,
   RuntimeConditionalStepResolver,
+  PlayCellProducerAttempt,
+  PlayCellReadRef,
+  PlayCellDecision,
+  PlayRowReadOrder,
+  PlayRowMeta,
+  PlaySheetCellProducer,
 } from './ctx-types';
+import {
+  MAX_CELL_READ_REFS,
+  MAX_ROW_READ_CELLS,
+  ROW_META_CELL_KEY,
+  cellReadCut,
+  hydrateCellReadRefs,
+} from './cell-provenance';
+import {
+  buildPlayNodeScope,
+  playNodeScopeToWire,
+  type PlayNodeScope,
+} from './play-node-scope';
 import {
   StepProgramDatasetBuilder,
   type StepProgramDatasetColumnInput,
@@ -755,6 +779,59 @@ function finitePositiveInteger(value: unknown): number | null {
   return integer !== null && integer > 0 ? integer : null;
 }
 
+/**
+ * Sources that answered without opening a provider request of their own: a
+ * completed-receipt cache hit, a worker-replay checkpoint, and a follower that
+ * attached to an in-flight owner. `cached` is false on the in-flight metadata
+ * (nothing was cached at attach time), but no request was made either, so
+ * classifying it as a live call disagreed with the `reused` marker the sheet
+ * already writes and inflated `providerRequests` against `reusedCells`.
+ */
+const REUSED_TOOL_EXECUTION_SOURCES = new Set([
+  'cache',
+  'checkpoint',
+  'in_flight',
+]);
+
+/**
+ * Classify a settled tool-call result for the cell producer trace (ADR 0018).
+ * Unknown shapes settle as `completed`: the call returned, which is the fact
+ * the trace records.
+ */
+function toolAttemptOutcomeForResult(
+  value: unknown,
+): Exclude<PlayCellProducerAttempt['outcome'], 'running'> {
+  if (value == null) return 'no_result';
+  if (typeof value !== 'object' || Array.isArray(value)) return 'completed';
+  const record = value as Record<string, unknown>;
+  const execution = (record._metadata as Record<string, unknown> | undefined)
+    ?.execution as Record<string, unknown> | undefined;
+  const reused =
+    execution?.cached === true ||
+    execution?.receiptRole === 'follower' ||
+    (typeof execution?.source === 'string' &&
+      REUSED_TOOL_EXECUTION_SOURCES.has(execution.source));
+  if (reused) return 'cached';
+  return record.status === 'no_result' ? 'no_result' : 'completed';
+}
+
+/**
+ * Explicit execution location for a queued row-scoped tool call (ADR 0018).
+ * `toolIdOverride` lets a native batch report the batch operation it actually
+ * sent while keeping the members' column/namespace.
+ */
+function playNodeScopeForToolCallRequest(
+  request: ToolCallRequest,
+  toolIdOverride?: string,
+): PlayNodeScope | null {
+  return buildPlayNodeScope({
+    toolId: toolIdOverride ?? request.toolId,
+    callKey: request.contextKey,
+    column: request.fieldName,
+    tableNamespace: request.tableNamespace,
+  });
+}
+
 type ToolExecutionApiOptions = {
   timeoutMs?: number;
   durableCallReceiptKey?: string | null;
@@ -764,6 +841,12 @@ type ToolExecutionApiOptions = {
   beforeProviderCall?: () => Promise<void> | void;
   heartbeatReceipt?: () => Promise<void> | void;
   parkProviderCall?: () => Promise<void> | void;
+  /**
+   * Explicit graph-node attribution for this provider call (ADR 0018). Carried
+   * to the execute route, which stamps it onto the usage event so per-node
+   * credits are a query instead of a log-text inference.
+   */
+  playNodeScope?: PlayNodeScope | null;
   customerDbDataset?: {
     limit: number;
     offset: number;
@@ -772,6 +855,11 @@ type ToolExecutionApiOptions = {
   };
 };
 const IN_MEMORY_STEP_RESULT_PREVIEW_LIMIT = 25;
+/**
+ * Per-cell cap on the durable producer trace (ADR 0018). A cascade has a handful
+ * of legs; this only bounds pathological loops, keeping `_cell_meta` small.
+ */
+const MAX_CELL_PRODUCER_ATTEMPTS = 12;
 const BATCH_SIZE_LOG_SAMPLE_LIMIT = 10;
 const STEP_PROGRAM_MAP_DEFINITION = Symbol('deepline.stepProgramMapDefinition');
 
@@ -1435,6 +1523,22 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   }> = [];
   private processedRowCount = 0;
   private sleepBoundaryIndex = 0;
+  private nextDocflowInvocationSequence = 0;
+  /**
+   * Whether this run captures the docflow trace at all (ADR 0019), decided at
+   * admission and handed down through the signed runtime authority.
+   *
+   * Read at every capture SITE rather than only inside the recorders, because
+   * the cost being gated is mostly in the arguments: `cellReadRefsForRow`,
+   * `effectiveCellReads` and `rowInputReadColumns` each walk the row, and a
+   * recorder that returns early has already paid for them. Off, an ungated org
+   * writes precisely the `_cell_meta` it wrote before this feature existed —
+   * no `reads`, no `decide`, no `_row` order — so nothing downstream has to
+   * know two shapes.
+   */
+  private get docflowCaptureEnabled(): boolean {
+    return this.#options.docflowEnabled === true;
+  }
   /**
    * `ctx.customerDb.query` is syntactic sugar over the query_customer_db tool.
    * Keep generated tool ids distinct so separate imperative queries retain
@@ -1764,6 +1868,165 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     });
   }
 
+  /** @internal Compiler-injected authored-flow execution marker. */
+  async __deeplineDocflowHit(nodeId: string): Promise<void> {
+    const normalizedNodeId = nodeId.trim();
+    if (!normalizedNodeId) {
+      throw new Error('Docflow runtime node id must be non-empty.');
+    }
+    // These calls are COMPILER-INJECTED, so bundle-time gating cannot reach
+    // them: a prebuilt is compiled once, with its diagram, and then runs for
+    // every org. Without this check an ungated customer running a prebuilt gets
+    // `docflow.node.*` events on the wire and a `step docflow:*` sequence in
+    // `plays run --watch` — the vocabulary of a feature they do not have.
+    // The id is still validated above: a malformed injection is a compiler bug
+    // and stays loud whether or not the run is capturing.
+    if (!this.docflowCaptureEnabled) return;
+    this.emitExecutionEvent({
+      type: 'docflow.node.hit',
+      nodeId: `docflow:${normalizedNodeId}`,
+      at: Date.now(),
+    });
+  }
+
+  /** @internal Compiler-injected bounded authored-node observation boundary. */
+  __deeplineObserveDocflowNode<T>(
+    nodeId: string,
+    inputCaptures: readonly PlayDocflowNodeInputCapture[],
+    outputPaths: readonly string[],
+    execute: () => T | Promise<T>,
+  ): T | Promise<T> {
+    const normalizedNodeId = nodeId.trim();
+    if (!normalizedNodeId) {
+      throw new Error('Docflow runtime node id must be non-empty.');
+    }
+    // Ungated, this boundary is a pass-through: the wrapped work still runs and
+    // still returns what it returned, but nothing is previewed, redacted, or
+    // emitted. Returning before `buildPlayDocflowNodeInputPreviewMap` is the
+    // point — previewing every bound node's inputs is the expensive half, and a
+    // customer outside the rollout should not pay for a capture they cannot
+    // read. Same reasoning as `__deeplineDocflowHit` above: injected at compile
+    // time, so the run is the only place left to decide.
+    if (!this.docflowCaptureEnabled) return execute();
+    const attempt = this.currentRunAttempt;
+    const inputs = buildPlayDocflowNodeInputPreviewMap(inputCaptures, {
+      redactor: this.secretRedactor,
+    });
+    const invocationSeq = this.nextDocflowInvocationSequence++;
+    const invocationId = `${attempt}:${invocationSeq}`;
+    const observationNodeId = `docflow:${normalizedNodeId}`;
+    this.emitExecutionEvent({
+      type: 'docflow.node.started',
+      nodeId: observationNodeId,
+      attempt,
+      invocationId,
+      inputs: inputs.values,
+      ...(inputs.truncated ? { inputsTruncated: true } : {}),
+      at: Date.now(),
+    });
+    this.emitDocflowObservation({
+      runId: this.currentGovernance.currentRunId,
+      attempt,
+      nodeId: observationNodeId,
+      invocationSeq,
+      invocationId,
+      status: 'started',
+      inputs: inputs.values,
+      inputsTruncated: inputs.truncated,
+      at: Date.now(),
+    });
+
+    const complete = (result: T): void => {
+      const outputRoots = new Set(
+        outputPaths
+          .map((path) => path.trim())
+          .filter((path) => path && path !== '$output')
+          .map((path) => path.split('.')[0]),
+      );
+      const outputs = buildPlayDocflowNodeInputPreviewMap(
+        outputPaths
+          .map((path) => path.trim())
+          .filter(Boolean)
+          .map((path) => ({
+            path,
+            readRoot: () => result,
+            properties:
+              path === '$output'
+                ? []
+                : outputRoots.size > 1
+                  ? path.split('.')
+                  : path.split('.').slice(1),
+          })),
+        { redactor: this.secretRedactor },
+      );
+      this.emitExecutionEvent({
+        type: 'docflow.node.completed',
+        nodeId: observationNodeId,
+        attempt,
+        invocationId,
+        inputs: inputs.values,
+        ...(inputs.truncated ? { inputsTruncated: true } : {}),
+        outputs: outputs.values,
+        ...(outputs.truncated ? { outputsTruncated: true } : {}),
+        at: Date.now(),
+      });
+      this.emitDocflowObservation({
+        runId: this.currentGovernance.currentRunId,
+        attempt,
+        nodeId: observationNodeId,
+        invocationSeq,
+        invocationId,
+        status: 'completed',
+        inputs: inputs.values,
+        inputsTruncated: inputs.truncated,
+        outputs: outputs.values,
+        outputsTruncated: outputs.truncated,
+        at: Date.now(),
+      });
+    };
+    const fail = (error: unknown): void => {
+      const errorPreview = buildPlayDocflowNodeErrorPreview(
+        error,
+        this.secretRedactor,
+      );
+      this.emitExecutionEvent({
+        type: 'docflow.node.failed',
+        nodeId: observationNodeId,
+        attempt,
+        invocationId,
+        inputs: inputs.values,
+        ...(inputs.truncated ? { inputsTruncated: true } : {}),
+        error: errorPreview,
+        at: Date.now(),
+      });
+      this.emitDocflowObservation({
+        runId: this.currentGovernance.currentRunId,
+        attempt,
+        nodeId: observationNodeId,
+        invocationSeq,
+        invocationId,
+        status: 'failed',
+        inputs: inputs.values,
+        inputsTruncated: inputs.truncated,
+        error: errorPreview,
+        at: Date.now(),
+      });
+    };
+
+    try {
+      const result = execute();
+      if (result instanceof Promise) {
+        void result.then(complete, fail);
+        return result;
+      }
+      complete(result);
+      return result;
+    } catch (error) {
+      fail(error);
+      throw error;
+    }
+  }
+
   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
@@ -1907,6 +2170,16 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           ...(existing?.cellMetaPatch ?? {}),
           ...(update.cellMetaPatch ?? {}),
         },
+        // Row-grain provenance is re-stated whole on every patch, so the later
+        // record always supersedes: it can only have grown (ADR 0019).
+        ...((update.rowMetaPatch ?? existing?.rowMetaPatch)
+          ? {
+              rowMetaPatch: {
+                ...(existing?.rowMetaPatch ?? {}),
+                ...(update.rowMetaPatch ?? {}),
+              },
+            }
+          : {}),
       };
       this.activeMapCheckpointUpdates.set(checkpointKey, next);
     }
@@ -1931,7 +2204,41 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     if (!this.#options.onExecutionEvent) {
       return;
     }
-    void this.#options.onExecutionEvent(event);
+    try {
+      const pending = this.#options.onExecutionEvent(event);
+      if (pending && typeof pending.then === 'function') {
+        void pending.catch(() => {
+          // Execution events are observability projections. Their transport
+          // must never change authored play behavior or mask its result.
+        });
+      }
+    } catch {
+      // Keep synchronous observer failures outside the authored execution.
+    }
+  }
+
+  /**
+   * Durable docflow observation write (ADR 0016 rule 2). The sink is present
+   * only for instrumented plays and posts to the receipt gateway. It is
+   * strictly fire-and-forget: a synchronous throw or a rejected promise is
+   * swallowed (loudly logged by the sink) so a durable-write failure can never
+   * fail or slow the authored play body. The live event emission above is the
+   * authoritative low-latency path and is unaffected.
+   */
+  private emitDocflowObservation(observation: DocflowObservationUpsert): void {
+    if (!this.#options.onDocflowObservation) {
+      return;
+    }
+    try {
+      const pending = this.#options.onDocflowObservation(observation);
+      if (pending && typeof pending.then === 'function') {
+        void pending.catch(() => {
+          // Swallowed here; the sink is responsible for loud logging.
+        });
+      }
+    } catch {
+      // Never let an observation write escape into authored execution.
+    }
   }
 
   private async resolveSecretAuth(auth: SecretAuth | undefined) {
@@ -3346,6 +3653,418 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     return this.currentExecutionScope.receipt.ownerAttempt;
   }
 
+  /**
+   * Explicit tool-node lifecycle for non-row-scoped calls (ADR 0018). Replaces
+   * the stdout-regex inference the progress reporter used to run.
+   */
+  private emitToolCallLifecycle(
+    phase: 'started' | 'settled',
+    toolId: string,
+    callKey: string | null,
+    settlement?: {
+      outcome: 'completed' | 'no_result' | 'failed' | 'cached';
+      durationMs?: number | null;
+      error?: string | null;
+    },
+  ): void {
+    if (phase === 'started') {
+      this.emitExecutionEvent({
+        type: 'tool.call.started',
+        toolId,
+        callKey,
+        at: Date.now(),
+      });
+      return;
+    }
+    if (!settlement) return;
+    this.emitExecutionEvent({
+      type: 'tool.call.settled',
+      toolId,
+      callKey,
+      outcome: settlement.outcome,
+      ...(settlement.durationMs !== undefined
+        ? { durationMs: settlement.durationMs }
+        : {}),
+      ...(settlement.error ? { error: settlement.error } : {}),
+      at: Date.now(),
+    });
+  }
+
+  /**
+   * Direct (non-row-scoped) provider call with explicit node lifecycle. The
+   * failure branch must emit `tool.call.settled` before rethrowing, otherwise a
+   * failed tool node would stay `running` in the snapshot forever.
+   */
+  private async executeDirectToolCall(input: {
+    toolId: string;
+    callKey: string;
+    startedAt: number;
+    input: Record<string, unknown>;
+    options: ToolExecutionApiOptions;
+  }): Promise<ParsedToolExecuteResponse> {
+    // The caller owns settlement: it pairs started/settled in a finally so a
+    // throw anywhere in the direct path — transport, result wrapping, receipt
+    // ownership — settles the node exactly once instead of stranding it.
+    return await this.callToolExecutionAPI(
+      input.toolId,
+      input.input,
+      input.options,
+    );
+  }
+
+  /**
+   * Bounded per-cell producer trace (ADR 0018).
+   *
+   * Returns the cell's accumulated attempts, with `attempt` appended when a new
+   * one starts. Attempt records are returned by reference so a caller can
+   * settle `outcome`/`durationMs` in place before the next patch re-states the
+   * array. Storage is `activeMapCellMeta`, which is scoped to the running map
+   * and released with it, so this adds no run-lifetime structure.
+   */
+  /** Last recorded producer for a cell, so a later patch cannot erase it. */
+  private resolveCellProducer(
+    key: string | null,
+    fieldName: string,
+  ): PlaySheetCellProducer | undefined {
+    const existingCell = key
+      ? this.activeMapCellMeta?.get(key)?.[fieldName]
+      : undefined;
+    const producer =
+      existingCell &&
+      typeof existingCell === 'object' &&
+      !Array.isArray(existingCell)
+        ? (existingCell as { producer?: unknown }).producer
+        : undefined;
+    return producer as PlaySheetCellProducer | undefined;
+  }
+
+  private resolveCellProducers(
+    key: string | null,
+    fieldName: string,
+    attempt?: PlayCellProducerAttempt,
+  ): {
+    producers: PlayCellProducerAttempt[] | undefined;
+    attemptsDropped: number;
+  } {
+    if (!key) {
+      return {
+        producers: attempt ? [attempt] : undefined,
+        attemptsDropped: 0,
+      };
+    }
+    const existingCell = this.activeCellMetaRecord(key, fieldName);
+    const existingProducers = existingCell?.producers;
+    const current = Array.isArray(existingProducers)
+      ? (existingProducers as PlayCellProducerAttempt[])
+      : [];
+    const droppedSoFar =
+      typeof existingCell?.attemptsDropped === 'number'
+        ? existingCell.attemptsDropped
+        : 0;
+    if (!attempt) {
+      return {
+        producers: current.length > 0 ? current : undefined,
+        attemptsDropped: droppedSoFar,
+      };
+    }
+    const next = [...current, attempt];
+    if (next.length <= MAX_CELL_PRODUCER_ATTEMPTS) {
+      return { producers: next, attemptsDropped: droppedSoFar };
+    }
+    // Keep the newest attempts — a cascade's decisive legs are its last ones —
+    // but count what fell off. Without the count a capped cell's logicalCalls
+    // reads as a complete total when it is a floor.
+    const dropped = next.length - MAX_CELL_PRODUCER_ATTEMPTS;
+    return {
+      producers: next.slice(dropped),
+      attemptsDropped: droppedSoFar + dropped,
+    };
+  }
+
+  /**
+   * Carry this run's durable producer trace into a re-executed row (ADR 0018).
+   *
+   * `activeMapCellMeta` starts empty on a worker replay, and the durable jsonb
+   * merge replaces a cell's `producers` array wholesale, so a re-executed cell
+   * would erase the attempts the earlier execution recorded — silently
+   * under-counting `logicalCalls` and losing the only record a failed leg ever
+   * gets. The row already arrives carrying its durable cell meta (it is what
+   * `previousCell` is built from), so seeding costs no extra round trip.
+   *
+   * Only cells stamped with the CURRENT run are seeded. A previous run's
+   * attempts are that run's facts; appending them here would inflate this run.
+   * Seeding read-modify-writes nothing durable: the append still lands through
+   * the attempt-fenced write, so a fenced-out attempt cannot corrupt the trace.
+   */
+  private seedActiveCellProducersFromDurableRow(
+    rowKey: string | null,
+    baseRow: Record<string, unknown>,
+  ): void {
+    if (!rowKey || !this.activeMapCellMeta) return;
+    const durable = baseRow[DEEPLINE_CELL_META_FIELD];
+    if (!durable || typeof durable !== 'object' || Array.isArray(durable)) {
+      return;
+    }
+    for (const [fieldName, rawCell] of Object.entries(
+      durable as Record<string, unknown>,
+    )) {
+      if (!rawCell || typeof rawCell !== 'object' || Array.isArray(rawCell)) {
+        continue;
+      }
+      const cell = rawCell as Record<string, unknown>;
+      if (cell.runId !== this.currentRunId) continue;
+      if (!Array.isArray(cell.producers) || cell.producers.length === 0) {
+        continue;
+      }
+      const existingRow = this.activeMapCellMeta.get(rowKey);
+      const existingCell = this.activeCellMetaRecord(rowKey, fieldName);
+      if (existingCell?.producers !== undefined) continue;
+      this.activeMapCellMeta.set(rowKey, {
+        ...(existingRow ?? {}),
+        [fieldName]: {
+          ...(existingCell ?? {}),
+          producers: cell.producers,
+          ...(typeof cell.attemptsDropped === 'number'
+            ? { attemptsDropped: cell.attemptsDropped }
+            : {}),
+        },
+      });
+    }
+  }
+
+  /** Existing `_cell_meta` record for a cell inside the running map, if any. */
+  private activeCellMetaRecord(
+    key: string | null,
+    fieldName: string,
+  ): Record<string, unknown> | null {
+    const existingCell = key
+      ? this.activeMapCellMeta?.get(key)?.[fieldName]
+      : undefined;
+    return existingCell &&
+      typeof existingCell === 'object' &&
+      !Array.isArray(existingCell)
+      ? (existingCell as Record<string, unknown>)
+      : null;
+  }
+
+  /**
+   * Provenance capture is a field on writes that already happen (ADR 0019), so
+   * a record made *before* the cell's next patch is seeded into the running
+   * map's cell meta and re-stated by that patch. No extra emit, no extra round
+   * trip, and the record is released with the map like the producer trace.
+   */
+  private recordCellProvenance(
+    key: string | null,
+    fieldName: string,
+    record: { reads?: PlayCellReadRef[]; decide?: PlayCellDecision },
+  ): void {
+    if (!key || !this.activeMapCellMeta) return;
+    if (record.reads === undefined && record.decide === undefined) return;
+    const existingRow = this.activeMapCellMeta.get(key);
+    const existingCell = this.activeCellMetaRecord(key, fieldName);
+    this.activeMapCellMeta.set(key, {
+      ...(existingRow ?? {}),
+      [fieldName]: {
+        ...(existingCell ?? {}),
+        ...(record.reads !== undefined ? { reads: record.reads } : {}),
+        ...(record.decide !== undefined ? { decide: record.decide } : {}),
+      },
+    });
+  }
+
+  /** Row-grain read order for the running map's row, if one was recorded. */
+  private resolveRowReadOrder(
+    key: string | null,
+  ): PlayRowReadOrder | undefined {
+    const rowMeta = this.activeCellMetaRecord(key, ROW_META_CELL_KEY);
+    const reads = rowMeta?.reads;
+    return reads && typeof reads === 'object' && !Array.isArray(reads)
+      ? (reads as PlayRowReadOrder)
+      : undefined;
+  }
+
+  /**
+   * Open one cell against the row's read order (ADR 0019).
+   *
+   * The order lives once per row under the reserved `_row` key instead of once
+   * per cell. A written column is appended before its own cell runs, so its
+   * position in the list *is* its cut point — everything before it was
+   * available to it, itself and everything after it was not. That makes the
+   * common case a single string append with no per-cell record at all. Cells
+   * the list cannot place (non-persisted fields, and anything past the column
+   * cap) fall back to an explicit cut, and cells past the cell cap are counted
+   * as dropped rather than silently reading as having read nothing.
+   */
+  private recordRowReadCell(
+    key: string | null,
+    fieldName: string,
+    persisted: boolean,
+  ): void {
+    if (!key || !this.activeMapCellMeta) return;
+    const order = this.resolveRowReadOrder(key);
+    if (!order || order.columns.length === 0) return;
+    if (cellReadCut(order, fieldName) !== null) return;
+    if (persisted && order.columns.length < MAX_CELL_READ_REFS) {
+      this.mergeRowMeta(key, {
+        reads: { ...order, columns: [...order.columns, fieldName] },
+      });
+      return;
+    }
+    const upto = order.upto ?? {};
+    if (Object.keys(upto).length >= MAX_ROW_READ_CELLS) {
+      this.mergeRowMeta(key, {
+        reads: { ...order, droppedCells: (order.droppedCells ?? 0) + 1 },
+      });
+      return;
+    }
+    this.mergeRowMeta(key, {
+      reads: { ...order, upto: { ...upto, [fieldName]: order.columns.length } },
+    });
+  }
+
+  /** Seed the row's read order with the columns the row arrived carrying. */
+  private recordRowReadColumns(
+    key: string | null,
+    columns: readonly string[],
+  ): void {
+    if (!key || !this.activeMapCellMeta || columns.length === 0) return;
+    const order = this.resolveRowReadOrder(key);
+    const merged = order ? [...order.columns] : [];
+    for (const column of columns) {
+      if (merged.length >= MAX_CELL_READ_REFS) break;
+      if (merged.includes(column)) continue;
+      merged.push(column);
+    }
+    if (order && merged.length === order.columns.length) return;
+    this.mergeRowMeta(key, {
+      reads: { ...(order ?? {}), columns: merged },
+    });
+  }
+
+  /** Merge a row-grain record under the reserved `_row` cell-meta key. */
+  private mergeRowMeta(key: string, record: PlayRowMeta): void {
+    if (!this.activeMapCellMeta) return;
+    const existingRow = this.activeMapCellMeta.get(key);
+    const existingMeta = this.activeCellMetaRecord(key, ROW_META_CELL_KEY);
+    this.activeMapCellMeta.set(key, {
+      ...(existingRow ?? {}),
+      [ROW_META_CELL_KEY]: { ...(existingMeta ?? {}), ...record },
+    });
+  }
+
+  /**
+   * Explicit per-cell read array, re-stated so a later patch cannot erase it.
+   *
+   * Only nested step-program cells carry one: their read-set includes sibling
+   * steps, which are not part of the row's column order, so the row-grain cut
+   * point cannot express it. Dataset columns resolve through the row order.
+   */
+  private resolveCellReads(
+    key: string | null,
+    fieldName: string,
+  ): PlayCellReadRef[] | undefined {
+    const reads = this.activeCellMetaRecord(key, fieldName)?.reads;
+    return Array.isArray(reads) ? (reads as PlayCellReadRef[]) : undefined;
+  }
+
+  /** The read-set a cell saw, from its explicit array or the row order. */
+  private effectiveCellReads(
+    key: string | null,
+    fieldName: string,
+  ): PlayCellReadRef[] {
+    return (
+      this.resolveCellReads(key, fieldName) ??
+      hydrateCellReadRefs(this.resolveRowReadOrder(key), fieldName, '')?.map(
+        (ref) => ({ column: ref.column }),
+      ) ??
+      []
+    );
+  }
+
+  /** Last recorded branch decision for a cell, re-stated on every patch. */
+  private resolveCellDecision(
+    key: string | null,
+    fieldName: string,
+  ): PlayCellDecision | undefined {
+    const decide = this.activeCellMetaRecord(key, fieldName)?.decide;
+    return decide && typeof decide === 'object' && !Array.isArray(decide)
+      ? (decide as PlayCellDecision)
+      : undefined;
+  }
+
+  /**
+   * Bounded read-set for one cell (ADR 0019).
+   *
+   * The runtime hands a column resolver the whole row, so the read-set it
+   * witnesses is the row's columns at eval time — not a per-property access
+   * trace. Recording the resolved column list as-is is the honest form: it is a
+   * superset of what the resolver touched, and it is an observation rather than
+   * a declaration. Per-property precision needs sandbox proxy tracking, which
+   * is deliberately out of this wave.
+   *
+   * Only enumerable columns are recorded. CSV alias projections are
+   * non-enumerable by construction, so they read as absent rather than as a
+   * column the runtime can name.
+   *
+   * Refs carry no `table` or `rowKey` because every read here is same-row and
+   * same-table; the reader fills both in from the cell's own address. Writing
+   * the row key into each ref put a mapped row over the retained-row memory
+   * budget, and the budget is not the thing that moves.
+   */
+  private cellReadRefsForRow(
+    rowKey: string | null,
+    rowSources: readonly Record<string, unknown>[],
+    targetFieldName: string,
+    /**
+     * Columns this map will write but has not written yet in this run. On a
+     * rerun the row arrives carrying their previous values, which is
+     * `previousCell` — the same fact the self-exclusion below rejects, and
+     * recording it would manufacture a cycle between two columns that each
+     * saw the other's stale value.
+     */
+    pendingOutputColumns?: ReadonlySet<string>,
+  ): PlayCellReadRef[] | undefined {
+    if (!rowKey) return undefined;
+    const refs: PlayCellReadRef[] = [];
+    const seen = new Set<string>();
+    for (const source of rowSources) {
+      for (const column of Object.keys(source)) {
+        if (refs.length >= MAX_CELL_READ_REFS) break;
+        // A cell never reads itself: on a rerun the target column is present in
+        // the row carrying the *previous* run's value, which is a different
+        // fact (`previousCell`), not an input to this computation.
+        if (column === targetFieldName) continue;
+        if (pendingOutputColumns?.has(column)) continue;
+        if (!shouldPersistMapCellField(column)) continue;
+        if (column.startsWith('__deepline')) continue;
+        if (seen.has(column)) continue;
+        seen.add(column);
+        refs.push({ column });
+      }
+    }
+    return refs.length > 0 ? refs : undefined;
+  }
+
+  /**
+   * The row's input columns — everything the first cell of the row could read.
+   * Columns this map writes are excluded even when the row already carries a
+   * value for them, because on a rerun that value is the previous run's.
+   */
+  private rowInputReadColumns(
+    baseRow: Record<string, unknown>,
+    datasetColumns: ReadonlySet<string>,
+  ): string[] {
+    const columns: string[] = [];
+    for (const column of Object.keys(baseRow)) {
+      if (columns.length >= MAX_CELL_READ_REFS) break;
+      if (datasetColumns.has(column)) continue;
+      if (!shouldPersistMapCellField(column)) continue;
+      if (column.startsWith('__deepline')) continue;
+      columns.push(column);
+    }
+    return columns;
+  }
+
   private emitScopedFieldMetaUpdate(input: {
     rowId: number;
     key: string | null;
@@ -3375,6 +4094,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       toolId?: string | null;
       runId?: string | null;
     } | null;
+    /**
+     * A newly started producer attempt for this cell (ADR 0018). The record is
+     * appended to the cell's bounded `producers` trace and kept by reference so
+     * the caller can settle its outcome/duration in place.
+     */
+    producerAttempt?: PlayCellProducerAttempt;
     dataPatch?: Record<string, unknown>;
   }): void {
     if (!input.fieldName) {
@@ -3389,6 +4114,46 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       return;
     }
 
+    // Every patch for a cell re-states its producer trace. The in-memory cell
+    // patch merge replaces a field wholesale, so carrying the array forward is
+    // what keeps a waterfall's losing legs alive through the cell's completion
+    // patch (which deliberately omits `producer`).
+    //
+    // Everything from here to `rowReads` is the attribution capture the docflow
+    // campaign added (ADR 0018 producers, ADR 0019 reads/decide). Resolved as a
+    // block behind the run's rollout answer so that an ungated run emits the
+    // cell patch main emitted, key for key — including OMITTING `producer` when
+    // the caller passed none, which is the one pre-existing key whose behavior
+    // the re-statement rule changed.
+    const capture = this.docflowCaptureEnabled;
+    const { producers, attemptsDropped } = capture
+      ? this.resolveCellProducers(
+          input.key,
+          input.fieldName,
+          input.producerAttempt,
+        )
+      : { producers: undefined, attemptsDropped: 0 };
+    // The durable jsonb merge preserves keys a patch omits; the in-memory cell
+    // patch merge replaces the field wholesale. Re-state the winning producer
+    // so the cell's terminal write does not erase it (ADR 0018).
+    const producer =
+      input.producer !== undefined
+        ? input.producer
+        : capture
+          ? this.resolveCellProducer(input.key, input.fieldName)
+          : undefined;
+    // Same re-statement discipline for the provenance capture (ADR 0019): both
+    // were seeded before the cell resolved, and the wholesale field replace
+    // would otherwise drop them on the cell's terminal patch.
+    const reads = capture
+      ? this.resolveCellReads(input.key, input.fieldName)
+      : undefined;
+    const decide = capture
+      ? this.resolveCellDecision(input.key, input.fieldName)
+      : undefined;
+    // The row's read order is row-grain, so it rides the patch once under the
+    // reserved key rather than being copied onto every cell.
+    const rowReads = capture ? this.resolveRowReadOrder(input.key) : undefined;
     this.emitScopedRowUpdate(input.key, input.tableNamespace, {
       rowId: input.rowId,
       status: input.rowStatus,
@@ -3396,13 +4161,27 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       provider: input.provider ?? null,
       error: input.error ?? null,
       dataPatch: input.dataPatch ?? {},
+      ...(rowReads ? { rowMetaPatch: { reads: rowReads } } : {}),
       cellMetaPatch: {
         [input.fieldName]: {
           status: input.status,
           stage: input.stage ?? null,
           provider: input.provider ?? null,
           error: input.error ?? null,
-          ...(input.producer !== undefined ? { producer: input.producer } : {}),
+          ...(producer !== undefined ? { producer } : {}),
+          // Only attribution-bearing cells carry the run stamp and the trace.
+          // Both ride the retained-row payload, so paying for them on every
+          // status-only cell patch would move the map memory budget.
+          ...(producers !== undefined
+            ? {
+                runId: this.currentRunId,
+                producers,
+                // Loud under-count: a capped trace states what it lost.
+                ...(attemptsDropped > 0 ? { attemptsDropped } : {}),
+              }
+            : {}),
+          ...(reads !== undefined ? { reads } : {}),
+          ...(decide !== undefined ? { decide } : {}),
           ...(input.reused !== undefined ? { reused: input.reused } : {}),
           ...(input.completedAt !== undefined
             ? { completedAt: input.completedAt }
@@ -3416,53 +4195,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     });
   }
 
-  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;
-    producer?: {
-      kind: 'play' | 'tool' | 'code';
-      id?: string | null;
-      displayName?: string | null;
-      playId?: string | null;
-      toolId?: string | null;
-      runId?: string | null;
-    } | 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,
-          ...(input.producer !== undefined ? { producer: input.producer } : {}),
-        },
-      },
-    });
-  }
-
   private isCompletedFieldValue(value: unknown): boolean {
     return (
       value !== null &&
@@ -4327,6 +5059,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         options.onRowError,
       );
       validateOptionalPlayAuthoringField('ctx.dataset.run.mode', options.mode);
+      validateOptionalPlayAuthoringField(
+        'ctx.dataset.run.undrawnColumns',
+        options.undrawnColumns,
+      );
       if (options.key !== undefined) {
         validatePlayAuthoringField('ctx.dataset.run.key', options.key);
       }
@@ -5732,6 +6468,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   ): Promise<FieldMapRunResult> {
     const fieldEntries = Object.entries(definition);
     const datasetColumnNames = fieldEntries.map(([fieldName]) => fieldName);
+    /** Columns this map writes; excluded from a row's input read order. */
+    const datasetColumnSet = new Set(datasetColumnNames);
     const visibleFields = fieldEntries
       .map(([fieldName]) => fieldName)
       .filter((fieldName) => shouldPersistMapCellField(fieldName));
@@ -6046,6 +6784,19 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       const rowIndex = executionRowIndex(idx);
       const computedFields: Record<string, unknown> = {};
       let activeFieldName: string | null = null;
+      // ADR 0019: the row's read order, computed once. Every cell reads a
+      // prefix of it — the inputs, then each column this run wrote — so this
+      // loop appends rather than rebuilding a per-cell set (which was
+      // O(columns squared) in both time and allocations).
+      if (this.docflowCaptureEnabled) {
+        this.recordRowReadColumns(
+          rowKey,
+          this.rowInputReadColumns(baseRow, datasetColumnSet),
+        );
+      }
+      if (this.docflowCaptureEnabled) {
+        this.seedActiveCellProducersFromDurableRow(rowKey, baseRow);
+      }
 
       // Global row slot keeps concurrent maps in the same run under rowMax. The
       // worker pool below enforces this map's requested/default concurrency.
@@ -6055,6 +6806,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       try {
         for (const [fieldName, resolver] of fieldEntries) {
           activeFieldName = fieldName;
+          // Recorded before the first patch for the cell, so every later patch
+          // (tool legs, completion) re-states the row order for free.
+          this.recordRowReadCell(
+            rowKey,
+            fieldName,
+            shouldPersistMapCellField(fieldName),
+          );
           this.emitScopedFieldMetaUpdate({
             rowId: idx,
             key: rowKey,
@@ -6495,8 +7253,27 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   ): Promise<unknown> {
     let currentRow = cloneCsvAliasedRow(row);
     const produced: Record<string, unknown> = {};
+    // Steps this program has not run yet. Hoisted per program, not rebuilt per
+    // step, and shrunk as each step produces.
+    const pendingStepNames = new Set(program.steps.map((step) => step.name));
     for (const step of program.steps) {
       const stepPath = [...path, step.name];
+      // ADR 0019: a step's read-set is the row as it stands *now*, which
+      // includes every earlier step's output. Sibling steps are not part of the
+      // row's column order, so a step cell keeps an explicit array where a
+      // dataset column resolves through the row-grain cut point. Recorded
+      // before the step runs so the step's own cell patches re-state it.
+      const stepRowStore = rowContext.getStore();
+      if (this.docflowCaptureEnabled && stepRowStore?.rowKey) {
+        this.recordCellProvenance(stepRowStore.rowKey, stepPath.join('.'), {
+          reads: this.cellReadRefsForRow(
+            stepRowStore.rowKey,
+            [currentRow],
+            stepPath.join('.'),
+            pendingStepNames,
+          ),
+        });
+      }
       const runStep = async () =>
         options?.checkpointSteps
           ? await this.step(
@@ -6554,10 +7331,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           });
         }
         produced[step.name] = value;
+        pendingStepNames.delete(step.name);
         currentRow = cloneCsvAliasedRow(currentRow, { [step.name]: value });
         continue;
       }
       produced[step.name] = value;
+      pendingStepNames.delete(step.name);
       const rowStore = rowContext.getStore();
       const fieldName = stepPath.join('.');
       const patchFieldName = runtimeSheetPatchFieldName(fieldName);
@@ -6615,6 +7394,22 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
     if (isRuntimeConditionalStepResolver(resolver)) {
       const shouldRun = await resolver.when(currentRow, index);
+      // ADR 0019: the per-row branch this evaluator selected, written onto the
+      // cell the decision governs. `run`/`else` is the runtime's own vocabulary
+      // for a `runIf` conditional — the only per-row branch construct the
+      // runtime evaluates. A branch inside authored code is invisible here and
+      // degrades to the transform's read-set, which is the honest floor.
+      if (this.docflowCaptureEnabled && store?.rowKey) {
+        // The evaluator was handed the same row the resolver would get, so the
+        // decision's read-set is the cell's read-set. Reusing the seeded trace
+        // keeps the two consistent and costs no second pass over the row.
+        this.recordCellProvenance(store.rowKey, nestedFieldName, {
+          decide: {
+            branch: shouldRun ? 'run' : 'else',
+            reads: this.effectiveCellReads(store.rowKey, nestedFieldName),
+          },
+        });
+      }
       if (!shouldRun) {
         const elseValue = Object.prototype.hasOwnProperty.call(
           resolver,
@@ -6680,6 +7475,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     rowIdentity: (row: Record<string, unknown>, index: number) => string,
   ): Promise<Array<Record<string, unknown>>> {
     const results: Array<Record<string, unknown>> = [];
+    const pureDatasetColumnSet = new Set(
+      fieldEntries.map(([fieldName]) => fieldName),
+    );
     this.pureMapExecutionActive = true;
 
     try {
@@ -6688,6 +7486,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         const baseRow = this.toOutputRow(item);
         const computedFields: Record<string, unknown> = {};
         let activeFieldName: string | null = null;
+        // The pure path emits one consolidated patch per row, so the read
+        // trace is stamped straight onto that patch (ADR 0019) instead of
+        // riding the seed-and-re-state path the row loop uses.
+        const pureRowKey = rowIdentity(baseRow, index);
 
         // Pure rows complete in microseconds, so interim per-field updates
         // carry no live value. Accumulate every field's data/meta patch and
@@ -6698,9 +7500,39 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         const rowDataPatch: Record<string, unknown> = {};
         const rowCellMetaPatch: NonNullable<PlayRowUpdate['cellMetaPatch']> =
           {};
+        // ADR 0019 row-grain read order, built once per row on the consolidated
+        // patch this path already emits.
+        //
+        // Ungated this stays empty, which is the gate: the per-field branch
+        // below already treats an empty order as "nothing was available to
+        // read" and does no work, and the two `length > 0` guards on the
+        // consolidated patches omit `rowMetaPatch` entirely. This path never
+        // touches `activeMapCellMeta`, so it has to be stopped here or not at
+        // all.
+        const pureReadColumns = this.docflowCaptureEnabled
+          ? this.rowInputReadColumns(baseRow, pureDatasetColumnSet)
+          : [];
+        const pureReadUpto: Record<string, number> = {};
         try {
           for (const [fieldName, resolver] of fieldEntries) {
             activeFieldName = fieldName;
+            // A written column joins the order before its own cell runs, so
+            // its position is its cut; anything the list cannot place states
+            // an explicit one.
+            if (pureReadColumns.length === 0) {
+              // Nothing was available to read.
+            } else if (
+              shouldPersistMapCellField(fieldName) &&
+              pureReadColumns.length < MAX_CELL_READ_REFS &&
+              !pureReadColumns.includes(fieldName)
+            ) {
+              pureReadColumns.push(fieldName);
+            } else if (
+              Object.keys(pureReadUpto).length < MAX_ROW_READ_CELLS &&
+              !pureReadColumns.includes(fieldName)
+            ) {
+              pureReadUpto[fieldName] = pureReadColumns.length;
+            }
             const value = await this.resolveMapFieldValue(
               resolver,
               item,
@@ -6725,20 +7557,30 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             this.toPublicOutputRow(cloneCsvAliasedRow(baseRow, computedFields)),
           );
 
-          const rowKey = rowIdentity(baseRow, index);
           activeFieldName = null;
-          this.emitScopedRowUpdate(rowKey, tableNamespace, {
+          this.emitScopedRowUpdate(pureRowKey, tableNamespace, {
             rowId: index,
             status: 'completed',
             stage: 'completed',
             provider: null,
             error: null,
             dataPatch: rowDataPatch,
+            ...(pureReadColumns.length > 0
+              ? {
+                  rowMetaPatch: {
+                    reads: {
+                      columns: pureReadColumns,
+                      ...(Object.keys(pureReadUpto).length > 0
+                        ? { upto: pureReadUpto }
+                        : {}),
+                    },
+                  },
+                }
+              : {}),
             cellMetaPatch: rowCellMetaPatch,
           });
         } catch (error) {
-          const rowKey = rowIdentity(baseRow, index);
-          this.emitScopedRowUpdate(rowKey, tableNamespace, {
+          this.emitScopedRowUpdate(pureRowKey, tableNamespace, {
             rowId: index,
             status: 'failed',
             stage: 'failed',
@@ -6747,6 +7589,18 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             // Carry the cells that completed before the failure — previously
             // they had already been emitted as individual field updates.
             dataPatch: rowDataPatch,
+            ...(pureReadColumns.length > 0
+              ? {
+                  rowMetaPatch: {
+                    reads: {
+                      columns: pureReadColumns,
+                      ...(Object.keys(pureReadUpto).length > 0
+                        ? { upto: pureReadUpto }
+                        : {}),
+                    },
+                  },
+                }
+              : {}),
             cellMetaPatch: {
               ...rowCellMetaPatch,
               [String(activeFieldName ?? '__unknown')]: {
@@ -7239,89 +8093,150 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               );
         if (cached) {
           this.log(`Calling tool: ${toolId} recovered from checkpoint`);
-          return await this.wrapToolExecutionResult({
-            toolId,
-            status: cached.result.result == null ? 'no_result' : 'completed',
-            result: cached.result.result,
-            requestInput: input,
-            execution: toolExecutionMetadataForOutcome({
-              kind: 'checkpoint',
-              cacheKey: cached.cacheKey,
-            }),
-          });
+          // Started and settled are paired in a finally: an uncovered throw
+          // between them strands the tool node `running` forever in the
+          // snapshot, which is exactly the lossy state ADR 0018 removed.
+          this.emitToolCallLifecycle('started', toolId, normalizedKey);
+          let settled = false;
+          try {
+            const recovered = await this.wrapToolExecutionResult({
+              toolId,
+              status: cached.result.result == null ? 'no_result' : 'completed',
+              result: cached.result.result,
+              requestInput: input,
+              execution: toolExecutionMetadataForOutcome({
+                kind: 'checkpoint',
+                cacheKey: cached.cacheKey,
+              }),
+            });
+            settled = true;
+            this.emitToolCallLifecycle('settled', toolId, normalizedKey, {
+              outcome: 'cached',
+              durationMs: 0,
+            });
+            return recovered;
+          } finally {
+            if (!settled) {
+              this.emitToolCallLifecycle('settled', toolId, normalizedKey, {
+                outcome: 'failed',
+                durationMs: 0,
+              });
+            }
+          }
         }
         this.log(
           toolCachePolicy.force
             ? `Calling tool: ${toolId} (force)`
             : `Calling tool: ${toolId}`,
         );
-        const directReceiptLeaseId = context?.leaseId?.trim() || null;
-        if (!logicalCallId) {
-          throw new Error(
-            'Direct tool execution requires a stable logical call identity.',
-          );
-        }
-        const physicalDirectKey = cacheableToolResult
-          ? directCacheKey
-          : `${buildDurableToolReceiptPrefix({
-              orgId: this.#options.orgId ?? 'unknown-org',
-              toolId,
-            })}${stableDigest(`${this.currentRunId}:${logicalCallId}:always-fresh`)}`;
-        const execution = await this.callToolExecutionAPI(toolId, input, {
-          durableCallReceiptKey: physicalDirectKey,
-          executionAuthScopeDigest,
-          providerIdempotencyKey: cacheableToolResult
-            ? this.providerIdempotencyKeyForToolCall({
-                cacheKey: directCacheKey,
-                force: toolCachePolicy.force,
-                leaseId: directReceiptLeaseId,
-                logicalCallId,
-              })
-            : physicalDirectKey,
-          timeoutMs: resolveToolRuntimeTimeoutMs(
+        // ADR 0018: the tool node's lifecycle is an explicit typed event, not a
+        // regex over this log line.
+        const directCallStartedAt = Date.now();
+        this.emitToolCallLifecycle('started', toolId, normalizedKey);
+        // Settled exactly once, including on paths that throw before the
+        // explicit settle below (result wrapping, receipt-ownership failures,
+        // authoring validation). `executeDirectToolCall` settles its own
+        // transport failure and marks this handled.
+        let directSettled = false;
+        const settleDirectCall = (
+          outcome: 'completed' | 'no_result' | 'failed' | 'cached',
+          error?: unknown,
+        ) => {
+          if (directSettled) return;
+          directSettled = true;
+          this.emitToolCallLifecycle('settled', toolId, normalizedKey, {
+            outcome,
+            durationMs: Date.now() - directCallStartedAt,
+            ...(error !== undefined
+              ? { error: this.formatRuntimeError(error) }
+              : {}),
+          });
+        };
+        try {
+          const directReceiptLeaseId = context?.leaseId?.trim() || null;
+          if (!logicalCallId) {
+            throw new Error(
+              'Direct tool execution requires a stable logical call identity.',
+            );
+          }
+          const physicalDirectKey = cacheableToolResult
+            ? directCacheKey
+            : `${buildDurableToolReceiptPrefix({
+                orgId: this.#options.orgId ?? 'unknown-org',
+                toolId,
+              })}${stableDigest(`${this.currentRunId}:${logicalCallId}:always-fresh`)}`;
+          const execution = await this.executeDirectToolCall({
             toolId,
-            options?.timeoutMs,
-            this.currentAuthoringContractEdition,
-          ),
-          ...(directReceiptLeaseId &&
-          (this.#options.heartbeatRuntimeStepReceipts ||
-            this.#options.getRuntimeStepReceipt ||
-            this.#options.getRuntimeStepReceipts)
-            ? {
-                beforeProviderCall: async () => {
-                  await this.assertRuntimeToolReceiptOwnership([
-                    {
-                      callId: 'direct',
-                      cacheKey: directCacheKey,
-                      receiptKey: directCacheKey,
-                      receiptLeaseId: directReceiptLeaseId,
-                      rowId: -1,
-                      toolId,
-                      input,
+            callKey: normalizedKey,
+            startedAt: directCallStartedAt,
+            input,
+            options: {
+              durableCallReceiptKey: physicalDirectKey,
+              playNodeScope: buildPlayNodeScope({
+                toolId,
+                callKey: normalizedKey,
+              }),
+              executionAuthScopeDigest,
+              providerIdempotencyKey: cacheableToolResult
+                ? this.providerIdempotencyKeyForToolCall({
+                    cacheKey: directCacheKey,
+                    force: toolCachePolicy.force,
+                    leaseId: directReceiptLeaseId,
+                    logicalCallId,
+                  })
+                : physicalDirectKey,
+              timeoutMs: resolveToolRuntimeTimeoutMs(
+                toolId,
+                options?.timeoutMs,
+                this.currentAuthoringContractEdition,
+              ),
+              ...(directReceiptLeaseId &&
+              (this.#options.heartbeatRuntimeStepReceipts ||
+                this.#options.getRuntimeStepReceipt ||
+                this.#options.getRuntimeStepReceipts)
+                ? {
+                    beforeProviderCall: async () => {
+                      await this.assertRuntimeToolReceiptOwnership([
+                        {
+                          callId: 'direct',
+                          cacheKey: directCacheKey,
+                          receiptKey: directCacheKey,
+                          receiptLeaseId: directReceiptLeaseId,
+                          rowId: -1,
+                          toolId,
+                          input,
+                        },
+                      ]);
                     },
-                  ]);
-                },
-              }
-            : {}),
-        });
-        const wrapped = await this.wrapToolExecutionResult({
-          toolId,
-          status: execution.status,
-          jobId: execution.jobId,
-          result: execution.result,
-          metadata: execution.metadata,
-          meta: execution.meta,
-          requestInput: input,
-          execution: toolExecutionMetadataForOutcome({
-            kind: 'live',
-            cacheKey: directCacheKey,
-          }),
-        });
-        if (cacheableToolResult) {
-          this.cacheToolResult(toolId, directCacheKey, wrapped, 'direct');
-          this.#options.onBatchComplete?.(this.checkpoint);
+                  }
+                : {}),
+            },
+          });
+          const wrapped = await this.wrapToolExecutionResult({
+            toolId,
+            status: execution.status,
+            jobId: execution.jobId,
+            result: execution.result,
+            metadata: execution.metadata,
+            meta: execution.meta,
+            requestInput: input,
+            execution: toolExecutionMetadataForOutcome({
+              kind: 'live',
+              cacheKey: directCacheKey,
+            }),
+          });
+          settleDirectCall(toolAttemptOutcomeForResult(wrapped));
+          if (cacheableToolResult) {
+            this.cacheToolResult(toolId, directCacheKey, wrapped, 'direct');
+            this.#options.onBatchComplete?.(this.checkpoint);
+          }
+          return wrapped;
+        } catch (error) {
+          settleDirectCall('failed', error);
+          throw error;
+        } finally {
+          settleDirectCall('failed');
         }
-        return wrapped;
       }
 
       const rowId = store.rowId;
@@ -7361,7 +8276,27 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         });
       }
 
-      return new Promise((resolve, reject) => {
+      // ADR 0018: record this leg before it runs. `producer` still names the
+      // last leg (the usual cascade winner); `producers` keeps every leg, which
+      // is the only durable record a losing leg ever gets — a failed tool call
+      // writes no receipt at all.
+      const producerAttemptStartedAt = Date.now();
+      // Deliberately minimal: `displayName` is derivable from `toolId`, and
+      // this record is retained per row until the map's persistence barrier.
+      const producerAttempt: PlayCellProducerAttempt = {
+        kind: 'tool',
+        id: normalizedKey,
+        toolId,
+        at: producerAttemptStartedAt,
+        outcome: 'running',
+      };
+      const settleProducerAttempt = (
+        outcome: PlayCellProducerAttempt['outcome'],
+      ) => {
+        producerAttempt.outcome = outcome;
+        producerAttempt.durationMs = Date.now() - producerAttemptStartedAt;
+      };
+      const pendingToolCall = new Promise((resolve, reject) => {
         this.toolCallResolvers.set(callId, { resolve, reject });
         this.emitScopedFieldMetaUpdate({
           rowId,
@@ -7379,6 +8314,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             toolId,
             displayName: displayNameFromProducerId(toolId),
           },
+          producerAttempt,
           dataPatch: {},
         });
         const timeoutMs = resolveToolRuntimeTimeoutMs(
@@ -7396,6 +8332,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           forceFailedRefresh: toolCachePolicy.forceFailedRefresh,
           rowId,
           fieldName,
+          contextKey: normalizedKey,
           toolId,
           input,
           ...(timeoutMs !== undefined ? { timeoutMs } : {}),
@@ -7407,6 +8344,16 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           description: normalizeStepDescription(options?.description),
         });
       });
+      return await pendingToolCall.then(
+        (value) => {
+          settleProducerAttempt(toolAttemptOutcomeForResult(value));
+          return value;
+        },
+        (error: unknown) => {
+          settleProducerAttempt('failed');
+          throw error;
+        },
+      );
     };
 
     if (store || !cacheableToolResult) {
@@ -8845,6 +9792,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     beforeProviderCall: () =>
                       this.assertRuntimeToolReceiptOwnership([owner]),
                     durableCallReceiptKey: receiptKey,
+                    playNodeScope: playNodeScopeForToolCallRequest(owner),
                     executionAuthScopeDigest: owner.executionAuthScopeDigest,
                     receiptLeaseExpiresAt: owner.receiptLeaseExpiresAt,
                     heartbeatReceipt: () =>
@@ -9096,6 +10044,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     batch.batchPayload,
                     {
                       durableCallReceiptKey: aggregateReceiptKey,
+                      // A native batch is one physical provider request for
+                      // many rows of the same column, so the batch's node scope
+                      // is its members' shared scope.
+                      playNodeScope: batch.memberRequests[0]
+                        ? playNodeScopeForToolCallRequest(
+                            batch.memberRequests[0],
+                            batch.batchOperation,
+                          )
+                        : null,
                       executionAuthScopeDigest:
                         batch.memberRequests[0]?.executionAuthScopeDigest ??
                         null,
@@ -9284,6 +10241,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     {
                       beforeProviderCall: () =>
                         this.assertRuntimeToolReceiptOwnership([request]),
+                      playNodeScope: playNodeScopeForToolCallRequest(request),
                       ...(request.receiptKey
                         ? {
                             durableCallReceiptKey: request.receiptKey,
@@ -9588,6 +10546,11 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           const deeplineRequestId = providerIdempotencyKey
             ? `ctx-tool-${stableDigest(providerIdempotencyKey).slice(0, 32)}`
             : `ctx-tool-${crypto.randomUUID()}`;
+          // Every runtime provider call carries at least a tool-scoped
+          // attribution. Callers that know the execution location (row-scoped
+          // map cells, batched owners) supply the fuller scope.
+          const playNodeScope =
+            options?.playNodeScope ?? buildPlayNodeScope({ toolId });
           const serializedRequestBody = (invocationAttempt: number) =>
             JSON.stringify({
               payload: toolInputSnapshot,
@@ -9631,6 +10594,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 ...(providerIdempotencyKey
                   ? { provider_idempotency_key: providerIdempotencyKey }
                   : {}),
+                ...(playNodeScope
+                  ? { play_node_scope: playNodeScopeToWire(playNodeScope) }
+                  : {}),
               },
               ...(this.#options.integrationMode
                 ? { integration_mode: this.#options.integrationMode }