deepline 0.3.144 → 0.3.146

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

@@ -59,16 +59,16 @@ export type PlayRunLedgerEventSource =
  *   these; they re-execute on the next run).
  * - `total` is the settled-row denominator. In-flight it is the row-count
  *   estimate (`rowCountHint`); at map finalize it is reconciled to
- *   `completed + failed` and CAN SHRINK from the initial estimate when rows are
- *   filtered/skipped. So `total` is monotonic-up during flight but is corrected
- *   down to the settled count at terminal.
+ *   `completed + failed + supersededRows` and CAN SHRINK from the initial
+ *   estimate when rows are filtered/skipped. So `total` is monotonic-up during
+ *   flight but is corrected down to the settled count at terminal.
  *
- * Terminal invariant: once the step is settled, `completed + failed === total`.
- * Because `completed` is successes-only (NOT all-settled), readers must NOT
- * assume `completed === total` at terminal — a truthful terminal render is
- * `{total} rows` when `failed === 0`, else a `completed`/`failed`/`total`
- * breakdown. See `settleRunningStepsOnTerminal` for why the reducer does not
- * force `completed = total`.
+ * Terminal invariant: once the step is settled,
+ * `completed + failed + supersededRows === total` when supersededRows is
+ * present; older producers without that field use `completed + failed ===
+ * total`. Because `completed` is successes-only (NOT all-settled), readers
+ * must not assume `completed === total`. Superseded rows are omitted because a
+ * newer Runtime Sheet write won, not because this step failed.
  */
 export type PlayRunLedgerStepProgress = {
   completed?: number;
@@ -78,6 +78,7 @@ export type PlayRunLedgerStepProgress = {
   activeRows?: number;
   waitingRows?: number;
   completedRows?: number;
+  supersededRows?: number;
   message?: string;
   artifactTableNamespace?: string | null;
   startedAt?: number | null;
@@ -209,6 +210,7 @@ export type PlayRunLedgerEvent =
       type: 'run.failed';
       error?: string | null;
       result?: unknown;
+      resultSummary?: unknown;
     })
   | (PlayRunLedgerBaseEvent & {
       type: 'run.cancelled';
@@ -463,14 +465,17 @@ export type PlayRunRowOutcomeSummary = {
   failedRows: number;
   totalRows: number;
   hasRowFailures: boolean;
+  supersededRows?: number;
 };
 
 export function summarizeRunRowOutcomes(
-  snapshot: Pick<PlayRunLedgerSnapshot, 'stepsById'>,
+  snapshot: Pick<PlayRunLedgerSnapshot, 'stepsById'> &
+    Partial<Pick<PlayRunLedgerSnapshot, 'resultSummary'>>,
 ): PlayRunRowOutcomeSummary {
   let completedRows = 0;
   let failedRows = 0;
   let totalRows = 0;
+  let supersededRows = 0;
   for (const step of Object.values(snapshot.stepsById)) {
     const progress = step.progress;
     if (!progress) continue;
@@ -479,20 +484,39 @@ export function summarizeRunRowOutcomes(
     // row outcome, not just the last step.
     completedRows += Math.max(0, finiteNumber(progress.completed) ?? 0);
     failedRows += Math.max(0, finiteNumber(progress.failed) ?? 0);
-    // Prefer the settled denominator; fall back to completed+failed when a
-    // producer never stamped `total` (per the terminal invariant those agree).
+    supersededRows += Math.max(0, finiteNumber(progress.supersededRows) ?? 0);
+    // Prefer the settled denominator; fall back to completed+failed+superseded
+    // when a producer never stamped `total`.
     const stepTotal = finiteNumber(progress.total);
     totalRows +=
       stepTotal !== null && stepTotal >= 0
         ? stepTotal
         : Math.max(0, finiteNumber(progress.completed) ?? 0) +
-          Math.max(0, finiteNumber(progress.failed) ?? 0);
+          Math.max(0, finiteNumber(progress.failed) ?? 0) +
+          Math.max(0, finiteNumber(progress.supersededRows) ?? 0);
   }
+  const resultSummary = isRecord(snapshot.resultSummary)
+    ? snapshot.resultSummary
+    : null;
+  const resultRowOutcomes = isRecord(resultSummary?.rowOutcomes)
+    ? resultSummary.rowOutcomes
+    : null;
+  const terminalCompletedRows = finiteNumber(resultRowOutcomes?.completedRows);
+  const terminalFailedRows = finiteNumber(resultRowOutcomes?.failedRows);
+  const terminalTotalRows = finiteNumber(resultRowOutcomes?.totalRows);
+  const terminalSupersededRows = finiteNumber(
+    resultRowOutcomes?.supersededRows,
+  );
+  const settledCompletedRows = terminalCompletedRows ?? completedRows;
+  const settledFailedRows = terminalFailedRows ?? failedRows;
   return {
-    completedRows,
-    failedRows,
-    totalRows,
-    hasRowFailures: failedRows > 0,
+    completedRows: settledCompletedRows,
+    failedRows: settledFailedRows,
+    totalRows: terminalTotalRows ?? totalRows,
+    hasRowFailures: settledFailedRows > 0,
+    ...((terminalSupersededRows ?? supersededRows) > 0
+      ? { supersededRows: terminalSupersededRows ?? supersededRows }
+      : {}),
   };
 }
 
@@ -762,6 +786,11 @@ function mergeMonotonicStepProgress(input: {
           ),
         }
       : {}),
+    ...(next.supersededRows !== undefined
+      ? { supersededRows: Math.max(0, next.supersededRows) }
+      : current.supersededRows !== undefined
+        ? { supersededRows: current.supersededRows }
+        : {}),
   };
 }
 
@@ -771,8 +800,8 @@ function mergeMonotonicStepProgress(input: {
  * live-only counters: once a step is terminal nothing is in flight or waiting,
  * so leaving the last observed values renders a contradiction like
  * "status: completed · 1 in flight · waiting 29". This preserves the settled
- * counts (completed/failed/total/completedRows/startedRows) and only clears the
- * two live accumulators. Idempotent: dropping already-absent fields is a no-op.
+ * counts (including supersededRows) and only clears the two live accumulators.
+ * Idempotent: dropping already-absent fields is a no-op.
  */
 function clearInFlightProgressOnTerminal(
   progress: PlayRunLedgerStepProgress | null | undefined,
@@ -831,6 +860,9 @@ function normalizeStepProgress(
     ...(optionalFiniteNumber(value.completedRows) !== undefined
       ? { completedRows: optionalFiniteNumber(value.completedRows) }
       : {}),
+    ...(optionalFiniteNumber(value.supersededRows) !== undefined
+      ? { supersededRows: optionalFiniteNumber(value.supersededRows) }
+      : {}),
     ...(optionalString(value.message)
       ? { message: optionalString(value.message) }
       : {}),
@@ -1309,6 +1341,8 @@ export function reducePlayRunLedgerEvent(
           allowStaleSameStatusPayloadMerge:
             (base.error == null && event.error != null) ||
             (base.result === undefined && event.result !== undefined) ||
+            (base.resultSummary === undefined &&
+              event.resultSummary !== undefined) ||
             canPromoteTerminalResultReference(base.result, event.result),
         }) ??
         withTiming({
@@ -1327,6 +1361,7 @@ export function reducePlayRunLedgerEvent(
             current: base.result,
             next: event.result,
           }),
+          resultSummary: event.resultSummary ?? base.resultSummary,
           terminalSource: nextTerminalSource(base, event.source),
         })
       );
@@ -1657,6 +1692,7 @@ function progressSignature(
     activeRows: progress?.activeRows ?? null,
     waitingRows: progress?.waitingRows ?? null,
     completedRows: progress?.completedRows ?? null,
+    supersededRows: progress?.supersededRows ?? null,
     message: progress?.message ?? null,
     artifactTableNamespace: progress?.artifactTableNamespace ?? null,
     startedAt: progress?.startedAt ?? null,
@@ -1913,6 +1949,9 @@ export function buildPlayRunLedgerEventsFromStatusPatch(input: {
       ...(progress.completedRows !== undefined
         ? { completedRows: progress.completedRows }
         : {}),
+      ...(progress.supersededRows !== undefined
+        ? { supersededRows: progress.supersededRows }
+        : {}),
       ...(progress.message !== undefined ? { message: progress.message } : {}),
       ...(progress.artifactTableNamespace !== undefined
         ? { artifactTableNamespace: progress.artifactTableNamespace }

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

@@ -103,11 +103,11 @@ export type PlayRunLiveSnapshot = {
   nodeStates: PlayRunStreamNodeState[];
   activeNodeId: string | null;
   /**
-   * Additive, terminal-only aggregate of row outcomes across all steps. Present
-   * once the run is terminal so readers can render a truthful "completed with
-   * failures" surface (row-failure isolation persists failed rows for retry, so
-   * a run legitimately reports `status: 'completed'` with `rowOutcomes.failedRows
-   * > 0`). Absent on non-terminal snapshots and on runs with no row/map steps.
+   * Additive, terminal-only aggregate of row outcomes across all steps. It lets
+   * readers distinguish successful, failed, and superseded rows. Superseded
+   * rows were omitted because a newer Runtime Sheet write won; they are neither
+   * failures nor pending work. Absent on non-terminal snapshots and runs
+   * without row outcomes.
    */
   rowOutcomes?: PlayRunRowOutcomeSummary;
 };
@@ -205,6 +205,7 @@ function buildSnapshotFromLedger(
             activeRows: step.progress.activeRows,
             waitingRows: step.progress.waitingRows,
             completedRows: step.progress.completedRows,
+            supersededRows: step.progress.supersededRows,
             message: step.progress.message,
             artifactTableNamespace:
               step.progress.artifactTableNamespace ??
@@ -222,13 +223,18 @@ function buildSnapshotFromLedger(
       ...(step.progress?.nodeIo ? { nodeIo: step.progress.nodeIo } : {}),
     }));
   const liveStatus = normalizePlayRunLiveStatus(snapshot.status);
-  // Only surface the row-outcome aggregate once the run is terminal and it
-  // actually observed row/map steps — mid-flight `failed` counts churn, and a
-  // no-map play has no meaningful row outcome to report.
+  // Only surface the aggregate once terminal: live `failed` counts churn.
+  // Prefer the runner's terminal summary when available (it survives detached
+  // checkpoint omission), falling back to the reconciled step progress.
+  const terminalRowOutcomes = isTerminalPlayRunLiveStatus(liveStatus)
+    ? summarizeRunRowOutcomes(snapshot)
+    : null;
   const rowOutcomes =
-    isTerminalPlayRunLiveStatus(liveStatus) &&
-    Object.keys(snapshot.stepsById).length > 0
-      ? summarizeRunRowOutcomes(snapshot)
+    terminalRowOutcomes &&
+    (Object.keys(snapshot.stepsById).length > 0 ||
+      terminalRowOutcomes.totalRows > 0 ||
+      (terminalRowOutcomes.supersededRows ?? 0) > 0)
+      ? terminalRowOutcomes
       : null;
   return {
     runId: snapshot.runId,

package/dist/bundling-sources/shared_libs/play-runtime/runner-app/index.ts

@@ -1831,6 +1831,55 @@ function terminalLogsWithPhaseSummary(ctx: {
   ];
 }
 
+function rowOutcomesFromCheckpoint(checkpoint: {
+  mapFrames?: Record<
+    string,
+    {
+      completedRowsCount?: number;
+      completedRowKeys?: string[];
+      failedRowsCount?: number;
+      totalRows?: number;
+      supersededRows?: number;
+    }
+  >;
+}): {
+  completedRows: number;
+  failedRows: number;
+  totalRows: number;
+  supersededRows?: number;
+} | null {
+  const frames = Object.values(checkpoint.mapFrames ?? {});
+  if (frames.length === 0) return null;
+  let completedRows = 0;
+  let failedRows = 0;
+  let totalRows = 0;
+  let supersededRows = 0;
+  for (const frame of frames) {
+    const completed = Number.isFinite(frame.completedRowsCount)
+      ? Math.max(0, Math.floor(frame.completedRowsCount ?? 0))
+      : Math.max(0, frame.completedRowKeys?.length ?? 0);
+    const failed = Number.isFinite(frame.failedRowsCount)
+      ? Math.max(0, Math.floor(frame.failedRowsCount ?? 0))
+      : 0;
+    const superseded = Number.isFinite(frame.supersededRows)
+      ? Math.max(0, Math.floor(frame.supersededRows ?? 0))
+      : 0;
+    completedRows += completed;
+    failedRows += failed;
+    supersededRows += superseded;
+    totalRows +=
+      Number.isFinite(frame.totalRows) && (frame.totalRows ?? 0) >= 0
+        ? Math.floor(frame.totalRows ?? 0)
+        : completed + failed + superseded;
+  }
+  return {
+    completedRows,
+    failedRows,
+    totalRows,
+    supersededRows,
+  };
+}
+
 async function run(
   config: PlayRunnerExecutionConfig,
   options?: ExecutePlayRunnerOptions,
@@ -3125,6 +3174,8 @@ async function run(
           ]),
       ).values(),
     ).slice(0, 16);
+    const checkpoint = ctx.getCheckpoint();
+    const rowOutcomes = rowOutcomesFromCheckpoint(checkpoint);
 
     return {
       status: 'completed' as const,
@@ -3135,9 +3186,10 @@ async function run(
       outputRowCount,
       logs,
       ...(runtimeDiagnostics.length > 0 ? { runtimeDiagnostics } : {}),
+      ...(rowOutcomes ? { rowOutcomes } : {}),
       stats: ctx.getStats(),
       steps: ctx.getSteps(),
-      checkpoint: ctx.getCheckpoint(),
+      checkpoint,
       tableNamespace: resultTableNamespace,
       totalRows,
       inserted,
@@ -3215,14 +3267,17 @@ async function run(
     ensureSourceMapSupport();
     const failure = normalizePlayRunFailure(error);
     logRecovery();
+    const checkpoint = ctx.getCheckpoint();
+    const rowOutcomes = rowOutcomesFromCheckpoint(checkpoint);
     return {
       status: 'failed',
       error: formatRunnerFailure(error),
       errors: [failure],
       logs: terminalLogsWithPhaseSummary(ctx),
+      ...(rowOutcomes ? { rowOutcomes } : {}),
       stats: ctx.getStats(),
       steps: ctx.getSteps(),
-      checkpoint: ctx.getCheckpoint(),
+      checkpoint,
       tableNamespace: null,
       totalRows,
       inserted,

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/postgres-progress.ts

@@ -159,10 +159,14 @@ function resolveDatasetNodeRefFromTableNamespace(
 function rowsProcessedMessage(
   completed: number,
   total: number | undefined,
+  supersededRows = 0,
 ): string | undefined {
-  return total !== undefined && total > 0
-    ? `${Math.max(0, completed).toLocaleString()} / ${total.toLocaleString()} rows processed`
-    : undefined;
+  if (total === undefined || total <= 0) return undefined;
+  const skipped = Math.max(0, supersededRows);
+  const base = `${Math.max(0, completed).toLocaleString()} / ${total.toLocaleString()} rows processed`;
+  return skipped > 0
+    ? `${base}; ${skipped.toLocaleString()} skipped because a newer Runtime Sheet write took precedence`
+    : base;
 }
 
 function callsInFlightMessage(input: {
@@ -597,6 +601,9 @@ export function createPostgresSchedulerProgressReporter(input: {
         ...(current.completedRows !== undefined
           ? { completedRows: current.completedRows }
           : {}),
+        ...(current.supersededRows !== undefined
+          ? { supersededRows: current.supersededRows }
+          : {}),
         ...(current.message !== undefined ? { message: current.message } : {}),
         ...(current.artifactTableNamespace !== undefined
           ? { artifactTableNamespace: current.artifactTableNamespace }
@@ -625,6 +632,9 @@ export function createPostgresSchedulerProgressReporter(input: {
         ...(patch.completedRows !== undefined
           ? { completedRows: patch.completedRows }
           : {}),
+        ...(patch.supersededRows !== undefined
+          ? { supersededRows: patch.supersededRows }
+          : {}),
         ...(patch.message !== undefined ? { message: patch.message } : {}),
         ...(patch.artifactTableNamespace !== undefined
           ? { artifactTableNamespace: patch.artifactTableNamespace }
@@ -926,25 +936,40 @@ export function createPostgresSchedulerProgressReporter(input: {
         completed: event.completedRows,
         failed: 0,
         total: eventTotalRows,
-        startedRows: event.completedRows,
+        startedRows: event.completedRows + (event.supersededRows ?? 0),
         activeRows: 0,
         waitingRows:
           typeof eventTotalRows === 'number'
-            ? Math.max(0, eventTotalRows - event.completedRows)
+            ? Math.max(
+                0,
+                eventTotalRows -
+                  event.completedRows -
+                  (event.supersededRows ?? 0),
+              )
             : undefined,
         completedRows: event.completedRows,
+        ...(event.supersededRows !== undefined
+          ? { supersededRows: event.supersededRows }
+          : {}),
         artifactTableNamespace: event.artifactTableNamespace,
         startedAt: Date.now(),
         message:
           event.type === 'map.preparing'
             ? 'Preparing durable table...'
-            : rowsProcessedMessage(event.completedRows, eventTotalRows ?? 0),
+            : rowsProcessedMessage(
+                event.completedRows,
+                eventTotalRows ?? 0,
+                event.supersededRows,
+              ),
       });
       return;
     }
     if (event.type === 'map.progress') {
       const current = liveNodeProgress[nodeId] ?? {};
-      const settled = Math.max(0, event.completedRows + event.failedRows);
+      const settled = Math.max(
+        0,
+        event.completedRows + event.failedRows + (event.supersededRows ?? 0),
+      );
       const progressTotalRows = Math.max(
         typeof event.totalRows === 'number' && Number.isFinite(event.totalRows)
           ? event.totalRows
@@ -964,8 +989,15 @@ export function createPostgresSchedulerProgressReporter(input: {
             ? Math.max(0, progressTotalRows - startedRows)
             : undefined,
         completedRows: event.completedRows,
+        ...(event.supersededRows !== undefined
+          ? { supersededRows: event.supersededRows }
+          : {}),
         artifactTableNamespace: event.artifactTableNamespace,
-        message: rowsProcessedMessage(event.completedRows, progressTotalRows),
+        message: rowsProcessedMessage(
+          event.completedRows,
+          progressTotalRows,
+          event.supersededRows,
+        ),
       });
       return;
     }
@@ -975,7 +1007,10 @@ export function createPostgresSchedulerProgressReporter(input: {
       } else {
         stepLifecycle.onMapCompleted(nodeId);
       }
-      const processedRows = Math.max(0, event.completedRows + event.failedRows);
+      const processedRows = Math.max(
+        0,
+        event.completedRows + event.failedRows + (event.supersededRows ?? 0),
+      );
       const terminalTotal =
         typeof event.totalRows === 'number' && Number.isFinite(event.totalRows)
           ? event.totalRows
@@ -991,9 +1026,16 @@ export function createPostgresSchedulerProgressReporter(input: {
         activeRows: 0,
         waitingRows: 0,
         completedRows: event.completedRows,
+        ...(event.supersededRows !== undefined
+          ? { supersededRows: event.supersededRows }
+          : {}),
         artifactTableNamespace: event.artifactTableNamespace,
         completedAt: Date.now(),
-        message: rowsProcessedMessage(event.completedRows, event.totalRows),
+        message: rowsProcessedMessage(
+          event.completedRows,
+          event.totalRows,
+          event.supersededRows,
+        ),
       });
       activeMapNodeId = null;
       return;
@@ -1151,12 +1193,19 @@ export function createPostgresSchedulerProgressReporter(input: {
         activeRows: 0,
         waitingRows: 0,
         completedRows: completed,
+        ...(frame.supersededRows !== undefined
+          ? { supersededRows: Math.max(0, frame.supersededRows) }
+          : {}),
         artifactTableNamespace:
           frame.artifactTableNamespace ||
           existing.artifactTableNamespace ||
           undefined,
         completedAt: existing.completedAt ?? Date.now(),
-        message: rowsProcessedMessage(completed, total > 0 ? total : undefined),
+        message: rowsProcessedMessage(
+          completed,
+          total > 0 ? total : undefined,
+          frame.supersededRows ?? existing.supersededRows ?? 0,
+        ),
       });
     }
     liveNodeProgressDirty = true;
@@ -1199,18 +1248,22 @@ export function createPostgresSchedulerProgressReporter(input: {
       if (!nodeRef) continue;
       const completed = Math.max(0, Math.floor(outcome.completed) || 0);
       const failed = Math.max(0, Math.floor(outcome.failed) || 0);
-      const total =
+      const existing = liveNodeProgress[nodeRef.nodeId] ?? {};
+      const supersededRows = Math.max(0, existing.supersededRows ?? 0);
+      const sheetTotal =
         Number.isFinite(outcome.total) && outcome.total > 0
           ? Math.floor(outcome.total)
           : completed + failed;
-      if (total <= 0 && completed <= 0 && failed <= 0) continue;
-      const existing = liveNodeProgress[nodeRef.nodeId] ?? {};
+      const total = Math.max(sheetTotal, completed + failed + supersededRows);
+      if (total <= 0 && completed <= 0 && failed <= 0 && supersededRows <= 0) {
+        continue;
+      }
       const now = Date.now();
       setNodeProgress(nodeRef.nodeId, {
         completed,
         failed,
         total: total > 0 ? total : undefined,
-        startedRows: total > 0 ? total : completed + failed,
+        startedRows: total > 0 ? total : completed + failed + supersededRows,
         activeRows: 0,
         waitingRows: 0,
         completedRows: completed,
@@ -1218,7 +1271,11 @@ export function createPostgresSchedulerProgressReporter(input: {
           existing.artifactTableNamespace ?? nodeRef.artifactTableNamespace,
         startedAt: existing.startedAt ?? now,
         completedAt: existing.completedAt ?? now,
-        message: rowsProcessedMessage(completed, total > 0 ? total : undefined),
+        message: rowsProcessedMessage(
+          completed,
+          total > 0 ? total : undefined,
+          existing.supersededRows ?? 0,
+        ),
       });
     }
     liveNodeProgressDirty = true;