deepline 0.1.90 → 0.1.93

package/dist/repo/shared_libs/play-runtime/run-ledger.ts

@@ -0,0 +1,1074 @@
+export type PlayRunLedgerStatus =
+  | 'queued'
+  | 'running'
+  | 'waiting'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'terminated'
+  | 'timed_out'
+  | 'unknown';
+
+export type PlayRunLedgerStepStatus =
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'skipped';
+
+export type PlayRunLedgerEventSource =
+  | 'worker'
+  | 'temporal'
+  | 'convex'
+  | 'coordinator'
+  | 'system';
+
+export type PlayRunLedgerStepProgress = {
+  completed?: number;
+  total?: number;
+  failed?: number;
+  message?: string;
+  artifactTableNamespace?: string | null;
+  startedAt?: number | null;
+  completedAt?: number | null;
+  updatedAt?: number | null;
+};
+
+export type PlayRunLedgerStepSnapshot = {
+  stepId: string;
+  label?: string;
+  kind?: string;
+  status: PlayRunLedgerStepStatus;
+  artifactTableNamespace?: string | null;
+  startedAt?: number | null;
+  completedAt?: number | null;
+  updatedAt?: number | null;
+  progress?: PlayRunLedgerStepProgress | null;
+};
+
+export type PlayRunLedgerSnapshot = {
+  runId: string;
+  playName?: string | null;
+  status: PlayRunLedgerStatus;
+  error?: string | null;
+  createdAt?: number | null;
+  startedAt?: number | null;
+  updatedAt?: number | null;
+  finishedAt?: number | null;
+  durationMs?: number | null;
+  orderedStepIds: string[];
+  stepsById: Record<string, PlayRunLedgerStepSnapshot>;
+  /**
+   * Bounded tail of the run's log lines (last {@link LOG_TAIL_LIMIT}).
+   * Full retention lives in the Run Log Stream (Convex `playRunLogChunks`);
+   * the snapshot only carries enough tail for live previews.
+   * `totalLogCount` is the monotonic count of every line ever ingested
+   * (post channel-dedupe), so readers can derive the absolute sequence
+   * number of the first retained tail line:
+   * `totalLogCount - logTail.length + 1`.
+   */
+  logTail: string[];
+  totalLogCount: number;
+  /**
+   * True once the Run Log Stream stopped storing line bodies because the run
+   * crossed the retention cap (25k lines / 5MB). `totalLogCount` keeps
+   * counting past the cap; a loud truncation marker is the last stored line.
+   */
+  logsTruncated: boolean;
+  activeStepId?: string | null;
+  activeArtifactTableNamespace?: string | null;
+  resultTableNamespace?: string | null;
+  resultSummary?: unknown;
+  result?: unknown;
+};
+
+type PlayRunLedgerBaseEvent = {
+  runId: string;
+  seq?: number;
+  occurredAt: number;
+  source: PlayRunLedgerEventSource;
+};
+
+export type PlayRunLedgerEvent =
+  | (PlayRunLedgerBaseEvent & {
+      type: 'run.created';
+      playName?: string | null;
+      status?: PlayRunLedgerStatus;
+      runtimeBackend?: string | null;
+    })
+  | (PlayRunLedgerBaseEvent & {
+      type: 'run.started';
+      playName?: string | null;
+      runtimeBackend?: string | null;
+    })
+  | (PlayRunLedgerBaseEvent & {
+      type: 'run.completed';
+      result?: unknown;
+      resultSummary?: unknown;
+    })
+  | (PlayRunLedgerBaseEvent & {
+      type: 'run.failed';
+      error?: string | null;
+      result?: unknown;
+    })
+  | (PlayRunLedgerBaseEvent & {
+      type: 'run.cancelled';
+      error?: string | null;
+      result?: unknown;
+    })
+  | (PlayRunLedgerBaseEvent & {
+      type: 'step.started';
+      stepId: string;
+      label?: string;
+      kind?: string;
+      artifactTableNamespace?: string | null;
+    })
+  | (PlayRunLedgerBaseEvent & {
+      type: 'step.progress';
+      stepId: string;
+      label?: string;
+      kind?: string;
+      status?: PlayRunLedgerStepStatus;
+      progress: PlayRunLedgerStepProgress;
+    })
+  | (PlayRunLedgerBaseEvent & {
+      type: 'step.completed';
+      stepId: string;
+      label?: string;
+      kind?: string;
+      artifactTableNamespace?: string | null;
+    })
+  | (PlayRunLedgerBaseEvent & {
+      type: 'step.failed';
+      stepId: string;
+      label?: string;
+      kind?: string;
+      error?: string | null;
+      artifactTableNamespace?: string | null;
+    })
+  | (PlayRunLedgerBaseEvent & {
+      type: 'step.skipped';
+      stepId: string;
+      label?: string;
+      kind?: string;
+      artifactTableNamespace?: string | null;
+    })
+  | (PlayRunLedgerBaseEvent & {
+      type: 'log.appended';
+      lines: string[];
+      /**
+       * Absolute per-run sequence (1-based) of `lines[0]`. Assigned by Run
+       * Log Stream ingestion in Convex only; producers never set it.
+       */
+      firstSeq?: number;
+      /**
+       * Positional cursor for exactly-once delivery on the worker channel:
+       * the count of lines this producer emitted before `lines[0]`. Ingestion
+       * skips the already-ingested prefix positionally, which preserves
+       * repeated identical lines while absorbing redundant re-sends.
+       */
+      channelOffset?: number;
+      /** Set by ingestion when this append crossed the retention cap. */
+      logsTruncated?: boolean;
+    })
+  | (PlayRunLedgerBaseEvent & {
+      type: 'sheet.summary.updated';
+      tableNamespace: string;
+      deltaCursor?: number;
+      summary?: unknown;
+    });
+
+export type PlayRunLedgerStatusPatch = {
+  runId: string;
+  playName?: string | null;
+  status: string;
+  error?: string | null;
+  runtimeBackend?: string | null;
+  lastCheckpointAt?: number | null;
+  liveLogs?: readonly string[] | null;
+  /**
+   * Positional cursor for `liveLogs[0]` on this producer's log channel (the
+   * count of lines emitted before it). Computed by the producer-side cursor
+   * (see `slicePositionalLogLines`), forwarded onto the `log.appended` event.
+   */
+  liveLogsChannelOffset?: number | null;
+  liveNodeProgress?: unknown;
+  result?: unknown;
+};
+
+export const LOG_TAIL_LIMIT = 100;
+const TERMINAL_STATUSES = new Set<PlayRunLedgerStatus>([
+  'completed',
+  'failed',
+  'cancelled',
+  'terminated',
+  'timed_out',
+]);
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function optionalFiniteNumber(value: unknown): number | undefined {
+  const normalized = finiteNumber(value);
+  return normalized === null ? undefined : normalized;
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function optionalNullableString(value: unknown): string | null | undefined {
+  if (value === null) return null;
+  return optionalString(value);
+}
+
+export function normalizePlayRunLedgerStatus(
+  value: unknown,
+): PlayRunLedgerStatus {
+  const normalized = String(value ?? '')
+    .trim()
+    .toLowerCase();
+  switch (normalized) {
+    case 'queued':
+    case 'pending':
+      return 'queued';
+    case 'running':
+    case 'started':
+      return 'running';
+    case 'waiting':
+      return 'waiting';
+    case 'completed':
+    case 'complete':
+    case 'succeeded':
+      return 'completed';
+    case 'failed':
+    case 'error':
+      return 'failed';
+    case 'cancelled':
+    case 'canceled':
+      return 'cancelled';
+    case 'terminated':
+      return 'terminated';
+    case 'timed_out':
+    case 'timeout':
+      return 'timed_out';
+    default:
+      return 'unknown';
+  }
+}
+
+export function isTerminalPlayRunLedgerStatus(
+  status: PlayRunLedgerStatus,
+): boolean {
+  return TERMINAL_STATUSES.has(status);
+}
+
+export function createEmptyPlayRunLedgerSnapshot(input: {
+  runId: string;
+  playName?: string | null;
+  status?: unknown;
+  error?: string | null;
+  createdAt?: number | null;
+  startedAt?: number | null;
+  updatedAt?: number | null;
+  finishedAt?: number | null;
+}): PlayRunLedgerSnapshot {
+  const status = normalizePlayRunLedgerStatus(input.status ?? 'unknown');
+  const startedAt = finiteNumber(input.startedAt) ?? null;
+  const finishedAt = finiteNumber(input.finishedAt) ?? null;
+  return {
+    runId: input.runId,
+    playName: input.playName ?? null,
+    status,
+    error: optionalNullableString(input.error) ?? null,
+    createdAt: finiteNumber(input.createdAt) ?? null,
+    startedAt,
+    updatedAt:
+      finiteNumber(input.updatedAt) ??
+      finishedAt ??
+      startedAt ??
+      finiteNumber(input.createdAt) ??
+      null,
+    finishedAt,
+    durationMs:
+      startedAt !== null && finishedAt !== null
+        ? Math.max(0, finishedAt - startedAt)
+        : null,
+    orderedStepIds: [],
+    stepsById: {},
+    logTail: [],
+    totalLogCount: 0,
+    logsTruncated: false,
+    activeStepId: null,
+    activeArtifactTableNamespace: null,
+    resultTableNamespace: null,
+  };
+}
+
+export function normalizePlayRunLedgerSnapshot(
+  value: unknown,
+  fallback: Parameters<typeof createEmptyPlayRunLedgerSnapshot>[0],
+): PlayRunLedgerSnapshot {
+  if (!isRecord(value)) {
+    return createEmptyPlayRunLedgerSnapshot(fallback);
+  }
+  const orderedStepIds = Array.isArray(value.orderedStepIds)
+    ? value.orderedStepIds.filter(
+        (entry): entry is string =>
+          typeof entry === 'string' && Boolean(entry.trim()),
+      )
+    : [];
+  const rawSteps = isRecord(value.stepsById) ? value.stepsById : {};
+  const stepsById: Record<string, PlayRunLedgerStepSnapshot> = {};
+  for (const [stepId, rawStep] of Object.entries(rawSteps)) {
+    if (!stepId.trim() || !isRecord(rawStep)) continue;
+    const rawStatus = normalizeStepStatus(rawStep.status);
+    if (!rawStatus) continue;
+    const completedAt = finiteNumber(rawStep.completedAt);
+    const status =
+      rawStatus === 'running' && completedAt !== null ? 'completed' : rawStatus;
+    const rawProgress = isRecord(rawStep.progress) ? rawStep.progress : null;
+    stepsById[stepId] = {
+      stepId,
+      label: optionalString(rawStep.label),
+      kind: optionalString(rawStep.kind),
+      status,
+      artifactTableNamespace: optionalNullableString(
+        rawStep.artifactTableNamespace,
+      ),
+      startedAt: finiteNumber(rawStep.startedAt),
+      completedAt,
+      updatedAt: finiteNumber(rawStep.updatedAt),
+      progress: rawProgress ? normalizeStepProgress(rawProgress) : null,
+    };
+  }
+  const createdAt = finiteNumber(value.createdAt) ?? fallback.createdAt ?? null;
+  const startedAt = finiteNumber(value.startedAt) ?? fallback.startedAt ?? null;
+  const finishedAt =
+    finiteNumber(value.finishedAt) ?? fallback.finishedAt ?? null;
+  const updatedAt =
+    finiteNumber(value.updatedAt) ??
+    fallback.updatedAt ??
+    finishedAt ??
+    startedAt ??
+    createdAt ??
+    null;
+  const error = Object.prototype.hasOwnProperty.call(value, 'error')
+    ? (optionalNullableString(value.error) ?? null)
+    : (fallback.error ?? null);
+  // `logTail` is canonical; `logs` is the pre-Run-Log-Stream persisted name.
+  // Reading both is the deploy-window seam that lets the first post-cutover
+  // append backfill an old snapshot's retained tail into chunk storage.
+  const rawTail = Array.isArray(value.logTail) ? value.logTail : value.logs;
+  const logTail = Array.isArray(rawTail)
+    ? rawTail.filter((line): line is string => typeof line === 'string')
+    : [];
+  return {
+    runId: optionalString(value.runId) ?? fallback.runId,
+    playName:
+      optionalNullableString(value.playName) ?? fallback.playName ?? null,
+    status: normalizePlayRunLedgerStatus(value.status ?? fallback.status),
+    error,
+    createdAt,
+    startedAt,
+    updatedAt,
+    finishedAt,
+    durationMs:
+      startedAt !== null && finishedAt !== null
+        ? Math.max(0, finishedAt - startedAt)
+        : finiteNumber(value.durationMs),
+    orderedStepIds: orderedStepIds.filter((stepId) => stepsById[stepId]),
+    stepsById,
+    logTail: logTail.slice(-LOG_TAIL_LIMIT),
+    // Snapshots persisted before totalLogCount existed only know the retained
+    // tail, so the best lower bound for the cumulative count is the tail size.
+    totalLogCount: Math.max(
+      finiteNumber(value.totalLogCount) ?? logTail.length,
+      logTail.length,
+    ),
+    logsTruncated: value.logsTruncated === true,
+    activeStepId: optionalNullableString(value.activeStepId),
+    activeArtifactTableNamespace: optionalNullableString(
+      value.activeArtifactTableNamespace,
+    ),
+    resultTableNamespace: optionalNullableString(value.resultTableNamespace),
+    resultSummary: value.resultSummary,
+    result: value.result,
+  };
+}
+
+function normalizeStepStatus(value: unknown): PlayRunLedgerStepStatus | null {
+  const normalized = String(value ?? '')
+    .trim()
+    .toLowerCase();
+  if (
+    normalized === 'running' ||
+    normalized === 'completed' ||
+    normalized === 'failed' ||
+    normalized === 'skipped'
+  ) {
+    return normalized;
+  }
+  return null;
+}
+
+function normalizeStepProgress(
+  value: Record<string, unknown>,
+): PlayRunLedgerStepProgress {
+  return {
+    ...(optionalFiniteNumber(value.completed) !== undefined
+      ? { completed: optionalFiniteNumber(value.completed) }
+      : {}),
+    ...(optionalFiniteNumber(value.total) !== undefined
+      ? { total: optionalFiniteNumber(value.total) }
+      : {}),
+    ...(optionalFiniteNumber(value.failed) !== undefined
+      ? { failed: optionalFiniteNumber(value.failed) }
+      : {}),
+    ...(optionalString(value.message)
+      ? { message: optionalString(value.message) }
+      : {}),
+    ...(optionalNullableString(value.artifactTableNamespace) !== undefined
+      ? {
+          artifactTableNamespace: optionalNullableString(
+            value.artifactTableNamespace,
+          ),
+        }
+      : {}),
+    ...(finiteNumber(value.updatedAt) !== null
+      ? { updatedAt: finiteNumber(value.updatedAt) }
+      : {}),
+  };
+}
+
+function normalizeLiveProgressMap(
+  value: unknown,
+): Record<string, PlayRunLedgerStepProgress> {
+  if (!isRecord(value)) {
+    return {};
+  }
+  const normalized: Record<string, PlayRunLedgerStepProgress> = {};
+  for (const [stepId, rawProgress] of Object.entries(value)) {
+    if (!stepId.trim() || !isRecord(rawProgress)) continue;
+    normalized[stepId] = {
+      ...normalizeStepProgress(rawProgress),
+      ...(optionalFiniteNumber(rawProgress.startedAt) !== undefined
+        ? { startedAt: optionalFiniteNumber(rawProgress.startedAt) }
+        : {}),
+      ...(optionalFiniteNumber(rawProgress.completedAt) !== undefined
+        ? { completedAt: optionalFiniteNumber(rawProgress.completedAt) }
+        : {}),
+    };
+  }
+  return normalized;
+}
+
+function appendOrderedStepId(
+  snapshot: PlayRunLedgerSnapshot,
+  stepId: string,
+): string[] {
+  return snapshot.orderedStepIds.includes(stepId)
+    ? snapshot.orderedStepIds
+    : [...snapshot.orderedStepIds, stepId];
+}
+
+function resolveResultTableNamespace(
+  snapshot: PlayRunLedgerSnapshot,
+): string | null {
+  const terminalStepNamespace = [...snapshot.orderedStepIds]
+    .reverse()
+    .map((stepId) => snapshot.stepsById[stepId]?.artifactTableNamespace)
+    .find((namespace): namespace is string => Boolean(namespace?.trim()));
+  return snapshot.resultTableNamespace ?? terminalStepNamespace ?? null;
+}
+
+function withTiming(snapshot: PlayRunLedgerSnapshot): PlayRunLedgerSnapshot {
+  const startedAt = snapshot.startedAt ?? null;
+  const finishedAt = snapshot.finishedAt ?? null;
+  return {
+    ...snapshot,
+    durationMs:
+      startedAt !== null && finishedAt !== null
+        ? Math.max(0, finishedAt - startedAt)
+        : null,
+    resultTableNamespace: isTerminalPlayRunLedgerStatus(snapshot.status)
+      ? resolveResultTableNamespace(snapshot)
+      : (snapshot.resultTableNamespace ?? null),
+  };
+}
+
+const TERMINAL_STATUS_BY_EVENT_TYPE = {
+  'run.completed': 'completed',
+  'run.failed': 'failed',
+  'run.cancelled': 'cancelled',
+} as const satisfies Partial<Record<string, PlayRunLedgerStatus>>;
+
+/**
+ * Append already-deduplicated log lines to the snapshot tail.
+ *
+ * Cross-channel reconciliation (positional worker cursors, bounded
+ * text-window dedupe for recovery channels) happens at Run Log Stream
+ * ingestion in Convex, BEFORE events reach this reducer. The reducer trusts
+ * the event: every line counts, repeated identical lines included.
+ *
+ * Events stamped with `firstSeq` (assigned by ingestion) pin the cumulative
+ * count exactly; unstamped events (reducer-internal anomaly markers,
+ * producer-side snapshot caches) advance it by line count.
+ */
+function appendLogLines(
+  snapshot: PlayRunLedgerSnapshot,
+  lines: readonly string[],
+  options?: { firstSeq?: number; logsTruncated?: boolean },
+): PlayRunLedgerSnapshot {
+  const nextLines = lines
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  const totalLogCount =
+    typeof options?.firstSeq === 'number' && options.firstSeq > 0
+      ? Math.max(
+          snapshot.totalLogCount,
+          options.firstSeq + nextLines.length - 1,
+        )
+      : snapshot.totalLogCount + nextLines.length;
+  return {
+    ...snapshot,
+    logTail: [...snapshot.logTail, ...nextLines].slice(-LOG_TAIL_LIMIT),
+    totalLogCount,
+    logsTruncated: snapshot.logsTruncated || options?.logsTruncated === true,
+  };
+}
+
+/**
+ * Terminal-status precedence. Re-delivery of the same terminal status is a
+ * benign no-op handled by the regular reduction. A terminal event that
+ * disagrees with an already-terminal snapshot is ignored (keeping e.g. an
+ * explicit user cancellation from being flipped to completed by a late
+ * worker terminal), and the conflict is recorded as one anomaly log line —
+ * with ONE exception: `run.failed` DEMOTES a `completed` snapshot. The
+ * worker appends run.completed BEFORE awaiting post-completion accounting
+ * (compute billing finalize), so a billing business denial there — e.g. the
+ * per-run credit cap (maxCreditsPerRun) — arrives as a later run.failed
+ * that MUST fail the run. Blanket first-terminal-wins silently completed
+ * capped runs (regression pinned by
+ * tests/v2-plays/plays/44-compute-billing-cap.play.ts). A cancelled run
+ * stays cancelled, and a failed run can never be flipped to completed.
+ */
+function conflictingTerminalSnapshot(
+  base: PlayRunLedgerSnapshot,
+  eventType: keyof typeof TERMINAL_STATUS_BY_EVENT_TYPE,
+): PlayRunLedgerSnapshot | null {
+  if (!isTerminalPlayRunLedgerStatus(base.status)) {
+    return null;
+  }
+  if (TERMINAL_STATUS_BY_EVENT_TYPE[eventType] === base.status) {
+    return null;
+  }
+  if (base.status === 'completed' && eventType === 'run.failed') {
+    // Post-completion accounting demotion (e.g. per-run billing cap denial):
+    // let the regular run.failed reduction flip the run to failed.
+    return null;
+  }
+  return withTiming(
+    appendLogLines(base, [
+      `[ledger] conflicting terminal event ${eventType} ignored; status already ${base.status}`,
+    ]),
+  );
+}
+
+export function reducePlayRunLedgerEvent(
+  snapshot: PlayRunLedgerSnapshot,
+  event: PlayRunLedgerEvent,
+): PlayRunLedgerSnapshot {
+  if (event.runId !== snapshot.runId) {
+    return snapshot;
+  }
+  const occurredAt = Math.max(0, event.occurredAt);
+  const base: PlayRunLedgerSnapshot = {
+    ...snapshot,
+    updatedAt: Math.max(snapshot.updatedAt ?? 0, occurredAt),
+  };
+
+  switch (event.type) {
+    case 'run.created':
+      return withTiming({
+        ...base,
+        playName: event.playName ?? base.playName ?? null,
+        status: event.status ?? base.status,
+        createdAt: base.createdAt ?? occurredAt,
+      });
+    case 'run.started':
+      return withTiming({
+        ...base,
+        playName: event.playName ?? base.playName ?? null,
+        status: isTerminalPlayRunLedgerStatus(base.status)
+          ? base.status
+          : 'running',
+        startedAt: base.startedAt ?? occurredAt,
+      });
+    case 'run.completed':
+      return (
+        conflictingTerminalSnapshot(base, event.type) ??
+        withTiming({
+          ...base,
+          status: 'completed',
+          error: null,
+          startedAt: base.startedAt ?? occurredAt,
+          finishedAt: base.finishedAt ?? occurredAt,
+          activeStepId: null,
+          activeArtifactTableNamespace: null,
+          result: event.result ?? base.result,
+          resultSummary: event.resultSummary ?? base.resultSummary,
+        })
+      );
+    case 'run.failed':
+      return (
+        conflictingTerminalSnapshot(base, event.type) ??
+        withTiming({
+          ...base,
+          status: 'failed',
+          error: event.error ?? base.error ?? null,
+          startedAt: base.startedAt ?? occurredAt,
+          finishedAt: base.finishedAt ?? occurredAt,
+          activeStepId: null,
+          activeArtifactTableNamespace: null,
+          result: event.result ?? base.result,
+        })
+      );
+    case 'run.cancelled':
+      return (
+        conflictingTerminalSnapshot(base, event.type) ??
+        withTiming({
+          ...base,
+          status: 'cancelled',
+          error: event.error ?? base.error ?? null,
+          startedAt: base.startedAt ?? occurredAt,
+          finishedAt: base.finishedAt ?? occurredAt,
+          activeStepId: null,
+          activeArtifactTableNamespace: null,
+          result: event.result ?? base.result,
+        })
+      );
+    case 'log.appended':
+      return withTiming(
+        appendLogLines(base, event.lines, {
+          ...(typeof event.firstSeq === 'number'
+            ? { firstSeq: event.firstSeq }
+            : {}),
+          ...(event.logsTruncated === true ? { logsTruncated: true } : {}),
+        }),
+      );
+    case 'step.started': {
+      const current = base.stepsById[event.stepId];
+      const nextStep: PlayRunLedgerStepSnapshot = {
+        ...(current ?? { stepId: event.stepId, status: 'running' as const }),
+        stepId: event.stepId,
+        label: event.label ?? current?.label,
+        kind: event.kind ?? current?.kind,
+        status:
+          current?.status === 'failed' || current?.status === 'completed'
+            ? current.status
+            : 'running',
+        artifactTableNamespace:
+          event.artifactTableNamespace ??
+          current?.artifactTableNamespace ??
+          null,
+        startedAt: current?.startedAt ?? occurredAt,
+        updatedAt: occurredAt,
+      };
+      return withTiming({
+        ...base,
+        status: isTerminalPlayRunLedgerStatus(base.status)
+          ? base.status
+          : 'running',
+        startedAt: base.startedAt ?? occurredAt,
+        orderedStepIds: appendOrderedStepId(base, event.stepId),
+        stepsById: { ...base.stepsById, [event.stepId]: nextStep },
+        activeStepId:
+          nextStep.status === 'running' ? event.stepId : base.activeStepId,
+        activeArtifactTableNamespace:
+          nextStep.status === 'running'
+            ? (nextStep.artifactTableNamespace ?? null)
+            : (base.activeArtifactTableNamespace ?? null),
+      });
+    }
+    case 'step.progress': {
+      const current = base.stepsById[event.stepId];
+      const progress = {
+        ...(current?.progress ?? {}),
+        ...event.progress,
+        updatedAt: event.progress.updatedAt ?? occurredAt,
+      };
+      const inferredStatus =
+        typeof progress.completedAt === 'number' ||
+        (typeof progress.total === 'number' &&
+          typeof progress.completed === 'number' &&
+          progress.total > 0 &&
+          progress.completed >= progress.total)
+          ? 'completed'
+          : 'running';
+      const status =
+        current?.status === 'failed' ||
+        current?.status === 'skipped' ||
+        current?.status === 'completed'
+          ? current.status
+          : event.status === 'running' && inferredStatus === 'completed'
+            ? 'completed'
+            : (event.status ?? current?.status ?? inferredStatus);
+      const nextStep: PlayRunLedgerStepSnapshot = {
+        ...(current ?? { stepId: event.stepId, status }),
+        stepId: event.stepId,
+        label: event.label ?? current?.label,
+        kind: event.kind ?? current?.kind,
+        status,
+        artifactTableNamespace:
+          progress.artifactTableNamespace ??
+          current?.artifactTableNamespace ??
+          null,
+        startedAt: current?.startedAt ?? event.progress.startedAt ?? null,
+        completedAt:
+          current?.completedAt ??
+          event.progress.completedAt ??
+          (status === 'completed'
+            ? (event.progress.updatedAt ?? occurredAt)
+            : null),
+        updatedAt: occurredAt,
+        progress,
+      };
+      return withTiming({
+        ...base,
+        orderedStepIds: appendOrderedStepId(base, event.stepId),
+        stepsById: { ...base.stepsById, [event.stepId]: nextStep },
+        activeStepId:
+          status === 'running'
+            ? event.stepId
+            : base.activeStepId === event.stepId
+              ? null
+              : base.activeStepId,
+        activeArtifactTableNamespace:
+          status === 'running'
+            ? (nextStep.artifactTableNamespace ?? null)
+            : base.activeStepId === event.stepId
+              ? null
+              : (base.activeArtifactTableNamespace ?? null),
+      });
+    }
+    case 'step.completed':
+    case 'step.failed':
+    case 'step.skipped': {
+      const current = base.stepsById[event.stepId];
+      const preserveFailedStatus =
+        current?.status === 'failed' && event.type !== 'step.failed';
+      const status = preserveFailedStatus
+        ? 'failed'
+        : event.type === 'step.completed'
+          ? 'completed'
+          : event.type === 'step.failed'
+            ? 'failed'
+            : 'skipped';
+      const nextStep: PlayRunLedgerStepSnapshot = {
+        ...(current ?? { stepId: event.stepId, status }),
+        stepId: event.stepId,
+        label: event.label ?? current?.label,
+        kind: event.kind ?? current?.kind,
+        status,
+        artifactTableNamespace:
+          event.artifactTableNamespace ??
+          current?.artifactTableNamespace ??
+          null,
+        startedAt: current?.startedAt ?? null,
+        completedAt:
+          status === 'skipped' || preserveFailedStatus
+            ? (current?.completedAt ?? null)
+            : occurredAt,
+        updatedAt: occurredAt,
+        progress: current?.progress ?? null,
+      };
+      const runningStepIds = base.orderedStepIds.filter((stepId) => {
+        if (stepId === event.stepId) return false;
+        return base.stepsById[stepId]?.status === 'running';
+      });
+      const activeStepId = runningStepIds.at(-1) ?? null;
+      return withTiming({
+        ...base,
+        orderedStepIds: appendOrderedStepId(base, event.stepId),
+        stepsById: { ...base.stepsById, [event.stepId]: nextStep },
+        activeStepId,
+        activeArtifactTableNamespace: activeStepId
+          ? (base.stepsById[activeStepId]?.artifactTableNamespace ?? null)
+          : null,
+      });
+    }
+    case 'sheet.summary.updated':
+      return withTiming({
+        ...base,
+        resultTableNamespace:
+          base.resultTableNamespace ?? event.tableNamespace ?? null,
+      });
+  }
+}
+
+export function reducePlayRunLedgerEvents(
+  snapshot: PlayRunLedgerSnapshot,
+  events: readonly PlayRunLedgerEvent[],
+): PlayRunLedgerSnapshot {
+  return events.reduce(reducePlayRunLedgerEvent, snapshot);
+}
+
+function progressSignature(
+  progress: PlayRunLedgerStepProgress | null | undefined,
+): string {
+  return JSON.stringify({
+    completed: progress?.completed ?? null,
+    total: progress?.total ?? null,
+    failed: progress?.failed ?? null,
+    message: progress?.message ?? null,
+    artifactTableNamespace: progress?.artifactTableNamespace ?? null,
+    startedAt: progress?.startedAt ?? null,
+    completedAt: progress?.completedAt ?? null,
+  });
+}
+
+function terminalEventTypeForStatus(
+  status: PlayRunLedgerStatus,
+): 'run.completed' | 'run.failed' | 'run.cancelled' | null {
+  if (status === 'completed') return 'run.completed';
+  if (
+    status === 'failed' ||
+    status === 'terminated' ||
+    status === 'timed_out'
+  ) {
+    return 'run.failed';
+  }
+  if (status === 'cancelled') return 'run.cancelled';
+  return null;
+}
+
+/**
+ * Slice the not-yet-sent suffix out of a producer's rotating log buffer,
+ * using positional counts instead of text comparison.
+ *
+ * `bufferTotalCount` is the count of lines the producer ever emitted on this
+ * channel (monotonic); `bufferLines` is its retained tail of those lines.
+ * `sentCount` is the producer-side cursor: lines already handed to the
+ * ledger. Returns the new lines plus the `channelOffset` of the first one,
+ * or null when there is nothing new. Lines that rotated out of the buffer
+ * before they were ever sent surface as a positive gap at ingestion (which
+ * records a loud gap marker) instead of being silently re-numbered.
+ */
+export function slicePositionalLogLines(input: {
+  bufferLines: readonly string[];
+  bufferTotalCount: number;
+  sentCount: number;
+}): { lines: string[]; channelOffset: number } | null {
+  const total = Math.max(input.bufferTotalCount, input.bufferLines.length);
+  const sent = Math.max(0, input.sentCount);
+  if (total <= sent) {
+    return null;
+  }
+  const bufferFirstOffset = total - input.bufferLines.length;
+  const sendFromOffset = Math.max(sent, bufferFirstOffset);
+  const lines = input.bufferLines.slice(sendFromOffset - bufferFirstOffset);
+  if (lines.length === 0) {
+    return null;
+  }
+  return { lines: [...lines], channelOffset: sendFromOffset };
+}
+
+/**
+ * Forward producer log lines as one `log.appended` event.
+ *
+ * No text dedupe here: redundant-delivery reconciliation moved to Run Log
+ * Stream ingestion (positional `channelOffset` cursors for the worker
+ * channel, bounded tail-window text dedupe for recovery channels).
+ */
+export function buildPlayRunLedgerEventsFromLogLines(input: {
+  runId: string;
+  lines: readonly string[];
+  source?: PlayRunLedgerEventSource;
+  occurredAt?: number;
+  channelOffset?: number | null;
+  includeLogAppend?: boolean;
+}): PlayRunLedgerEvent[] {
+  const source = input.source ?? 'worker';
+  const occurredAt = input.occurredAt ?? Date.now();
+  const positional =
+    typeof input.channelOffset === 'number' &&
+    input.channelOffset >= 0 &&
+    Number.isFinite(input.channelOffset);
+  // Positional batches must keep one entry per emitted line — dropping a
+  // blank would shift every later line off its channel position.
+  const newLines = positional
+    ? input.lines.map((line) => line.trim() || '(blank log line)')
+    : input.lines.map((line) => line.trim()).filter((line) => line.length > 0);
+  if (newLines.length === 0 || input.includeLogAppend === false) {
+    return [];
+  }
+  return [
+    {
+      type: 'log.appended',
+      runId: input.runId,
+      source,
+      occurredAt,
+      lines: newLines,
+      ...(positional ? { channelOffset: input.channelOffset! } : {}),
+    },
+  ];
+}
+
+export function buildPlayRunLedgerEventsFromStatusPatch(input: {
+  patch: PlayRunLedgerStatusPatch;
+  previousSnapshot: PlayRunLedgerSnapshot;
+  now?: number;
+  source?: PlayRunLedgerEventSource;
+}): PlayRunLedgerEvent[] {
+  const now = input.now ?? Date.now();
+  const source = input.source ?? 'worker';
+  const patch = input.patch;
+  const status = normalizePlayRunLedgerStatus(patch.status);
+  const liveProgress = normalizeLiveProgressMap(patch.liveNodeProgress);
+  const checkpointAt = finiteNumber(patch.lastCheckpointAt) ?? now;
+  const progressStartedAts = Object.values(liveProgress)
+    .map((progress) => progress.startedAt)
+    .filter((value): value is number => typeof value === 'number');
+  const progressCompletedAts = Object.values(liveProgress)
+    .map((progress) => progress.completedAt)
+    .filter((value): value is number => typeof value === 'number');
+  const existingStepStartedAts = Object.values(input.previousSnapshot.stepsById)
+    .map((step) => step.startedAt)
+    .filter((value): value is number => typeof value === 'number');
+  const existingStepCompletedAts = Object.values(
+    input.previousSnapshot.stepsById,
+  )
+    .map((step) => step.completedAt)
+    .filter((value): value is number => typeof value === 'number');
+  const logEvents = Array.isArray(patch.liveLogs)
+    ? buildPlayRunLedgerEventsFromLogLines({
+        runId: patch.runId,
+        lines: patch.liveLogs,
+        source,
+        occurredAt: checkpointAt,
+        channelOffset: patch.liveLogsChannelOffset ?? null,
+      })
+    : [];
+  const earliestStartedAt =
+    progressStartedAts.length > 0 || existingStepStartedAts.length > 0
+      ? Math.min(...progressStartedAts, ...existingStepStartedAts)
+      : null;
+  const latestCompletedAt =
+    progressCompletedAts.length > 0 || existingStepCompletedAts.length > 0
+      ? Math.max(...progressCompletedAts, ...existingStepCompletedAts)
+      : null;
+  const events: PlayRunLedgerEvent[] = [];
+
+  if (
+    !input.previousSnapshot.startedAt &&
+    (Object.keys(liveProgress).length > 0 ||
+      status === 'running' ||
+      isTerminalPlayRunLedgerStatus(status))
+  ) {
+    events.push({
+      type: 'run.started',
+      runId: patch.runId,
+      playName: patch.playName ?? input.previousSnapshot.playName ?? null,
+      source,
+      occurredAt: earliestStartedAt ?? checkpointAt,
+      runtimeBackend: patch.runtimeBackend ?? null,
+    });
+  }
+
+  events.push(...logEvents);
+
+  for (const [stepId, progress] of Object.entries(liveProgress)) {
+    const previousStep = input.previousSnapshot.stepsById[stepId];
+    if (progress.startedAt && !previousStep?.startedAt) {
+      events.push({
+        type: 'step.started',
+        runId: patch.runId,
+        source,
+        occurredAt: progress.startedAt,
+        stepId,
+        artifactTableNamespace: progress.artifactTableNamespace ?? null,
+      });
+    }
+
+    const normalizedProgress: PlayRunLedgerStepProgress = {
+      ...(progress.completed !== undefined
+        ? { completed: progress.completed }
+        : {}),
+      ...(progress.total !== undefined ? { total: progress.total } : {}),
+      ...(progress.failed !== undefined ? { failed: progress.failed } : {}),
+      ...(progress.message !== undefined ? { message: progress.message } : {}),
+      ...(progress.artifactTableNamespace !== undefined
+        ? { artifactTableNamespace: progress.artifactTableNamespace }
+        : {}),
+      ...(progress.startedAt !== undefined
+        ? { startedAt: progress.startedAt }
+        : {}),
+      ...(progress.completedAt !== undefined
+        ? { completedAt: progress.completedAt }
+        : {}),
+      updatedAt: progress.updatedAt ?? checkpointAt,
+    };
+    if (
+      progressSignature(normalizedProgress) !==
+      progressSignature(previousStep?.progress)
+    ) {
+      events.push({
+        type: 'step.progress',
+        runId: patch.runId,
+        source,
+        occurredAt: progress.updatedAt ?? checkpointAt,
+        stepId,
+        status:
+          typeof progress.completedAt === 'number'
+            ? 'completed'
+            : previousStep?.status === 'failed'
+              ? 'failed'
+              : 'running',
+        progress: normalizedProgress,
+      });
+    }
+
+    if (progress.completedAt && !previousStep?.completedAt) {
+      events.push({
+        type: 'step.completed',
+        runId: patch.runId,
+        source,
+        occurredAt: progress.completedAt,
+        stepId,
+        artifactTableNamespace: progress.artifactTableNamespace ?? null,
+      });
+    }
+  }
+
+  const terminalType = terminalEventTypeForStatus(status);
+  if (
+    terminalType &&
+    !isTerminalPlayRunLedgerStatus(input.previousSnapshot.status)
+  ) {
+    const occurredAt = latestCompletedAt ?? checkpointAt;
+    if (terminalType === 'run.completed') {
+      events.push({
+        type: terminalType,
+        runId: patch.runId,
+        source,
+        occurredAt,
+        result: patch.result,
+      });
+    } else {
+      events.push({
+        type: terminalType,
+        runId: patch.runId,
+        source,
+        occurredAt,
+        error: patch.error ?? null,
+        result: patch.result,
+      });
+    }
+  }
+
+  return events;
+}