deepline 0.3.257 → 0.3.259

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

@@ -0,0 +1,845 @@
+import {
+  decodePlayRunPublicStatus,
+  type PlayRunPublicStatus,
+} from './run-lifecycle-policy';
+import { docflowUnreachedVerdict } from '../plays/docflow-unreached-reason';
+
+/**
+ * Run Execution State: the ONE typed model of what a Play Run and each of its
+ * steps did, and the ONE set of words for it.
+ *
+ * Every surface that says what a run did reads it from here: the run read
+ * path (`GET /api/v2/runs/:id` steps), `deepline runs get`, the dashboard's
+ * canvas pills, run rail and record pane. Before this, each surface derived
+ * the same concept on its own, and they disagreed: a step the run stopped
+ * mid-map said "Failed 1,241 of 50,000 rows" (no row had failed — the run had
+ * stopped), the CLI printed the same step as `running` on a failed run, and
+ * the CLI and the record pane formatted one billing read two ways.
+ *
+ * The rules this module enforces by type:
+ *  - "failed" about rows only ever counts rows that failed. A step the run
+ *    ended while it was in flight is `stopped`, never `failed`.
+ *  - A step is never `running` once its run is terminal.
+ *  - Row counts are run-scoped and monotonic (`mergeRowCounts`), and
+ *    `total`, when known, is never below `completed + failed`.
+ *  - Every switch over a state is exhaustive (`assertNeverState`).
+ *
+ * Pure and dependency-free (bundled into the CLI): no I/O, no clocks.
+ */
+
+/** Exhaustiveness guard: a new state kind is a compile error at every switch. */
+export function assertNeverState(value: never, what: string): never {
+  throw new Error(`Unhandled ${what}: ${JSON.stringify(value)}`);
+}
+
+// ---------------------------------------------------------------------------
+// Row counts
+// ---------------------------------------------------------------------------
+
+/**
+ * Row outcomes of one scope (a step's table, or a whole run). Scope is always
+ * the run: a chunk or a sheet page never feeds these.
+ */
+export type RowCounts = {
+  /** Rows that finished successfully. */
+  readonly completed: number;
+  /** Rows that FAILED — never rows that did not run. */
+  readonly failed: number;
+  /** Rows the scope was handed, when known. Never below completed + failed. */
+  readonly total: number | null;
+};
+
+function count(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.max(0, Math.trunc(value))
+    : null;
+}
+
+/**
+ * Build counts from whatever fields a producer reported. `completed` is the
+ * ledger's successes-only counter (`PlayRunLedgerStepProgress.completed`);
+ * `completedRows` stands in only when `completed` is absent. When a total is
+ * known, failed rows are at most the rows that did not succeed. Null when no
+ * field carries a number.
+ */
+export function rowCountsFrom(
+  input:
+    | {
+        completed?: unknown;
+        completedRows?: unknown;
+        failed?: unknown;
+        total?: unknown;
+      }
+    | null
+    | undefined,
+): RowCounts | null {
+  if (!input) return null;
+  const completed = count(input.completed) ?? count(input.completedRows);
+  const failed = count(input.failed);
+  const total = count(input.total);
+  if (completed === null && failed === null && total === null) return null;
+  const c = completed ?? 0;
+  const known = total !== null && total > 0 ? Math.max(total, c) : null;
+  // A row is counted once. A producer that kept a row's earlier failure after
+  // it later succeeded (max-merged `failed` across attempts) reports more
+  // settled rows than it was handed; the successes are the recount.
+  const f = known === null ? (failed ?? 0) : Math.min(failed ?? 0, known - c);
+  return { completed: c, failed: f, total: known };
+}
+
+/**
+ * Monotonic merge of two reads of the same run-scoped counts: neither
+ * completed nor failed ever goes down, and a later total replaces an earlier
+ * one (the map reconciles its estimate at finalize) but never drops below the
+ * settled rows.
+ */
+export function mergeRowCounts(
+  held: RowCounts | null,
+  incoming: RowCounts | null,
+): RowCounts | null {
+  if (!held) return incoming;
+  if (!incoming) return held;
+  const completed = Math.max(held.completed, incoming.completed);
+  const failed = Math.max(held.failed, incoming.failed);
+  const total = incoming.total ?? held.total;
+  return {
+    completed,
+    failed,
+    total: total === null ? null : Math.max(total, completed + failed),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Run execution state
+// ---------------------------------------------------------------------------
+
+export type RunStopCause = 'run_failed' | 'run_cancelled';
+
+export type RunExecutionState =
+  | { readonly kind: 'queued' }
+  | { readonly kind: 'running' }
+  | { readonly kind: 'waiting'; readonly overdue: boolean }
+  /** Completed; `rows.failed > 0` means some rows failed, each in its row. */
+  | { readonly kind: 'completed'; readonly rows: RowCounts | null }
+  | {
+      readonly kind: 'failed';
+      readonly rows: RowCounts | null;
+      readonly error: string | null;
+    }
+  | { readonly kind: 'cancelled'; readonly rows: RowCounts | null }
+  /** The stored status is unreadable: no claim either way. */
+  | { readonly kind: 'unknown' };
+
+export type RunExecutionKind = RunExecutionState['kind'];
+
+/** Decode any stored/wire run status into the public lifecycle, or null. */
+export function decodeRunStatus(status: unknown): PlayRunPublicStatus | null {
+  return decodePlayRunPublicStatus(status);
+}
+
+export function isTerminalRunExecution(state: RunExecutionState): boolean {
+  switch (state.kind) {
+    case 'completed':
+    case 'failed':
+    case 'cancelled':
+      return true;
+    case 'queued':
+    case 'running':
+    case 'waiting':
+    case 'unknown':
+      return false;
+    default:
+      return assertNeverState(state, 'run execution state');
+  }
+}
+
+export function deriveRunExecutionState(input: {
+  status: unknown;
+  /** Terminal row outcomes, when the run reports them. */
+  rows?: RowCounts | null;
+  error?: string | null;
+  /** A waiting run's deadline, and the clock it is judged against. */
+  waitDeadlineAt?: number | null;
+  now?: number;
+}): RunExecutionState {
+  const status = decodeRunStatus(input.status);
+  const rows = input.rows ?? null;
+  switch (status) {
+    case 'queued':
+      return { kind: 'queued' };
+    case 'running':
+      return { kind: 'running' };
+    case 'waiting':
+      return {
+        kind: 'waiting',
+        overdue:
+          typeof input.waitDeadlineAt === 'number' &&
+          typeof input.now === 'number' &&
+          input.waitDeadlineAt < input.now,
+      };
+    case 'completed':
+      return { kind: 'completed', rows };
+    case 'failed':
+      return {
+        kind: 'failed',
+        rows,
+        error: input.error?.trim() ? input.error.trim() : null,
+      };
+    case 'cancelled':
+      return { kind: 'cancelled', rows };
+    case null:
+      return { kind: 'unknown' };
+    default:
+      return assertNeverState(status, 'run status');
+  }
+}
+
+export type RunExecutionLabel = {
+  /** The glyph/pill vocabulary every run surface shares. */
+  readonly tone:
+    | 'queued'
+    | 'running'
+    | 'waiting'
+    | 'waiting_overdue'
+    | 'completed'
+    | 'partial'
+    | 'failed'
+    | 'cancelled'
+    | 'unknown';
+  /** "Completed", "Completed, some rows failed", "Failed", ... */
+  readonly word: string;
+};
+
+export function runExecutionLabel(state: RunExecutionState): RunExecutionLabel {
+  switch (state.kind) {
+    case 'queued':
+      return { tone: 'queued', word: 'Queued' };
+    case 'running':
+      return { tone: 'running', word: 'Running' };
+    case 'waiting':
+      return state.overdue
+        ? { tone: 'waiting_overdue', word: 'Waiting past its deadline' }
+        : { tone: 'waiting', word: 'Waiting' };
+    case 'completed':
+      return (state.rows?.failed ?? 0) > 0
+        ? { tone: 'partial', word: 'Completed, some rows failed' }
+        : { tone: 'completed', word: 'Completed' };
+    case 'failed':
+      return { tone: 'failed', word: 'Failed' };
+    case 'cancelled':
+      return { tone: 'cancelled', word: 'Cancelled' };
+    case 'unknown':
+      return { tone: 'unknown', word: 'Unknown' };
+    default:
+      return assertNeverState(state, 'run execution state');
+  }
+}
+
+/** The same words keyed by tone, for surfaces that hold only a tone. */
+export const RUN_EXECUTION_TONE_WORD: Record<
+  RunExecutionLabel['tone'],
+  string
+> = {
+  queued: 'Queued',
+  running: 'Running',
+  waiting: 'Waiting',
+  waiting_overdue: 'Waiting past its deadline',
+  completed: 'Completed',
+  partial: 'Completed, some rows failed',
+  failed: 'Failed',
+  cancelled: 'Cancelled',
+  unknown: 'Unknown',
+};
+
+// ---------------------------------------------------------------------------
+// Node (step) execution state
+// ---------------------------------------------------------------------------
+
+/** The node statuses the Run Snapshot reports (`PlayRunStreamNodeState`). */
+export type ReportedNodeStatus =
+  | 'idle'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'skipped';
+
+export type NodeExecutionState =
+  /** The run is live and has not reached this step. */
+  | { readonly kind: 'queued' }
+  | {
+      readonly kind: 'running';
+      readonly rows: RowCounts | null;
+      readonly startedAt: number | null;
+    }
+  /** Finished. `rows.failed > 0`: some rows failed, each isolated to its row. */
+  | { readonly kind: 'completed'; readonly rows: RowCounts | null }
+  /** The step itself failed (it carries its own error). */
+  | {
+      readonly kind: 'failed';
+      readonly rows: RowCounts | null;
+      readonly error: string | null;
+    }
+  /**
+   * The run ended while this step was in flight. Its rows did not fail; the
+   * ones short of `total` never ran.
+   */
+  | {
+      readonly kind: 'stopped';
+      readonly rows: RowCounts | null;
+      readonly cause: RunStopCause;
+    }
+  /** The runtime decided this step does not run. */
+  | { readonly kind: 'skipped' }
+  /** The run ended with this step reported idle: it never started. */
+  | {
+      readonly kind: 'not_reached';
+      readonly cause: RunStopCause | 'run_completed';
+    }
+  /**
+   * No claim either way: the run reported no state for this node and it is
+   * not live, or its status is unreadable.
+   */
+  | { readonly kind: 'unknown' };
+
+export type NodeExecutionKind = NodeExecutionState['kind'];
+
+/** What a node reported, as the Run Snapshot / step package carries it. */
+export type ReportedNodeExecution = {
+  status: ReportedNodeStatus | string;
+  error?: string | null;
+  /** Set by the ledger when the run's terminal event settled the step. */
+  stoppedBy?: RunStopCause | null;
+  startedAt?: number | null;
+  progress?: {
+    completed?: unknown;
+    completedRows?: unknown;
+    failed?: unknown;
+    total?: unknown;
+  } | null;
+};
+
+function stopCauseForRun(run: PlayRunPublicStatus | null): RunStopCause | null {
+  if (run === 'failed') return 'run_failed';
+  if (run === 'cancelled') return 'run_cancelled';
+  return null;
+}
+
+/**
+ * The one derivation of a step's state from what it reported and its run's
+ * status. `rows` overrides the reported progress when the caller holds a more
+ * specific run-scoped count for this step (a loop member's own column).
+ */
+export function deriveNodeExecutionState(input: {
+  reported: ReportedNodeExecution | null | undefined;
+  runStatus: unknown;
+  rows?: RowCounts | null;
+}): NodeExecutionState {
+  const run = decodeRunStatus(input.runStatus);
+  const runTerminal =
+    run === 'completed' || run === 'failed' || run === 'cancelled';
+  const reported = input.reported ?? null;
+  const rows =
+    input.rows !== undefined
+      ? input.rows
+      : rowCountsFrom(reported?.progress ?? null);
+  const status = reported?.status ?? 'idle';
+  const runStop = stopCauseForRun(run);
+
+  switch (status) {
+    case 'running': {
+      if (!runTerminal) {
+        return {
+          kind: 'running',
+          rows,
+          startedAt:
+            typeof reported?.startedAt === 'number' ? reported.startedAt : null,
+        };
+      }
+      // The run ended under a step still reporting running. A completed run
+      // finished it (the ledger heals a missing final bump the same way).
+      return runStop
+        ? { kind: 'stopped', rows, cause: runStop }
+        : { kind: 'completed', rows };
+    }
+    case 'completed':
+      return { kind: 'completed', rows };
+    case 'skipped':
+      return { kind: 'skipped' };
+    case 'failed': {
+      if (reported?.stoppedBy) {
+        return { kind: 'stopped', rows, cause: reported.stoppedBy };
+      }
+      // A stop interrupts the step it lands on; the runtime records that step
+      // `failed`. It did not fail — the run was cancelled.
+      if (run === 'cancelled') {
+        return { kind: 'stopped', rows, cause: 'run_cancelled' };
+      }
+      // `stoppedBy` is projected once, by the Run Snapshot
+      // (run-snapshot-stream.ts `stepStopCause`), including for snapshots
+      // written before the ledger recorded it. Without it the step failed.
+      return {
+        kind: 'failed',
+        rows,
+        error: reported?.error?.trim() ? reported.error.trim() : null,
+      };
+    }
+    default: {
+      // idle / absent / unreadable.
+      if (run === 'queued' || run === 'running' || run === 'waiting') {
+        return { kind: 'queued' };
+      }
+      // Only a node the run REPORTED idle is known not to have run. A node
+      // the run reported nothing for says nothing either way.
+      if (runTerminal && status === 'idle' && reported) {
+        return { kind: 'not_reached', cause: runStop ?? 'run_completed' };
+      }
+      return { kind: 'unknown' };
+    }
+  }
+}
+
+/** Where a node state sits in its lifecycle; a node never steps back. */
+export function nodeExecutionRank(state: NodeExecutionState): number {
+  switch (state.kind) {
+    case 'unknown':
+      return 0;
+    case 'queued':
+      return 1;
+    case 'running':
+      return 2;
+    case 'completed':
+    case 'failed':
+    case 'stopped':
+    case 'skipped':
+    case 'not_reached':
+      return 3;
+    default:
+      return assertNeverState(state, 'node execution state');
+  }
+}
+
+function stateRows(state: NodeExecutionState): RowCounts | null {
+  switch (state.kind) {
+    case 'running':
+    case 'completed':
+    case 'failed':
+    case 'stopped':
+      return state.rows;
+    case 'queued':
+    case 'skipped':
+    case 'not_reached':
+    case 'unknown':
+      return null;
+    default:
+      return assertNeverState(state, 'node execution state');
+  }
+}
+
+/**
+ * Monotonic merge of two reads of one node within one run: the state never
+ * steps back a rank, and its row counts never decrease.
+ */
+export function mergeNodeExecutionState(
+  held: NodeExecutionState | null | undefined,
+  incoming: NodeExecutionState,
+): NodeExecutionState {
+  if (!held) return incoming;
+  const winner =
+    nodeExecutionRank(incoming) >= nodeExecutionRank(held) ? incoming : held;
+  const rows = mergeRowCounts(stateRows(held), stateRows(incoming));
+  switch (winner.kind) {
+    case 'running':
+    case 'completed':
+    case 'failed':
+    case 'stopped':
+      return rows === winner.rows ? winner : { ...winner, rows };
+    case 'queued':
+    case 'skipped':
+    case 'not_reached':
+    case 'unknown':
+      return winner;
+    default:
+      return assertNeverState(winner, 'node execution state');
+  }
+}
+
+/** The pill vocabulary every step surface shares (UI badge variant, CLI word). */
+export type NodeExecutionTone =
+  | 'queued'
+  | 'running'
+  | 'completed'
+  /** Completed, some rows failed. */
+  | 'partial'
+  | 'failed'
+  | 'stopped'
+  | 'cancelled'
+  | 'skipped'
+  | 'unknown';
+
+export type NodeExecutionLabel = {
+  readonly tone: NodeExecutionTone;
+  /** "Running", "Completed", "Failed", "Stopped", "Cancelled", ... */
+  readonly word: string;
+  /** "1,241/50,000", "50,000 rows", "49,000/50,000 ok", "1,241 of 50,000 done". */
+  readonly count: string | null;
+  /** Rows that failed (> 0 only when rows did). */
+  readonly failedRows: number;
+};
+
+function n(value: number): string {
+  return value.toLocaleString('en-US');
+}
+
+function rowsWord(value: number): string {
+  return `${n(value)} ${value === 1 ? 'row' : 'rows'}`;
+}
+
+/** "{completed}/{total} ok" when rows failed; null otherwise. */
+function okFraction(rows: RowCounts): string | null {
+  if (rows.failed <= 0) return null;
+  return `${n(rows.completed)}/${n(rows.total ?? rows.completed + rows.failed)} ok`;
+}
+
+function settledCount(rows: RowCounts | null): string | null {
+  if (!rows) return null;
+  const all = rows.total ?? rows.completed + rows.failed;
+  return all > 0 ? rowsWord(all) : null;
+}
+
+/** A step that ended short of its total says how far it got. */
+function partialCount(rows: RowCounts | null): string | null {
+  if (!rows) return null;
+  const ok = okFraction(rows);
+  if (ok) return ok;
+  if (rows.total !== null && rows.completed < rows.total) {
+    return `${n(rows.completed)} of ${n(rows.total)} done`;
+  }
+  return settledCount(rows);
+}
+
+export function nodeExecutionLabel(
+  state: NodeExecutionState,
+): NodeExecutionLabel {
+  const failedRows = stateRows(state)?.failed ?? 0;
+  switch (state.kind) {
+    case 'queued':
+      return { tone: 'queued', word: 'Queued', count: null, failedRows };
+    case 'running': {
+      const rows = state.rows;
+      // Progress counts every settled row; the failed ones are named after.
+      const settled = rows ? rows.completed + rows.failed : 0;
+      const live = rows
+        ? rows.total !== null
+          ? `${n(settled)}/${n(rows.total)}`
+          : settled > 0
+            ? rowsWord(settled)
+            : null
+        : null;
+      return { tone: 'running', word: 'Running', count: live, failedRows };
+    }
+    case 'completed':
+      return state.rows && state.rows.failed > 0
+        ? {
+            tone: 'partial',
+            word: 'Completed',
+            count: okFraction(state.rows),
+            failedRows,
+          }
+        : {
+            tone: 'completed',
+            word: 'Completed',
+            count: settledCount(state.rows),
+            failedRows,
+          };
+    case 'failed':
+      return {
+        tone: 'failed',
+        word: 'Failed',
+        count: partialCount(state.rows),
+        failedRows,
+      };
+    case 'stopped':
+      return state.cause === 'run_cancelled'
+        ? {
+            tone: 'cancelled',
+            word: 'Cancelled',
+            count: partialCount(state.rows),
+            failedRows,
+          }
+        : {
+            tone: 'stopped',
+            word: 'Stopped',
+            count: partialCount(state.rows),
+            failedRows,
+          };
+    case 'skipped':
+      return { tone: 'skipped', word: 'Skipped', count: null, failedRows };
+    case 'not_reached':
+      return { tone: 'skipped', word: 'Not reached', count: null, failedRows };
+    case 'unknown':
+      return { tone: 'unknown', word: 'Unknown', count: null, failedRows };
+    default:
+      return assertNeverState(state, 'node execution state');
+  }
+}
+
+/**
+ * The label as one line of text — `deepline runs get`'s step line, and what
+ * the dashboard pill reads aloud. "Stopped · 1,241 of 50,000 done",
+ * "Completed · 49,000/50,000 ok · 1,000 rows failed", "Running · 4/10 · 1 row
+ * failed".
+ */
+export function formatNodeExecutionLabel(label: NodeExecutionLabel): string {
+  const facts = formatNodeExecutionFacts(label);
+  return facts ? `${label.word} · ${facts}` : label.word;
+}
+
+/** The label's facts without its word: "1,241 of 50,000 done · 2 rows failed". */
+export function formatNodeExecutionFacts(label: NodeExecutionLabel): string {
+  return [
+    label.count,
+    label.failedRows > 0 ? `${rowsWord(label.failedRows)} failed` : null,
+  ]
+    .filter((part): part is string => Boolean(part))
+    .join(' · ');
+}
+
+export function formatNodeExecutionState(state: NodeExecutionState): string {
+  return formatNodeExecutionLabel(nodeExecutionLabel(state));
+}
+
+// ---------------------------------------------------------------------------
+// Run cost
+// ---------------------------------------------------------------------------
+
+/**
+ * A run's credits as every surface states them, from ONE source: the run
+ * billing read (`GET /api/v2/runs/billing`, Convex `runBillingSettlement`)
+ * plus whether the run is still live.
+ */
+export type RunCostState =
+  /** The billing read failed: say so, never a number. */
+  | { readonly kind: 'unavailable'; readonly reason: string }
+  /** Nothing billed, and nothing can still bill. */
+  | { readonly kind: 'none' }
+  /** Nothing posted yet, but a charge reservation is still open. */
+  | { readonly kind: 'pending' }
+  /** Credits posted so far; the total may still change. */
+  | { readonly kind: 'settling'; readonly credits: number }
+  /** The final total. */
+  | { readonly kind: 'settled'; readonly credits: number };
+
+export function deriveRunCostState(input: {
+  /** Posted credits from the billing read; `undefined` when none recorded. */
+  credits: number | null | undefined;
+  /**
+   * Unsettled charge reservations from the billing read: `true`/`false`, or
+   * `null` when the read could not say (then a shown amount is not final).
+   */
+  settling: boolean | null;
+  /** The run is still live, so its total is a running total. */
+  live: boolean;
+}): RunCostState {
+  const credits =
+    typeof input.credits === 'number' &&
+    Number.isFinite(input.credits) &&
+    input.credits > 0
+      ? input.credits
+      : null;
+  const mayChange = input.live || input.settling !== false;
+  if (credits === null) {
+    // Only an unsettled reservation says a charge is coming. A live run that
+    // has billed nothing and holds none has, so far, cost nothing.
+    return input.settling === true ? { kind: 'pending' } : { kind: 'none' };
+  }
+  return mayChange
+    ? { kind: 'settling', credits }
+    : { kind: 'settled', credits };
+}
+
+/** "0.06", "<0.01", "12", "1.2k" — one amount format for every surface. */
+export function formatCreditAmount(credits: number): string {
+  if (credits < 0.01) return '<0.01';
+  if (credits >= 1000) {
+    return `${(credits / 1000).toLocaleString('en-US', { maximumFractionDigits: 1 })}k`;
+  }
+  return credits.toLocaleString('en-US', {
+    minimumFractionDigits: credits < 10 ? 2 : 0,
+    maximumFractionDigits: credits < 10 ? 2 : 0,
+  });
+}
+
+function creditsWord(credits: number): string {
+  const amount = formatCreditAmount(credits);
+  return `${amount} ${amount === '1.00' ? 'credit' : 'credits'}`;
+}
+
+/**
+ * The cost as one line: `deepline runs get`'s `credits:` line and the run
+ * record's header. "0.06 credits", "0.06 credits · settling", "settling",
+ * "none", "unavailable (…)".
+ */
+export function formatRunCostState(state: RunCostState): string {
+  switch (state.kind) {
+    case 'unavailable':
+      return `unavailable (${state.reason})`;
+    case 'none':
+      return 'none';
+    case 'pending':
+      return 'settling';
+    case 'settling':
+      return `${creditsWord(state.credits)} · settling`;
+    case 'settled':
+      return creditsWord(state.credits);
+    default:
+      return assertNeverState(state, 'run cost state');
+  }
+}
+
+/**
+ * The same line without the unit, for a surface that draws the credit mark
+ * beside it (the run record's header): "0.06", "0.06 · settling", "settling".
+ */
+export function formatRunCostAmount(state: RunCostState): string {
+  switch (state.kind) {
+    case 'unavailable':
+    case 'none':
+    case 'pending':
+      return formatRunCostState(state);
+    case 'settling':
+      return `${formatCreditAmount(state.credits)} · settling`;
+    case 'settled':
+      return formatCreditAmount(state.credits);
+    default:
+      return assertNeverState(state, 'run cost state');
+  }
+}
+
+/** The runs gutter's few characters: "0.06", "0.06…", "…", "" for none. */
+export function formatRunCostCompact(state: RunCostState): string {
+  switch (state.kind) {
+    case 'unavailable':
+    case 'none':
+      return '';
+    case 'pending':
+      return '…';
+    case 'settling':
+      return `${formatCreditAmount(state.credits)}…`;
+    case 'settled':
+      return formatCreditAmount(state.credits);
+    default:
+      return assertNeverState(state, 'run cost state');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Wire decoding
+// ---------------------------------------------------------------------------
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function decodeRows(value: unknown): RowCounts | null | undefined {
+  if (value === null) return null;
+  if (!isObject(value)) return undefined;
+  const rows = rowCountsFrom({
+    completed: value.completed,
+    failed: value.failed,
+    total: value.total,
+  });
+  return rows ?? undefined;
+}
+
+function decodeStopCause(value: unknown): RunStopCause | null {
+  return value === 'run_failed' || value === 'run_cancelled' ? value : null;
+}
+
+/**
+ * Decode a step's `execution` from a run read (`steps[].execution`). Null for
+ * anything that is not a well-formed state — an older server sends none, and
+ * the caller then derives one from the step's reported fields.
+ */
+export function decodeNodeExecutionState(
+  value: unknown,
+): NodeExecutionState | null {
+  if (!isObject(value)) return null;
+  const rows = decodeRows(value.rows);
+  switch (value.kind) {
+    case 'queued':
+    case 'skipped':
+    case 'unknown':
+      return { kind: value.kind };
+    case 'running':
+      return rows === undefined
+        ? null
+        : {
+            kind: 'running',
+            rows,
+            startedAt:
+              typeof value.startedAt === 'number' ? value.startedAt : null,
+          };
+    case 'completed':
+      return rows === undefined ? null : { kind: 'completed', rows };
+    case 'failed':
+      return rows === undefined
+        ? null
+        : {
+            kind: 'failed',
+            rows,
+            error: typeof value.error === 'string' ? value.error : null,
+          };
+    case 'stopped': {
+      const cause = decodeStopCause(value.cause);
+      return rows === undefined || !cause
+        ? null
+        : { kind: 'stopped', rows, cause };
+    }
+    case 'not_reached': {
+      const cause =
+        value.cause === 'run_completed'
+          ? 'run_completed'
+          : decodeStopCause(value.cause);
+      return cause ? { kind: 'not_reached', cause } : null;
+    }
+    default:
+      return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// A step the run carries no state for
+// ---------------------------------------------------------------------------
+
+/**
+ * What a step the run reported NO state for is, from the graph walk that says
+ * why (`deriveDocflowUnreachedReason`) and the one rule that turns it into a
+ * verdict (`docflowUnreachedVerdict`, both in
+ * ../plays/docflow-unreached-reason). The canvas pill and `deepline
+ * runs get` give the same answer. `null` makes no claim.
+ */
+export function nodeExecutionForUnreachedReason(input: {
+  reason: string;
+  runStatus: unknown;
+}): NodeExecutionState | null {
+  const run = decodeRunStatus(input.runStatus);
+  const verdict = docflowUnreachedVerdict({
+    reason: input.reason,
+    runTerminal: run === 'completed' || run === 'failed' || run === 'cancelled',
+  });
+  switch (verdict) {
+    case null:
+      return null;
+    case 'skipped':
+      return { kind: 'skipped' };
+    case 'unknown':
+      return { kind: 'unknown' };
+    case 'not_reached':
+      return {
+        kind: 'not_reached',
+        cause: stopCauseForRun(run) ?? 'run_completed',
+      };
+    default:
+      return assertNeverState(verdict, 'unreached verdict');
+  }
+}