deepline 0.2.53 → 0.2.55

package/dist/bundling-sources/shared_libs/play-runtime/execution-capabilities.ts

@@ -46,6 +46,20 @@ export type RuntimeAuthorityDescriptor = {
   synthetic?: boolean | null;
   actorUserId?: string | null;
   actorEmail?: string | null;
+  /**
+   * Whether THIS run may capture the docflow provenance trace.
+   *
+   * Resolved once, server-side, at run admission — the only place that has both
+   * an actor and the rollout catalog. The runtime executes in a sandbox or on
+   * the customer's machine with no auth context and must never ask: capture is
+   * per-row on the hottest path there is, so the answer has to arrive as a fact
+   * it was handed, like `maxCreditsPerRun` and `integrationMode` beside it.
+   *
+   * Absent means OFF. A launch queued before this field existed, a scheduler
+   * that drops unknown keys, a caller that forgets to thread it — all land on
+   * the pre-feature behavior, which is the whole point of the switch.
+   */
+  docflowEnabled?: boolean | null;
   capabilities: RuntimeExecutionCapability[];
 };
 
@@ -128,6 +142,10 @@ export function requireRuntimeAuthorityDescriptor(
     synthetic: descriptor.synthetic === true,
     actorUserId: descriptor.actorUserId ?? null,
     actorEmail: descriptor.actorEmail ?? null,
+    // `=== true`, not `?? false`: the normalizer is what a durable launch is
+    // read back through, so anything that is not an explicit yes — missing,
+    // null, a string that survived a JSON round trip — denies.
+    docflowEnabled: descriptor.docflowEnabled === true,
     capabilities,
   };
 }

package/dist/bundling-sources/shared_libs/play-runtime/live-state-contract.ts

@@ -1,4 +1,5 @@
 import type { PlayRunLifecycleStatus } from './run-lifecycle-policy';
+import type { PlayDocflowNodeIoState } from './docflow-node-io';
 import type {
   PlayActivityObservation,
   PlayRunActivityProjection,
@@ -28,6 +29,36 @@ export type PlayVisualNodeProgressSnapshot = {
   startedAt?: number | null;
   completedAt?: number | null;
   artifactTableNamespace?: string | null;
+  nodeIo?: PlayDocflowNodeIoState;
+};
+
+/**
+ * Observed provider usage for one graph node (ADR 0018). Server-computed at
+ * read time from the Runtime Sheet producer trace plus the node-scoped usage
+ * events; never derived in the browser and never from event counters.
+ */
+export type PlayVisualNodeToolUsageSnapshot = {
+  toolId: string;
+  provider: string;
+  column?: string | null;
+  /** Per-row logical invocations, including losing cascade legs. */
+  logicalCalls: number;
+  /** Physical provider requests (one native batch answers many rows). */
+  providerRequests: number;
+  winningCells: number;
+  reusedCells: number;
+  failedCalls: number;
+  credits: number;
+  deeplineCostUsd: number;
+  durationMsTotal: number | null;
+};
+
+export type PlayVisualNodeUsageSnapshot = {
+  tools: PlayVisualNodeToolUsageSnapshot[];
+  totalCredits: number;
+  totalProviderRequests: number;
+  totalLogicalCalls: number;
+  totalDurationMs: number | null;
 };
 
 export type PlayVisualNodeStateSnapshot = {
@@ -39,6 +70,8 @@ export type PlayVisualNodeStateSnapshot = {
   startedAt?: number | null;
   completedAt?: number | null;
   updatedAt?: number | null;
+  nodeIo?: PlayDocflowNodeIoState;
+  usage?: PlayVisualNodeUsageSnapshot;
 };
 
 export type PlayRunLiveSnapshot = {

package/dist/bundling-sources/shared_libs/play-runtime/log-provenance.ts

@@ -0,0 +1,251 @@
+/**
+ * Play Runtime Log Provenance.
+ *
+ * A play run emits a stream of log / step / progress lines from very different
+ * places: the customer's own play code, the runtime's step lifecycle, replays
+ * that re-run already-completed work, scheduler/sandbox internals, warnings,
+ * and receipt/billing plumbing. On the wire they are all plain strings in one
+ * ordered log buffer (`ctx.getLogs()` → `play.run.log`), so historically each
+ * consumer re-derived "is this line noise?" with its own ad-hoc substring
+ * match (`isInternalLogLine` in the dashboard, the `[worker] ...` regex ladder
+ * in the SDK watch renderer). Those drifted apart and leaked internal churn to
+ * users.
+ *
+ * This module is the single source of truth. It defines:
+ *   1. `LogProvenance` — a CLOSED discriminated set naming WHO/WHY emitted a
+ *      line. Adding a class is a compile error everywhere that must route it.
+ *   2. `LOG_PROVENANCE_POLICY` — the one table mapping each class to the
+ *      surfaces it reaches (`watch`, `ui`, `debug`). Exhaustive over the union.
+ *   3. A structural tag carrier (`PROVENANCE_PREFIX`) so NEW emissions carry
+ *      their class inline in the log string without breaking persisted-log
+ *      readers, plus a legacy classifier (`classifyLegacyLogLine`) for old
+ *      untagged lines.
+ *
+ * Do NOT re-implement provenance decisions with ad-hoc string matching
+ * elsewhere. Import `classifyLogLine` + `logProvenanceReaches`.
+ */
+
+/**
+ * Closed set of provenance classes. Each names WHO emitted the line and WHY.
+ * Fewer, sharper classes on purpose — a consumer only needs to know which
+ * surface a line belongs on, not its exact emitter.
+ */
+export type LogProvenance =
+  /** Play code output: `ctx.log(...)` and captured `[console.*]` from the
+   *  play body. The customer wrote this; it is always in-scope everywhere. */
+  | 'user'
+  /** Runtime step/node lifecycle and map progress narration the runtime emits
+   *  to explain forward progress. The useful backbone of a `--watch` run. */
+  | 'lifecycle'
+  /** Deterministic re-execution echoes: a resumed/replayed attempt re-runs
+   *  already-durable work and reprints the same lines ("recovered from
+   *  checkpoint", re-narrated step transitions). Real signal only once; the
+   *  replay copy is churn. */
+  | 'replay'
+  /** Scheduler / sandbox / worker internals: run-file prep, sandbox
+   *  lifecycle, `[perf]` timings, batch-drain bookkeeping. Operator-facing. */
+  | 'infra'
+  /** Warnings and diagnostics: `[warn]`, `[error]`, `[runtime.*_failure]`,
+   *  and forward-looking hints. Surfaced because a human may need to act. */
+  | 'diagnostic'
+  /** Billing / receipt / ledger plumbing: receipt reads, completion sinks.
+   *  Never customer-facing. */
+  | 'receipt';
+
+/** Every provenance class, for exhaustiveness checks and tests. */
+export const LOG_PROVENANCE_CLASSES: readonly LogProvenance[] = [
+  'user',
+  'lifecycle',
+  'replay',
+  'infra',
+  'diagnostic',
+  'receipt',
+] as const;
+
+/** Rendering surfaces a log line can reach. */
+export type LogSurface =
+  /** The CLI `deepline plays run --watch` progress stream. */
+  | 'watch'
+  /** The dashboard run-detail log tail. */
+  | 'ui'
+  /** Verbose / `--debug` / internal inspection only. */
+  | 'debug';
+
+/**
+ * THE policy. Maps each provenance class to the surfaces it reaches. Exhaustive
+ * over `LogProvenance` by construction (a `Record`), so adding a class forces a
+ * routing decision here at compile time.
+ *
+ * Design intent:
+ *   - `watch` and `ui` carry what a person running/inspecting the play needs:
+ *     their own output, real step transitions, and warnings that matter.
+ *   - `replay`, `infra`, and `receipt` are internal churn — `debug` only. This
+ *     is what silences the repeated `step docflow:*` replay passes and the
+ *     scary-looking scaffolding on healthy runs.
+ *   - `debug` is a superset: everything is inspectable in verbose mode.
+ */
+export const LOG_PROVENANCE_POLICY: Record<
+  LogProvenance,
+  Readonly<Record<LogSurface, boolean>>
+> = {
+  user: { watch: true, ui: true, debug: true },
+  lifecycle: { watch: true, ui: true, debug: true },
+  replay: { watch: false, ui: false, debug: true },
+  infra: { watch: false, ui: false, debug: true },
+  diagnostic: { watch: true, ui: true, debug: true },
+  receipt: { watch: false, ui: false, debug: true },
+};
+
+/** True when a line of the given provenance should render on the surface. */
+export function logProvenanceReaches(
+  provenance: LogProvenance,
+  surface: LogSurface,
+): boolean {
+  return LOG_PROVENANCE_POLICY[provenance][surface];
+}
+
+/**
+ * Structural carrier for NEW emissions. A tagged line looks like:
+ *   `
prov:replay
<original line>`
+ * The sentinel is a control char that never appears in human log text, so old
+ * readers that don't know about it see a harmless invisible prefix rather than
+ * a mangled message, and `stripProvenanceTag` recovers the exact original.
+ *
+ * We deliberately do NOT put the tag inside the `[...]` bracket space that
+ * `formatPlayLogLine` / the dashboard timestamp parser rely on.
+ */
+const PROVENANCE_SENTINEL = '
';
+const PROVENANCE_PREFIX = `${PROVENANCE_SENTINEL}prov:`;
+
+/** Stamp a provenance class onto a log line for the wire. */
+export function tagLogProvenance(
+  provenance: LogProvenance,
+  line: string,
+): string {
+  return `${PROVENANCE_PREFIX}${provenance}${PROVENANCE_SENTINEL}${line}`;
+}
+
+/**
+ * Read a structural provenance tag off a line, if present, and return the tag
+ * plus the original untagged line. Returns `null` provenance when untagged.
+ */
+export function readProvenanceTag(line: string): {
+  provenance: LogProvenance | null;
+  line: string;
+} {
+  if (!line.startsWith(PROVENANCE_PREFIX)) {
+    return { provenance: null, line };
+  }
+  const end = line.indexOf(PROVENANCE_SENTINEL, PROVENANCE_PREFIX.length);
+  if (end === -1) {
+    return { provenance: null, line };
+  }
+  const candidate = line.slice(PROVENANCE_PREFIX.length, end);
+  const provenance = LOG_PROVENANCE_CLASSES.includes(
+    candidate as LogProvenance,
+  )
+    ? (candidate as LogProvenance)
+    : null;
+  return { provenance, line: line.slice(end + 1) };
+}
+
+/** Remove any provenance tag, yielding the original human-readable line. */
+export function stripProvenanceTag(line: string): string {
+  return readProvenanceTag(line).line;
+}
+
+/**
+ * Legacy classifier for old persisted log strings that carry NO structural
+ * tag. Mirrors — and supersedes — the two ad-hoc filters that used to live in
+ * `PlayRunDetailPanel.isInternalLogLine` and `formatPlayLogLine`. The patterns
+ * are the historical `[worker] ...` / `[event] ...` / `[perf] ...` shapes plus
+ * the checkpoint-replay marker. Order matters: most specific first.
+ *
+ * A legacy line the classifier can't place defaults to `user` — old runs
+ * predate structural tagging, and the safe default for an unrecognized line is
+ * to show it (never silently drop a line we can't prove is internal).
+ */
+export function classifyLegacyLogLine(line: string): LogProvenance {
+  const message = stripLeadingTimestamp(line);
+
+  // Replay / recovery echoes.
+  if (/recovered (?:from checkpoint|response from checkpoint)/i.test(message)) {
+    return 'replay';
+  }
+
+  // Receipt / ledger plumbing.
+  if (/^\[perf\] runtime receipt\b/i.test(message)) {
+    return 'receipt';
+  }
+
+  // Scheduler / sandbox / worker internals.
+  if (
+    /^\[perf\] runtime (?:map|state)\b/i.test(message) ||
+    /\[worker\] picked up run\b/.test(message) ||
+    /\[worker\] heartbeat\b/.test(message) ||
+    /\[worker\] progress completedRows=\d+ totalRows=\d+ rowUpdates=\d+/.test(
+      message,
+    ) ||
+    /\[worker\] step started\b/.test(message) ||
+    /\[worker\] Preparing run files\b/.test(message) ||
+    /\[worker\] Run files ready\b/.test(message) ||
+    /\[worker\] Runtime ready\b/.test(message) ||
+    /\[worker\] Sandbox (?:starting|create start|create done|workspace ready|upload start|runner uploaded)\b/.test(
+      message,
+    ) ||
+    /^\[event\] play\.step\.progress\b/.test(message) ||
+    /^\[event\] play\.run\.snapshot\b/.test(message) ||
+    /^\[event\] play\.sheet\.summary\b/.test(message)
+  ) {
+    return 'infra';
+  }
+
+  // Warnings / diagnostics.
+  if (
+    /^\[warn\]/i.test(message) ||
+    /^\[error\]/i.test(message) ||
+    /^\[runtime\.[a-z_]*(?:failure|error)\]/i.test(message)
+  ) {
+    return 'diagnostic';
+  }
+
+  return 'user';
+}
+
+/**
+ * Classify any log line — structurally tagged (new) or legacy (old) — into its
+ * provenance class, returning the class and the original human-readable line.
+ * This is the entry point every surface should use.
+ */
+export function classifyLogLine(line: string): {
+  provenance: LogProvenance;
+  line: string;
+} {
+  const tagged = readProvenanceTag(line);
+  if (tagged.provenance !== null) {
+    return { provenance: tagged.provenance, line: tagged.line };
+  }
+  return { provenance: classifyLegacyLogLine(tagged.line), line: tagged.line };
+}
+
+/** True when a raw (possibly tagged) log line should render on the surface. */
+export function logLineReaches(line: string, surface: LogSurface): boolean {
+  return logProvenanceReaches(classifyLogLine(line).provenance, surface);
+}
+
+/**
+ * Strip ONLY a leading timestamp bracket, if present. `ctx.log` stamps
+ * `[<ISO>] ` and the dashboard timeline stringifier prepends `[<ISO>] `
+ * followed by a `[<source>]` bracket. We must keep the `[<source>]` bracket
+ * (`[worker]`, `[event]`) because the legacy classifier's patterns key on it —
+ * so we only remove a leading bracket whose contents parse as a date.
+ */
+function stripLeadingTimestamp(line: string): string {
+  const match = line.match(/^\[([^\]]+)\]\s*([\s\S]*)$/);
+  if (!match) {
+    return line;
+  }
+  const inner = match[1] ?? '';
+  const isTimestamp = !Number.isNaN(new Date(inner).getTime());
+  return isTimestamp ? (match[2] ?? line) : line;
+}

package/dist/bundling-sources/shared_libs/play-runtime/play-node-scope.ts

@@ -0,0 +1,160 @@
+/**
+ * Play Node Scope — the explicit execution location stamped onto every provider
+ * tool call so usage/cost facts can be attributed back to a graph node.
+ *
+ * See ADR 0018 (Observed Provider Attribution). Before this module the only
+ * durable link between a provider call and a play graph node was a stdout regex
+ * (`Calling tool: <id>`), which collapsed N calls into one node transition and
+ * could not distinguish two nodes using the same tool. The scope below travels
+ * with the outbound `/api/v2/integrations/<tool>/execute` request and lands on
+ * `usageEvents.stepBlockId`, which already exists and is already written.
+ *
+ * The scope is deliberately made of facts the runtime *knows* at the call site:
+ * the tool id, the `ctx.tools.execute` id, and — for row-scoped calls — the
+ * runtime sheet column and artifact table namespace. It never guesses a graph
+ * node id; node resolution is a read-time join against the static pipeline and
+ * degrades to an explicit `unattributed` bucket instead of a wrong node.
+ */
+
+/** Execution location of a single logical `ctx.tools.execute` invocation. */
+export type PlayNodeScope = {
+  /** Provider tool id (`dropleads_search_people`). Always present. */
+  toolId: string;
+  /** The author-supplied `ctx.tools.execute(<id>, ...)` key, when known. */
+  callKey: string | null;
+  /** Runtime Sheet column the call fed, for row-scoped calls. */
+  column: string | null;
+  /** Artifact table namespace of the enclosing map, for row-scoped calls. */
+  tableNamespace: string | null;
+};
+
+/** Wire form of {@link PlayNodeScope} on the tool-execute request metadata. */
+export type PlayNodeScopeWire = {
+  tool_id: string;
+  call_key?: string;
+  column?: string;
+  table_namespace?: string;
+};
+
+export const PLAY_NODE_SCOPE_ENCODING_VERSION = 'pn1';
+
+/**
+ * Node id used when a usage fact carries no resolvable scope. Old events
+ * written before this contract, and calls the read path cannot place on the
+ * graph, aggregate here rather than being dropped or guessed onto a node.
+ */
+export const UNATTRIBUTED_PLAY_NODE_ID = 'unattributed';
+
+/** Per-component cap. Keeps the encoded key comfortably under Convex limits. */
+const MAX_COMPONENT_LENGTH = 128;
+
+function normalizeComponent(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  return trimmed.length > MAX_COMPONENT_LENGTH
+    ? trimmed.slice(0, MAX_COMPONENT_LENGTH)
+    : trimmed;
+}
+
+/**
+ * Build a scope from raw call-site facts. Returns null when there is no tool
+ * id, because a scope without a tool identity cannot be joined to anything.
+ */
+export function buildPlayNodeScope(input: {
+  toolId: unknown;
+  callKey?: unknown;
+  column?: unknown;
+  tableNamespace?: unknown;
+}): PlayNodeScope | null {
+  const toolId = normalizeComponent(input.toolId);
+  if (!toolId) return null;
+  return {
+    toolId,
+    callKey: normalizeComponent(input.callKey),
+    column: normalizeComponent(input.column),
+    tableNamespace: normalizeComponent(input.tableNamespace),
+  };
+}
+
+export function playNodeScopeToWire(scope: PlayNodeScope): PlayNodeScopeWire {
+  return {
+    tool_id: scope.toolId,
+    ...(scope.callKey ? { call_key: scope.callKey } : {}),
+    ...(scope.column ? { column: scope.column } : {}),
+    ...(scope.tableNamespace ? { table_namespace: scope.tableNamespace } : {}),
+  };
+}
+
+export function playNodeScopeFromWire(value: unknown): PlayNodeScope | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const wire = value as Record<string, unknown>;
+  return buildPlayNodeScope({
+    toolId: wire.tool_id ?? wire.toolId,
+    callKey: wire.call_key ?? wire.callKey,
+    column: wire.column,
+    tableNamespace: wire.table_namespace ?? wire.tableNamespace,
+  });
+}
+
+function encodeComponent(value: string): string {
+  return encodeURIComponent(value);
+}
+
+/**
+ * Durable key form written to `usageEvents.stepBlockId`.
+ *
+ * `pn1|tool=<t>|call=<c>|col=<f>|ns=<n>` with percent-encoded components and
+ * empty components omitted. Stable and parseable in both directions so a read
+ * path never has to pattern-match free text.
+ */
+export function encodePlayNodeScope(scope: PlayNodeScope): string {
+  const parts = [
+    `${PLAY_NODE_SCOPE_ENCODING_VERSION}`,
+    `tool=${encodeComponent(scope.toolId)}`,
+  ];
+  if (scope.callKey) parts.push(`call=${encodeComponent(scope.callKey)}`);
+  if (scope.column) parts.push(`col=${encodeComponent(scope.column)}`);
+  if (scope.tableNamespace) {
+    parts.push(`ns=${encodeComponent(scope.tableNamespace)}`);
+  }
+  return parts.join('|');
+}
+
+/**
+ * Parse a `stepBlockId` back into a scope. Returns null for legacy workflow
+ * block ids and for anything that is not this encoding — callers must treat
+ * null as "unattributed", never as an error.
+ */
+export function decodePlayNodeScope(value: unknown): PlayNodeScope | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!trimmed.startsWith(`${PLAY_NODE_SCOPE_ENCODING_VERSION}|`)) return null;
+  const fields: Record<string, string> = {};
+  for (const part of trimmed.split('|').slice(1)) {
+    const separator = part.indexOf('=');
+    if (separator <= 0) continue;
+    const key = part.slice(0, separator);
+    try {
+      fields[key] = decodeURIComponent(part.slice(separator + 1));
+    } catch {
+      // A malformed component must not poison the whole rollup.
+      return null;
+    }
+  }
+  return buildPlayNodeScope({
+    toolId: fields.tool,
+    callKey: fields.call,
+    column: fields.col,
+    tableNamespace: fields.ns,
+  });
+}
+
+/** Short human label stored beside the key in `usageEvents.stepAlias`. */
+export function playNodeScopeAlias(scope: PlayNodeScope): string {
+  if (scope.column && scope.tableNamespace) {
+    return `${scope.tableNamespace}.${scope.column}`;
+  }
+  if (scope.column) return scope.column;
+  return scope.callKey ?? scope.toolId;
+}

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

@@ -123,6 +123,12 @@ export interface PlayRunnerContextConfig {
   runtimeTestFaultHeader?: string | null;
   vercelProtectionBypassToken?: string | null;
   integrationMode?: 'live' | 'eval_stub' | 'fixture';
+  /**
+   * Docflow rollout answer for this run, stamped at admission onto the signed
+   * runtime authority and relayed here. Absent means OFF, so a runner reading a
+   * launch queued before the field existed captures nothing extra.
+   */
+  docflowEnabled?: boolean;
   /** Validated internal fixture-only provider response simulation. */
   fixtureBehavior?: FixtureBehavior | null;
   /** Preview/dev test seam that applies provider pacing to fixture responses. */

package/dist/bundling-sources/shared_libs/play-runtime/run-failure.ts

@@ -13,6 +13,7 @@ const RUNTIME_RUNNER_LOST_RE = /\bRUNTIME_RUNNER_LOST\b/i;
 const RUNTIME_SANDBOX_INSPECTION_UNAVAILABLE_RE =
   /\bRUNTIME_SANDBOX_INSPECTION_UNAVAILABLE\b/i;
 const RUNTIME_SANDBOX_LOST_RE = /\bRUNTIME_SANDBOX_LOST\b/i;
+const RUNTIME_SANDBOX_START_FAILED_RE = /\bRUNTIME_SANDBOX_START_FAILED\b/i;
 const RUNTIME_SANDBOX_OOM_RE =
   /\bRUNTIME_SANDBOX_OOM\b|(?:javascript heap out of memory|fatal error:.*(?:heap|allocation).*memory)/i;
 const RUNTIME_SANDBOX_KILLED_RE = /\bRUNTIME_SANDBOX_KILLED\b/i;
@@ -39,6 +40,11 @@ export const RUNTIME_RUNNER_LOST_MESSAGE =
   'The execution runner stopped reporting liveness before returning a terminal result. Completed work is preserved, but Deepline did not automatically replay the run because provider side effects may already exist. Re-run only when it is safe to do so.';
 export const RUNTIME_SANDBOX_INSPECTION_UNAVAILABLE_MESSAGE =
   'The play stopped after Deepline could not verify the execution sandbox state. Completed row state was preserved. Re-run from the persisted rows; if this keeps happening, contact Deepline support with the run ID.';
+// The sandbox was accepted but the runner never reported liveness, so the play
+// body never began. Safe to retry without the side-effect caveat RUNNER_LOST
+// carries: nothing ran, so no provider call can already exist.
+export const RUNTIME_SANDBOX_START_FAILED_MESSAGE =
+  'The execution sandbox never finished starting, so this play never began running. Re-run the same command; if this keeps happening, contact Deepline support with the run ID.';
 
 export const WORKSPACE_STORAGE_NOT_READY_CODE = 'WORKSPACE_STORAGE_NOT_READY';
 
@@ -332,6 +338,27 @@ export function normalizePlayRunFailure(error: unknown): PlayRunFailureDetails {
       ...(causes.length > 0 ? { causes } : {}),
     };
   }
+  // Before the generic fallthrough could claim it. Without this branch the
+  // whole minted string — sandbox and command UUIDs, `runner_heartbeat_not_observed`,
+  // the embedded `schedulerReadinessResponses` JSON, `exit_code_file_unavailable`
+  // — became the run's public `message` verbatim, and every surface that prints
+  // a failure printed the scheduler talking to itself. The detail is not
+  // swallowed: it stays on `cause`, which is what the run's logs and the CLI's
+  // `errors[]` carry.
+  if (RUNTIME_SANDBOX_START_FAILED_RE.test(rawCause)) {
+    const stack = error instanceof Error ? boundedFailureStack(error) : null;
+    const causes = error instanceof Error ? failureCauseTexts(error) : [];
+    return {
+      code: 'RUNTIME_SANDBOX_START_FAILED',
+      phase: 'infrastructure',
+      message: RUNTIME_SANDBOX_START_FAILED_MESSAGE,
+      retryable: true,
+      cause,
+      ...(error instanceof Error ? { name: error.name || 'Error' } : {}),
+      ...(stack ? { stack } : {}),
+      ...(causes.length > 0 ? { causes } : {}),
+    };
+  }
   if (RUNTIME_SANDBOX_INSPECTION_UNAVAILABLE_RE.test(rawCause)) {
     return {
       code: 'RUNTIME_SANDBOX_INSPECTION_UNAVAILABLE',

package/dist/bundling-sources/shared_libs/play-runtime/run-ledger.ts

@@ -7,10 +7,19 @@ import {
   normalizePlayRunLedgerTerminalSource,
 } from './run-terminal-source';
 import { MAX_LEDGER_LOG_LINES_PER_EVENT } from './ledger-safe-payload';
+import {
+  normalizePlayDocflowNodeIoState,
+  type PlayDocflowNodeIoState,
+} from './docflow-node-io';
 import {
   isPlayActivityObservation,
   type PlayActivityObservation,
 } from './activity-observation';
+import {
+  mergeDatasetBornFrom,
+  normalizeDatasetBornFrom,
+  type PlayDatasetBornFrom,
+} from './cell-provenance';
 
 export type PlayRunLedgerStatus =
   | 'queued'
@@ -73,6 +82,7 @@ export type PlayRunLedgerStepProgress = {
   startedAt?: number | null;
   completedAt?: number | null;
   updatedAt?: number | null;
+  nodeIo?: PlayDocflowNodeIoState;
 };
 
 export type PlayRunLedgerStepSnapshot = {
@@ -97,6 +107,12 @@ export type PlayRunLedgerDatasetSnapshot = {
   succeededRows: number;
   failedRows: number;
   complete: boolean;
+  /**
+   * Dataset-grain row birth (ADR 0019). Absent on datasets registered before
+   * the contract and on any registration that did not state one — never
+   * back-filled from row counts, which would assert a lineage nobody observed.
+   */
+  bornFrom?: PlayDatasetBornFrom | null;
   updatedAt: number;
 };
 
@@ -265,6 +281,8 @@ export type PlayRunLedgerEvent =
       succeededRows?: number;
       failedRows?: number;
       complete?: boolean;
+      /** Dataset-grain row birth, stated once per dataset (ADR 0019). */
+      bornFrom?: PlayDatasetBornFrom;
     })
   | (PlayRunLedgerBaseEvent & {
       type: 'activity.observed';
@@ -515,6 +533,7 @@ export function normalizePlayRunLedgerSnapshot(
       rawDataset.phase === 'available' || rawDataset.phase === 'failed'
         ? rawDataset.phase
         : 'registered';
+    const datasetBornFrom = normalizeDatasetBornFrom(rawDataset.bornFrom);
     datasetsById[datasetId] = {
       datasetId,
       path: optionalString(rawDataset.path) ?? `datasets.${datasetId}`,
@@ -524,6 +543,10 @@ export function normalizePlayRunLedgerSnapshot(
       succeededRows: Math.max(0, finiteNumber(rawDataset.succeededRows) ?? 0),
       failedRows: Math.max(0, finiteNumber(rawDataset.failedRows) ?? 0),
       complete: rawDataset.complete === true,
+      // ADR 0019 birth survives the snapshot round trip. A partial record is
+      // dropped rather than half-admitted, so a dataset either states where its
+      // rows came from or says nothing.
+      ...(datasetBornFrom ? { bornFrom: datasetBornFrom } : {}),
       updatedAt: finiteNumber(rawDataset.updatedAt) ?? 0,
     };
   }
@@ -766,6 +789,9 @@ function normalizeStepProgress(
     ...(finiteNumber(value.updatedAt) !== null
       ? { updatedAt: finiteNumber(value.updatedAt) }
       : {}),
+    ...(normalizePlayDocflowNodeIoState(value.nodeIo)
+      ? { nodeIo: normalizePlayDocflowNodeIoState(value.nodeIo) }
+      : {}),
   };
 }
 
@@ -1443,6 +1469,10 @@ export function reducePlayRunLedgerEvent(
     }
     case 'dataset.lifecycle': {
       const current = base.datasetsById[event.datasetId];
+      const mergedBornFrom = mergeDatasetBornFrom(
+        current?.bornFrom,
+        event.bornFrom,
+      );
       const next: PlayRunLedgerDatasetSnapshot = {
         datasetId: event.datasetId,
         path: event.path,
@@ -1458,6 +1488,10 @@ export function reducePlayRunLedgerEvent(
         ),
         failedRows: Math.max(current?.failedRows ?? 0, event.failedRows ?? 0),
         complete: current?.complete === true || event.complete === true,
+        // Birth is stated at registration. A later phase event carries no birth
+        // record and must not erase the one that was witnessed; a paged
+        // dataset re-registers with a larger admitted-row count.
+        ...(mergedBornFrom ? { bornFrom: mergedBornFrom } : {}),
         updatedAt: occurredAt,
       };
       return withTiming({
@@ -1516,6 +1550,7 @@ function progressSignature(
     artifactTableNamespace: progress?.artifactTableNamespace ?? null,
     startedAt: progress?.startedAt ?? null,
     completedAt: progress?.completedAt ?? null,
+    nodeIo: progress?.nodeIo ?? null,
   });
 }
 
@@ -1777,6 +1812,7 @@ export function buildPlayRunLedgerEventsFromStatusPatch(input: {
       ...(progress.completedAt !== undefined
         ? { completedAt: progress.completedAt }
         : {}),
+      ...(progress.nodeIo !== undefined ? { nodeIo: progress.nodeIo } : {}),
       updatedAt: progress.updatedAt ?? checkpointAt,
     };
     if (
@@ -1790,11 +1826,13 @@ export function buildPlayRunLedgerEventsFromStatusPatch(input: {
         occurredAt: progress.updatedAt ?? checkpointAt,
         stepId,
         status:
-          typeof progress.completedAt === 'number'
-            ? 'completed'
-            : previousStep?.status === 'failed'
-              ? 'failed'
-              : 'running',
+          typeof progress.nodeIo?.error === 'string'
+            ? 'failed'
+            : typeof progress.completedAt === 'number'
+              ? 'completed'
+              : previousStep?.status === 'failed'
+                ? 'failed'
+                : 'running',
         progress: normalizedProgress,
       });
     }