deepline 0.3.314 → 0.3.316

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

@@ -1,4 +1,8 @@
 import { RUN_EVENT_KIND } from './run-event-catalog';
+import {
+  MapExecutionFrameStore,
+  MapExecutionVisibility,
+} from './map-execution-frame';
 /**
  * PlayContextImpl — the cloud execution engine.
  *
@@ -477,6 +481,7 @@ import {
 } from './step-program-dataset-builder';
 import {
   createRuntimeSheetDatasetPageReader,
+  readRuntimeSheetDatasetRowKeys,
   RuntimeSheetAttemptSupersededError,
 } from './runtime-api';
 import { executionGatewayDecodedBodyBytes } from './execution-gateway-response-size';
@@ -553,19 +558,11 @@ const authoredStepContext = new AsyncLocalStorage<{
 const toolExecutionOverrides = new AsyncLocalStorage<{ force: boolean }>();
 const PROGRESS_HEARTBEAT_INTERVAL_MS = 1_000;
 const PURE_JS_HEARTBEAT_ROW_INTERVAL = 250;
-/**
- * How often map-frame checkpoint state is materialized (array spread + frame
- * clone) and a map.progress event is emitted during row execution. Per-row
- * materialization is O(rows²) in total copies and floods event consumers; a
- * row/time throttle keeps progress fresh while staying O(rows).
- */
-const MAP_FRAME_FLUSH_ROW_INTERVAL = 100;
 /** Executed-row sheet persistence chunking: rows AND bytes, whichever first. */
 const MAP_PERSIST_CHUNK_ROWS = 2_000;
 const MAP_PERSIST_CHUNK_BYTES = 8 * 1024 * 1024;
 const MAP_ROW_WRITER_BUFFER_BYTES = 16 * 1024 * 1024;
 const MAP_ROW_WRITER_MAX_FLUSH_MS = 1_000;
-const MAP_FRAME_FLUSH_INTERVAL_MS = 250;
 const MAP_STALL_LOG_INTERVAL_MS = 60_000;
 // Once the persistence latch has tripped, nothing a map is still waiting on can
 // change its outcome: the map fails and the run ends. What the wait can still
@@ -2040,17 +2037,23 @@ type FieldMapRunResult = {
   completedRowCount: number;
   failedRowCount: number;
   failureSamples: Array<{ rowLabel: string; error: string }>;
-  previewRows: Record<string, unknown>[];
+  previewRows: Array<Pick<PersistableMapRow, 'key' | 'data'>>;
   retainedRowsComplete: boolean;
 };
 
 const MAP_FAILURE_SAMPLE_LIMIT = 3;
 
 type RuntimeMapRowPersistence = {
+  /** Accepted-write visibility shared by every pool using this map's writer. */
+  visibility: MapExecutionVisibility;
   persistRows: (rows: PersistableMapRow[]) => {
     admitted: Promise<void>;
     committed: Promise<void>;
   };
+  /** Register the pool's single observer before admitting terminal writes. */
+  observeCommittedRows: (
+    observer: (rows: readonly PersistableMapRow[]) => void,
+  ) => void;
   isPersisted: (row: PersistableMapRow) => boolean;
   checkpoint: (updates: PlayRowUpdate[]) => Promise<void>;
   flush: () => Promise<void>;
@@ -2059,6 +2062,7 @@ type RuntimeMapRowPersistence = {
 
 function createRuntimeMapRowPersistence(
   persistRows: (rows: PersistableMapRow[]) => Promise<void>,
+  visibility: MapExecutionVisibility,
   options?: {
     prepareTerminalRow?: (row: PersistableMapRow) => PersistableMapRow;
     persistCheckpoint?: (updates: PlayRowUpdate[]) => Promise<void>;
@@ -2075,6 +2079,8 @@ function createRuntimeMapRowPersistence(
 ): RuntimeMapRowPersistence {
   const persisted = new Set<string>();
   const queued = new Set<string>();
+  let committedObserver: ((rows: readonly PersistableMapRow[]) => void) | null =
+    null;
   const writer = new RuntimeSheetRowWriter<PersistableMapRow, PlayRowUpdate>({
     terminalKey: (row) => {
       const identity = persistableMapRowIdentity(row);
@@ -2106,6 +2112,9 @@ function createRuntimeMapRowPersistence(
     writeBatch: async (batch) => {
       if (batch.kind === 'terminal') {
         await persistRows([...batch.rows]);
+        // Latest-view corrections describe this entire committed batch. Publish
+        // its outcomes together, before separate per-row promise continuations.
+        committedObserver?.(batch.rows);
         return { committed: batch.rows.length };
       }
       if (batch.updates.length > 0) {
@@ -2121,6 +2130,7 @@ function createRuntimeMapRowPersistence(
   if (latch?.tripped) writer.fail(runtimePersistenceLatchCauseError(latch));
 
   return {
+    visibility,
     persistRows: (rows) => {
       const admissions: Promise<void>[] = [];
       const commits: Promise<void>[] = [];
@@ -2165,6 +2175,13 @@ function createRuntimeMapRowPersistence(
         committed: Promise.all(commits).then(() => {}),
       };
     },
+    observeCommittedRows: (observer) => {
+      if (committedObserver)
+        throw new Error(
+          'Runtime map writer already has a committed-row observer.',
+        );
+      committedObserver = observer;
+    },
     isPersisted: (row) => {
       const identity = persistableMapRowIdentity(row);
       return identity ? persisted.has(identity) : false;
@@ -2585,25 +2602,6 @@ function emptyCheckpoint(): PlayCheckpoint {
   };
 }
 
-function cloneMapFrame(frame: MapExecutionFrame): MapExecutionFrame {
-  return {
-    ...frame,
-    completedRowKeys: [...frame.completedRowKeys],
-    pendingRowKeys: [...frame.pendingRowKeys],
-    ...(frame.suspendedInputRows
-      ? {
-          suspendedInputRows: frame.suspendedInputRows.map((row) => ({
-            inputIndex: row.inputIndex,
-            data: cloneCsvAliasedRow(row.data),
-            ...(row.authoredInputDigest
-              ? { authoredInputDigest: row.authoredInputDigest }
-              : {}),
-          })),
-        }
-      : {}),
-  };
-}
-
 /**
  * Adapt this runtime's per-tool queue hints into the Play Execution Governor's
  * pacing resolver. The Governor owns per-(org, provider) pacing; this only maps
@@ -2745,6 +2743,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   >();
   private readonly ctxFetchHttpFailureDiagnosticIdentities = new Set<string>();
   private checkpoint: PlayCheckpoint;
+  private readonly mapFrames: MapExecutionFrameStore;
   /**
    * A durable boundary is a control-flow handoff, not a customer-catchable
    * business failure. Keep it on the context as the source of truth so a
@@ -3259,6 +3258,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     };
     this.#options = options;
     this.checkpoint = options.checkpoint ?? emptyCheckpoint();
+    this.mapFrames = new MapExecutionFrameStore(this.checkpoint, (event) =>
+      this.emitExecutionEvent(event),
+    );
     const checkpointCacheEpochMs = this.checkpoint.durableCallCacheEpochMs;
     this.durableCallCacheEpochMs =
       typeof checkpointCacheEpochMs === 'number' &&
@@ -4310,10 +4312,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   }
 
   private setMapFrame(frame: MapExecutionFrame): void {
-    this.checkpoint.mapFrames = {
-      ...(this.checkpoint.mapFrames ?? {}),
-      [frame.mapInvocationId]: cloneMapFrame(frame),
-    };
+    this.mapFrames.set(frame);
   }
 
   private createMapExecutionScope(input: {
@@ -8180,52 +8179,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         : derivePlayRowIdentity(stableInputRow(row), resolvedTableNamespace);
     };
 
-    // A terminal write can be durably accepted into this run's history while
-    // losing the mutable latest-view race to newer intent. That outcome must
-    // not leak into the dataset returned by this execution. A later same-run
-    // reconciliation can explicitly recover a key; only that positive fact
-    // makes it visible again.
-    const staleCompletionKeys = new Set<string>();
-    const staleCompletedKeys = new Set<string>();
-    const staleFailedKeys = new Set<string>();
-    const recoveredStaleCompletionKeys = new Set<string>();
-    const observeMapWriteResult = (
-      writeResult: unknown,
-      writtenRows: readonly PersistableMapRow[] = [],
-    ): void => {
-      if (!writeResult || typeof writeResult !== 'object') return;
-      const result = writeResult as {
-        staleDroppedKeys?: unknown;
-        recoveredStaleKeys?: unknown;
-      };
-      const rowsByKey = new Map(writtenRows.map((row) => [row.key, row]));
-      if (Array.isArray(result.staleDroppedKeys)) {
-        for (const key of result.staleDroppedKeys) {
-          if (typeof key !== 'string' || !key) continue;
-          staleCompletionKeys.add(key);
-          if (rowsByKey.get(key)?.status === 'failed') {
-            staleFailedKeys.add(key);
-            staleCompletedKeys.delete(key);
-          } else {
-            staleCompletedKeys.add(key);
-            staleFailedKeys.delete(key);
-          }
-        }
-      }
-      if (Array.isArray(result.recoveredStaleKeys)) {
-        for (const key of result.recoveredStaleKeys) {
-          if (typeof key !== 'string' || !key) continue;
-          recoveredStaleCompletionKeys.add(key);
-          staleCompletionKeys.delete(key);
-          staleCompletedKeys.delete(key);
-          staleFailedKeys.delete(key);
-        }
-      }
-    };
-    const isVisibleTerminalRow = (row: PersistableMapRow): boolean =>
-      !staleCompletionKeys.has(row.key) ||
-      recoveredStaleCompletionKeys.has(row.key);
-
     // Identity for SEED rows (pre-execution raw inputs), matching the server's
     // own derivation in startRuntimeSheetDataset: hash the FULL cleaned input
     // row, output-named columns INCLUDED. Two distinct input rows that differ
@@ -8292,19 +8245,52 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     // Completed siblings require either the Runtime Sheet or a complete
     // authored replay. Never return only the pending subset as a full result.
     const replayWithoutSheet = Boolean(
-      suspendedInputRows?.length && !canReadPersistedMapResults,
+      suspendedInputRows !== null && !canReadPersistedMapResults,
     );
     const resumedPendingRowsOnly = Boolean(
-      suspendedInputRows?.length &&
+      suspendedInputRows !== null &&
       (canReadPersistedMapResults ||
         (replayMapFrame?.completedRowKeys.length ?? 0) === 0),
     );
-    const previouslyCompletedRowKeys = resumedPendingRowsOnly
-      ? (replayMapFrame?.completedRowKeys ?? [])
-      : [];
     const previouslyFailedRowsCount = resumedPendingRowsOnly
       ? (replayMapFrame?.failedRowsCount ?? 0)
       : 0;
+    const {
+      completedRowKeys: previouslyCompletedRowKeys,
+      completedRowsCount: previouslyCompletedRowsCount,
+      reusedRowsCount: previouslyReusedRowsCount,
+    } = resumedPendingRowsOnly
+      ? await this.mapFrames.restoreCompletedRows(
+          replayMapFrame!,
+          canReadPersistedMapResults
+            ? async (keys) => {
+                const result = await readRuntimeSheetDatasetRowKeys(
+                  {
+                    baseUrl: this.#options.baseUrl!,
+                    executorToken: this.#options.executorToken!,
+                    dbSessionStrategy: this.#options.dbSessionStrategy,
+                    playName: this.#options.playName!,
+                    userEmail: this.#options.userEmail,
+                    runId: this.#options.runId!,
+                  },
+                  {
+                    tableNamespace: replayMapFrame!.artifactTableNamespace,
+                    runId: this.#options.runId!,
+                    keys,
+                    rowMode: 'output',
+                  },
+                );
+                return result.keys;
+              }
+            : undefined,
+          MAP_PERSIST_CHUNK_ROWS,
+        )
+      : { completedRowKeys: [], completedRowsCount: 0, reusedRowsCount: 0 };
+    const visibility = new MapExecutionVisibility(
+      resumedPendingRowsOnly ? (replayMapFrame?.supersededRows ?? 0) : 0,
+    );
+    const isVisibleTerminalRow = (row: PersistableMapRow): boolean =>
+      visibility.isVisible(row.key);
     if (shouldStreamRuntimeBackedDataset) {
       // Net-new admission happens one source page at a time. Its progress and
       // returned dataset describe admitted rows, not every provider/CSV row
@@ -8402,28 +8388,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               ),
               staticPipeline: this.currentStaticPipeline ?? null,
             });
-            observeMapWriteResult(writeResult, chunk);
-            const supersededKeys =
-              typeof writeResult === 'object' && writeResult !== null
-                ? (writeResult.supersededKeys ?? [])
-                : [];
-            if (supersededKeys.length > 0) {
-              // The sheet rows belong to a different write version: this
-              // attempt has been superseded and nothing it persists from here
-              // on can be accepted. Fail the map (and trip the latch below)
-              // instead of spending provider calls on rows that are dropped.
-              throw new RuntimeSheetAttemptSupersededError({
-                tableNamespace: resolvedTableNamespace,
-                runId: this.currentRunId,
-                writeVersionValue: null,
-                submittedRows: chunk.length,
-                supersededRows: supersededKeys.map((key) => ({
-                  key,
-                  reason: 'unreported' as const,
-                  rowVersionStamp: null,
-                })),
-              });
-            }
+            visibility.recordAcceptedWrite(writeResult, chunk, {
+              tableNamespace: resolvedTableNamespace,
+              runId: this.currentRunId,
+            });
             this.resourceGovernor.observe({
               sheetFlushBytes: chunkBytes,
               sheetFlushLatencyMs: Date.now() - flushStartedAt,
@@ -8601,6 +8569,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       }): Promise<void> => {
         const incrementalPersistence = createRuntimeMapRowPersistence(
           persistMapRows,
+          visibility,
           {
             prepareTerminalRow: (row) =>
               this.withPendingMapRowData(row, resolvedTableNamespace),
@@ -8624,6 +8593,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
         this.beginActiveMapCellMeta();
         this.beginActiveMapCheckpointUpdates();
+        const settledBeforePool = visibility.settlement(
+          processedCount - failedCount,
+          failedCount,
+        );
         this.setMapFrame({
           mapInvocationId: mapScope.mapInvocationId,
           mapNodeId: mapScope.mapNodeId ?? null,
@@ -8633,13 +8606,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           totalRows: totalInputCount,
           completedRowKeys: [],
           pendingRowKeys: execution.rowFeed ? [] : [...execution.rowKeys],
-          completedRowsCount: Math.max(
-            0,
-            processedCount - failedCount - staleCompletedKeys.size,
-          ),
+          completedRowsCount: settledBeforePool.completedRows,
           pendingRowsCount: Math.max(0, totalInputCount - processedCount),
-          failedRowsCount: Math.max(0, failedCount - staleFailedKeys.size),
-          supersededRows: staleCompletedKeys.size + staleFailedKeys.size,
+          failedRowsCount: settledBeforePool.failedRows,
+          supersededRows: visibility.supersededRows,
           startedAt:
             this.checkpoint.mapFrames?.[mapScope.mapInvocationId]?.startedAt ??
             Date.now(),
@@ -8662,15 +8632,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               onRowError: options?.onRowError,
               executionRowKeys: execution.rowKeys,
               executionRowIndexes: execution.rowIndexes,
-              progressCompletedOffset: () =>
-                Math.max(
-                  0,
-                  processedCount - failedCount - staleCompletedKeys.size,
-                ),
-              progressFailedOffset: () =>
-                Math.max(0, failedCount - staleFailedKeys.size),
-              progressSupersededOffset: () =>
-                staleCompletedKeys.size + staleFailedKeys.size,
+              // Raw earlier-pool outcomes; the writer owns visibility facts.
+              progressCompletedOffset: () => processedCount - failedCount,
+              progressFailedOffset: () => failedCount,
               progressSkippedOffset: () => duplicateReuseCount,
               progressTotalRows: () => totalInputCount,
               rowFeed: execution.rowFeed,
@@ -8698,13 +8662,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         }
 
         await incrementalPersistence.flush();
-        const visibleCompletedRows =
-          mapResult.completedRows.filter(isVisibleTerminalRow);
-        const visibleFailedRows =
-          mapResult.failedRows.filter(isVisibleTerminalRow);
         const mapCellMeta = this.activeMapCellMeta;
         const persistRows: PersistableMapRow[] = [];
-        for (const row of visibleCompletedRows) {
+        for (const row of mapResult.completedRows) {
           if (incrementalPersistence.isPersisted(row)) continue;
           const meta = mapCellMeta?.get(row.key);
           persistRows.push(
@@ -8720,16 +8680,19 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           );
         }
         persistRows.push(
-          ...visibleFailedRows.filter(
+          ...mapResult.failedRows.filter(
             (row) => !incrementalPersistence.isPersisted(row),
           ),
         );
         await persistMapRows(persistRows);
+        const visibleCompletedRows =
+          mapResult.completedRows.filter(isVisibleTerminalRow);
         this.clearActiveMapCellMeta();
         this.clearActiveMapCheckpointUpdates();
 
-        for (const materializedRow of mapResult.previewRows) {
-          if (previewRows.length < 5) previewRows.push(materializedRow);
+        for (const row of mapResult.previewRows) {
+          if (previewRows.length < 5 && isVisibleTerminalRow(row))
+            previewRows.push(this.toMaterializedOutputRow(row.data));
         }
         if (!mapResult.retainedRowsComplete) {
           disableImmediateMaterializedCache(
@@ -8877,8 +8840,16 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         }
       }
 
-      successfulCount = Math.max(0, successfulCount - staleCompletedKeys.size);
-      failedCount = Math.max(0, failedCount - staleFailedKeys.size);
+      const terminalProgress = visibility.settlement(
+        processedCount - failedCount,
+        failedCount,
+      );
+      const visibleResults = visibility.settlement(
+        successfulCount,
+        failedCount,
+      );
+      successfulCount = visibleResults.completedRows;
+      failedCount = visibleResults.failedRows;
       this.#options.onMapRowsSettled?.({
         playName: this.#options.playName,
         runId: this.#options.runId,
@@ -8904,7 +8875,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           completedRowsCount: completedRows,
           pendingRowsCount: 0,
           failedRowsCount: failedCount,
-          supersededRows: staleCompletedKeys.size + staleFailedKeys.size,
+          supersededRows: visibility.supersededRows,
           startedAt:
             this.checkpoint.mapFrames?.[mapScope.mapInvocationId]?.startedAt ??
             Date.now(),
@@ -8919,7 +8890,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           completedRows,
           failedRows: failedCount,
           totalRows: totalInputCount,
-          supersededRows: staleCompletedKeys.size + staleFailedKeys.size,
+          supersededRows: visibility.supersededRows,
           at: Date.now(),
         });
         throw new AllAdmittedRowsFailedError({
@@ -8939,16 +8910,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         totalRows: totalInputCount,
         completedRowKeys: [],
         pendingRowKeys: [],
-        completedRowsCount: Math.max(
-          0,
-          processedCount -
-            failedCount -
-            staleFailedKeys.size -
-            staleCompletedKeys.size,
-        ),
+        completedRowsCount: terminalProgress.completedRows,
         pendingRowsCount: 0,
         failedRowsCount: failedCount,
-        supersededRows: staleCompletedKeys.size + staleFailedKeys.size,
+        supersededRows: visibility.supersededRows,
         startedAt:
           this.checkpoint.mapFrames?.[mapScope.mapInvocationId]?.startedAt ??
           Date.now(),
@@ -8960,16 +8925,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         mapNodeId: mapScope.mapNodeId ?? null,
         logicalNamespace: mapScope.logicalNamespace,
         artifactTableNamespace: resolvedTableNamespace,
-        completedRows: Math.max(
-          0,
-          processedCount -
-            failedCount -
-            staleFailedKeys.size -
-            staleCompletedKeys.size,
-        ),
+        completedRows: terminalProgress.completedRows,
         failedRows: failedCount,
         totalRows: totalInputCount,
-        supersededRows: staleCompletedKeys.size + staleFailedKeys.size,
+        supersededRows: visibility.supersededRows,
         at: Date.now(),
       });
 
@@ -9373,6 +9332,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 )
               : row,
             index,
+            originalIndex: itemOriginalIndexes[index] ?? index,
           };
         });
       const admittedItems =
@@ -9383,7 +9343,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           : seededItems;
       rawItems = admittedItems.map((item) => item.row);
       itemsToProcess = admittedItems.map((item) => item.row);
-      itemOriginalIndexes = admittedItems.map((item) => item.index);
+      itemOriginalIndexes = admittedItems.map((item) => item.originalIndex);
       totalInputCount = resumedPendingRowsOnly
         ? Math.max(replayMapFrame?.totalRows ?? 0, admittedItems.length)
         : admittedItems.length;
@@ -9399,6 +9359,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       rowIdentity(this.toOutputRow(item), itemOriginalIndexes[index] ?? index),
     );
     this.setMapFrame({
+      ...(resumedPendingRowsOnly ? replayMapFrame : undefined),
       mapInvocationId: mapScope.mapInvocationId,
       mapNodeId: mapScope.mapNodeId ?? null,
       logicalNamespace: mapScope.logicalNamespace,
@@ -9407,7 +9368,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       totalRows: totalInputCount,
       completedRowKeys,
       pendingRowKeys,
+      completedRowsCount: previouslyCompletedRowsCount,
       failedRowsCount: previouslyFailedRowsCount,
+      supersededRows: visibility.supersededRows,
+      activeBoundaryId: null,
       startedAt: resumedPendingRowsOnly
         ? (replayMapFrame?.startedAt ?? Date.now())
         : Date.now(),
@@ -9420,8 +9384,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       logicalNamespace: mapScope.logicalNamespace,
       artifactTableNamespace: mapScope.artifactTableNamespace,
       totalRows: totalInputCount,
-      completedRows: completedRowKeys.length,
+      completedRows: previouslyCompletedRowsCount,
+      failedRows: previouslyFailedRowsCount,
       pendingRows: pendingRowKeys.length,
+      supersededRows: visibility.supersededRows,
       at: Date.now(),
     });
 
@@ -9479,7 +9445,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             ),
             staticPipeline: this.currentStaticPipeline ?? null,
           });
-          observeMapWriteResult(writeResult, chunk);
+          visibility.recordAcceptedWrite(writeResult, chunk, {
+            tableNamespace: resolvedTableNamespace,
+            runId: this.currentRunId,
+          });
           this.resourceGovernor.observe({
             sheetFlushBytes: chunkBytes,
             sheetFlushLatencyMs: Date.now() - flushStartedAt,
@@ -9507,7 +9476,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       await flushChunk();
     };
     const incrementalPersistence = this.#options.onMapRowsCompleted
-      ? createRuntimeMapRowPersistence(persistMapRows, {
+      ? createRuntimeMapRowPersistence(persistMapRows, visibility, {
           prepareTerminalRow: (row) =>
             this.withPendingMapRowData(row, resolvedTableNamespace),
           persistCheckpoint: this.#options.onMapRowsCheckpoint
@@ -9556,6 +9525,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             : {}),
           retainedRowsMemoryBudgetBytes:
             mapMemoryLimits.materializedBudgetBytes,
+          progressCompletedOffset:
+            previouslyReusedRowsCount + duplicateReuseCount,
           progressFailedOffset: previouslyFailedRowsCount,
           incrementalPersistence,
         },
@@ -9576,6 +9547,41 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         this.clearActiveMapCheckpointUpdates();
       }
     }
+    // Persist executed rows to the tenant runtime sheet — the sheet is the
+    // source of truth, not this in-memory results array. Chunked by rows AND
+    // bytes so large cells (scraped pages) never produce oversized writes.
+    if (mapResult.completedRows.length > 0 || mapResult.failedRows.length > 0) {
+      await incrementalPersistence?.flush();
+      const mapCellMeta = this.activeMapCellMeta;
+      const persistRows: PersistableMapRow[] = [];
+      for (const row of mapResult.completedRows) {
+        if (incrementalPersistence?.isPersisted(row)) continue;
+        const rowKey = row.key;
+        const meta = mapCellMeta?.get(rowKey);
+        persistRows.push(
+          completedMapRowOutcome({
+            key: rowKey,
+            data: row.data,
+            cellMetaPatch: {
+              ...(row.cellMetaPatch ?? {}),
+              ...(meta ?? {}),
+            },
+          }),
+        );
+      }
+      persistRows.push(
+        ...mapResult.failedRows.filter(
+          (row) => !incrementalPersistence?.isPersisted(row),
+        ),
+      );
+      const persistStartedAt = Date.now();
+      await persistMapRows(persistRows);
+      if (persistRows.length > 0) {
+        this.runtimeLog(
+          `Persisted ${persistRows.length} executed rows to sheet ${resolvedTableNamespace} in ${Date.now() - persistStartedAt}ms`,
+        );
+      }
+    }
     const visibleCompletedRows =
       mapResult.completedRows.filter(isVisibleTerminalRow);
     const visibleFailedRows = mapResult.failedRows.filter(isVisibleTerminalRow);
@@ -9597,9 +9603,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             const rowKey = rowIdentity(rawItem, index);
             if (
               rowKey &&
-              (failedRowKeys.has(rowKey) ||
-                (staleCompletionKeys.has(rowKey) &&
-                  !recoveredStaleCompletionKeys.has(rowKey)))
+              (failedRowKeys.has(rowKey) || !visibility.isVisible(rowKey))
             ) {
               return [];
             }
@@ -9613,52 +9617,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       previouslyFailedRowsCount;
     const reusedCount = duplicateReuseCount;
 
-    // Persist executed rows to the tenant runtime sheet — the sheet is the
-    // source of truth, not this in-memory results array. Chunked by rows AND
-    // bytes so large cells (scraped pages) never produce oversized writes.
-    if (resultsByKey.size > 0 || visibleFailedRows.length > 0) {
-      await incrementalPersistence?.flush();
-      const mapCellMeta = this.activeMapCellMeta;
-      const persistRows: PersistableMapRow[] = [];
-      for (const row of visibleCompletedRows) {
-        if (incrementalPersistence?.isPersisted(row)) continue;
-        const rowKey = row.key;
-        const meta = mapCellMeta?.get(rowKey);
-        persistRows.push(
-          completedMapRowOutcome({
-            key: rowKey,
-            data: row.data,
-            cellMetaPatch: {
-              ...(row.cellMetaPatch ?? {}),
-              ...(meta ?? {}),
-            },
-          }),
-        );
-      }
-      persistRows.push(
-        ...visibleFailedRows.filter(
-          (row) => !incrementalPersistence?.isPersisted(row),
-        ),
-      );
-      const persistStartedAt = Date.now();
-      await persistMapRows(persistRows);
-      if (persistRows.length > 0) {
-        this.runtimeLog(
-          `Persisted ${persistRows.length} executed rows to sheet ${resolvedTableNamespace} in ${Date.now() - persistStartedAt}ms`,
-        );
-      }
-    }
     this.clearActiveMapCellMeta();
     this.clearActiveMapCheckpointUpdates();
 
-    const durableCompletedRows = Math.max(
-      0,
-      previouslyCompletedRowKeys.length +
-        reusedCount +
-        visibleCompletedRows.length,
+    const durableProgress = visibility.settlement(
+      previouslyCompletedRowsCount + reusedCount + mapResult.completedRowCount,
+      previouslyFailedRowsCount + mapResult.failedRowCount,
     );
-    const durableFailedRows =
-      previouslyFailedRowsCount + visibleFailedRows.length;
+    const durableCompletedRows = durableProgress.completedRows;
+    const durableFailedRows = durableProgress.failedRows;
     const terminalFrame = this.checkpoint.mapFrames?.[mapScope.mapInvocationId];
     if (terminalFrame) {
       this.setMapFrame({
@@ -9667,11 +9634,14 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         // Incremental rows add keys after their commit. Pure maps use the
         // durable aggregate count below instead of materializing up to millions
         // of keys only to mark the terminal frame.
-        completedRowKeys: terminalFrame.completedRowKeys,
+        completedRowKeys: terminalFrame.completedRowKeys.filter((key) =>
+          visibility.isVisible(key),
+        ),
         pendingRowKeys: [],
         completedRowsCount: durableCompletedRows,
         pendingRowsCount: 0,
         failedRowsCount: durableFailedRows,
+        supersededRows: visibility.supersededRows,
         activeBoundaryId: null,
         suspendedInputRows: undefined,
         updatedAt: Date.now(),
@@ -9685,6 +9655,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       artifactTableNamespace: resolvedTableNamespace,
       completedRows: durableCompletedRows,
       failedRows: durableFailedRows,
+      supersededRows: visibility.supersededRows,
       totalRows: totalInputCount,
       ...this.inlineChildAggregateEventFields(),
       at: Date.now(),
@@ -9714,8 +9685,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         expectedRows: Math.max(
           0,
           totalInputCount -
-            staleCompletionKeys.size -
-            (resumedPendingRowsOnly ? durableFailedRows : 0),
+            visibility.supersededRows -
+            (resumedPendingRowsOnly
+              ? durableFailedRows + previouslyReusedRowsCount
+              : 0),
         ),
         currentRows: results,
         failedRowCount: resumedPendingRowsOnly ? 0 : visibleFailedRows.length,
@@ -9899,7 +9872,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       retainedRowsMemoryBudgetBytes?: number;
       progressCompletedOffset?: number | (() => number);
       progressFailedOffset?: number | (() => number);
-      progressSupersededOffset?: number | (() => number);
       /** Input duplicates discovered after admission; excludes resolver outcomes. */
       progressSkippedOffset?: number | (() => number);
       progressTotalRows?: number | (() => number);
@@ -9987,7 +9959,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     const failedRowsToPersist: PersistableMapRow[] = [];
     const failureSamples: Array<{ rowLabel: string; error: string }> = [];
     const failureSampleErrors = new Set<string>();
-    const previewRows: Record<string, unknown>[] = [];
+    const previewRows: Array<Pick<PersistableMapRow, 'key' | 'data'>> = [];
     let completedRowCount = 0;
     let failedRowCount = 0;
     let retainedRowsComplete = true;
@@ -10084,6 +10056,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       onCommitted: () => void,
     ): Promise<void> => {
       if (!incrementalPersistence) {
+        mapProgress.recordCommittedRows([row]);
         onCommitted();
         return Promise.resolve();
       }
@@ -10131,199 +10104,23 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     this.steps.push(datasetStep);
     this.activeDatasetStep = datasetStep;
 
-    // Live row-key sets for this map invocation, mutated in place (O(1) per
-    // row). The previous implementation rebuilt both Sets from the checkpoint
-    // arrays, re-spread them into fresh arrays, AND deep-cloned the frame on
-    // every row — O(rows²) copies that collapsed 150k-row maps to ~30 rows/s.
-    // The checkpoint frame is now materialized on a throttle (every
-    // MAP_FRAME_FLUSH_ROW_INTERVAL rows / MAP_FRAME_FLUSH_INTERVAL_MS / any
-    // status, boundary, or explicit-event transition), which only narrows how
-    // fresh the replay frame is between persisted checkpoints — re-executed
-    // rows remain idempotent via deterministic keys and reuse detection.
-    let liveFrameSets: {
-      completedRowKeys: Set<string>;
-      pendingRowKeys: Set<string>;
-      failedRowsCount: number;
-    } | null = null;
-    let lastFrameFlushAt = 0;
-    let rowsSinceFrameFlush = 0;
-    // Scalars only: resolver admission is visible before the first row's
-    // durable completion, without publishing one event per row or tool call.
-    let startedResolverRows = 0;
-    let activeResolverRows = 0;
-    let tracksResolverActivity = false;
-    // Persistence can move current resolvers between successful, failed and
-    // superseded offsets. They already contribute to startedResolverRows:
-    // only the settled baseline before this pool started belongs in admission.
-    const initiallyStartedRows =
-      liveNumber(runtimeOptions?.progressCompletedOffset, completedRows) +
-      liveNumber(runtimeOptions?.progressFailedOffset, 0) +
-      liveNumber(runtimeOptions?.progressSupersededOffset, 0);
-    const initiallySkippedRows = liveNumber(
-      runtimeOptions?.progressSkippedOffset,
-      0,
+    const mapProgress = this.mapFrames.progress(mapScope, {
+      totalRows: currentTotalRows,
+      completedOffset: runtimeOptions?.progressCompletedOffset,
+      failedOffset: runtimeOptions?.progressFailedOffset,
+      visibility:
+        incrementalPersistence?.visibility ??
+        new MapExecutionVisibility(
+          this.checkpoint.mapFrames?.[mapScope.mapInvocationId]
+            ?.supersededRows ?? 0,
+        ),
+      skippedInputs: runtimeOptions?.progressSkippedOffset,
+      checkpointRows: rowFeed ? 'counts' : 'keys',
+      eventFields: () => this.inlineChildAggregateEventFields(),
+    });
+    incrementalPersistence?.observeCommittedRows((rows) =>
+      mapProgress.recordCommittedRows(rows),
     );
-    const mapActivityCounts = () => {
-      const startedRows =
-        initiallyStartedRows +
-        (liveNumber(
-          runtimeOptions?.progressSkippedOffset,
-          initiallySkippedRows,
-        ) -
-          initiallySkippedRows) +
-        startedResolverRows;
-      return {
-        startedRows,
-        activeRows: activeResolverRows,
-        waitingRows: currentTotalRows() - startedRows,
-      };
-    };
-    const updateMapFrameProgress = (input: {
-      status?: MapExecutionFrame['status'];
-      completedRowKey?: string | null;
-      pendingRowKey?: string | null;
-      completedRowKeys?: string[];
-      activeBoundaryId?: string | null;
-      failedDelta?: number;
-      failedRowKey?: string | null;
-      pendingRowKeys?: string[];
-      emitEventType?: PlayExecutionEvent['type'];
-    }) => {
-      const existing =
-        this.checkpoint.mapFrames?.[mapScope.mapInvocationId] ?? null;
-      if (!existing) {
-        return;
-      }
-      liveFrameSets ??= {
-        completedRowKeys: new Set(existing.completedRowKeys),
-        pendingRowKeys: new Set(existing.pendingRowKeys),
-        // Failure counts are explicit row outcomes, not the complement of the
-        // live key sets. The sets may be intentionally sparse for a fed map
-        // and may lag the durable row writer while a batch is in flight.
-        failedRowsCount: 0,
-      };
-      const { completedRowKeys, pendingRowKeys } = liveFrameSets;
-      const completedBefore = completedRowKeys.size;
-      if (input.completedRowKey?.trim()) {
-        const completedRowKey = input.completedRowKey.trim();
-        completedRowKeys.add(completedRowKey);
-        pendingRowKeys.delete(completedRowKey);
-      }
-      if (input.completedRowKeys) {
-        for (const rawKey of input.completedRowKeys) {
-          const completedRowKey = rawKey.trim();
-          if (!completedRowKey) continue;
-          completedRowKeys.add(completedRowKey);
-          pendingRowKeys.delete(completedRowKey);
-        }
-      }
-      if (input.pendingRowKey?.trim()) {
-        pendingRowKeys.add(input.pendingRowKey.trim());
-      }
-      if (input.pendingRowKeys) {
-        for (const rawKey of input.pendingRowKeys) {
-          const pendingRowKey = rawKey.trim();
-          if (pendingRowKey && !completedRowKeys.has(pendingRowKey)) {
-            pendingRowKeys.add(pendingRowKey);
-          }
-        }
-      }
-      if (input.failedRowKey?.trim()) {
-        pendingRowKeys.delete(input.failedRowKey.trim());
-      }
-      liveFrameSets.failedRowsCount += Math.max(0, input.failedDelta ?? 0);
-      rowsSinceFrameFlush += completedRowKeys.size - completedBefore;
-
-      const isTransition =
-        input.status !== undefined ||
-        input.activeBoundaryId !== undefined ||
-        input.emitEventType !== undefined;
-      const now = Date.now();
-      // Small maps keep per-row progress (live UX, negligible cost); the
-      // row/time throttle only kicks in where the per-row materialization
-      // cost matters.
-      const shouldFlush =
-        isTransition ||
-        totalRows <= MAP_FRAME_FLUSH_ROW_INTERVAL ||
-        rowsSinceFrameFlush >= MAP_FRAME_FLUSH_ROW_INTERVAL ||
-        now - lastFrameFlushAt >= MAP_FRAME_FLUSH_INTERVAL_MS;
-      if (shouldFlush) {
-        lastFrameFlushAt = now;
-        rowsSinceFrameFlush = 0;
-        const nextFrame: MapExecutionFrame = {
-          ...existing,
-          status: input.status ?? existing.status,
-          // A fed map spans every source page, so its frame carries counts
-          // only: the Runtime Sheet is the durable row record, and a key list
-          // that grows with the dataset would be copied and shipped on every
-          // progress flush.
-          ...(rowFeed
-            ? {
-                completedRowKeys: [],
-                pendingRowKeys: [],
-                completedRowsCount:
-                  liveNumber(runtimeOptions?.progressCompletedOffset, 0) +
-                  completedRowKeys.size,
-                pendingRowsCount: pendingRowKeys.size,
-                failedRowsCount:
-                  liveNumber(runtimeOptions?.progressFailedOffset, 0) +
-                  liveFrameSets.failedRowsCount,
-              }
-            : {
-                completedRowKeys: [...completedRowKeys],
-                pendingRowKeys: [...pendingRowKeys],
-                failedRowsCount:
-                  liveNumber(runtimeOptions?.progressFailedOffset, 0) +
-                  liveFrameSets.failedRowsCount,
-              }),
-          supersededRows: liveNumber(
-            runtimeOptions?.progressSupersededOffset,
-            existing.supersededRows ?? 0,
-          ),
-          ...(input.activeBoundaryId !== undefined
-            ? { activeBoundaryId: input.activeBoundaryId }
-            : {}),
-          updatedAt: now,
-        };
-        this.setMapFrame(nextFrame);
-      }
-      const progressEventType =
-        input.emitEventType ??
-        (shouldFlush && completedRowKeys.size > completedBefore
-          ? 'map.progress'
-          : null);
-      if (progressEventType) {
-        const failedRows = Math.max(
-          0,
-          liveNumber(runtimeOptions?.progressFailedOffset, 0) +
-            liveFrameSets.failedRowsCount,
-        );
-        this.emitExecutionEvent({
-          type: progressEventType,
-          mapInvocationId: mapScope.mapInvocationId,
-          mapNodeId: mapScope.mapNodeId ?? null,
-          logicalNamespace: mapScope.logicalNamespace,
-          artifactTableNamespace: mapScope.artifactTableNamespace,
-          completedRows:
-            liveNumber(runtimeOptions?.progressCompletedOffset, 0) +
-            completedRowKeys.size,
-          failedRows,
-          totalRows: currentTotalRows(),
-          ...(progressEventType === 'map.progress' && tracksResolverActivity
-            ? mapActivityCounts()
-            : {}),
-          supersededRows: liveNumber(
-            runtimeOptions?.progressSupersededOffset,
-            existing.supersededRows ?? 0,
-          ),
-          // Inline child aggregates ride the single-writer progress event so
-          // fan-out never contends on a per-child mutation. See ADR 0013.
-          ...this.inlineChildAggregateEventFields(),
-          at: Date.now(),
-        } as PlayExecutionEvent);
-      }
-    };
-
     if (this.canUsePureJsMapFastPath(definition)) {
       const results = await this.runPureFieldMap(
         items,
@@ -10353,7 +10150,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       // post-hoc map.progress events and re-copying the completed-keys array
       // per row — all theater, no live progress value.
       if (!incrementalPersistence) {
-        updateMapFrameProgress({
+        mapProgress.update({
           completedRowKeys: results.map((_row, index) =>
             executionRowKey(
               this.toOutputRow(items[index] as Record<string, unknown>),
@@ -10363,7 +10160,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         });
       }
       if (emitTerminalEvent) {
-        updateMapFrameProgress({
+        mapProgress.update({
           status: 'completed',
           activeBoundaryId: null,
           emitEventType: 'map.completed',
@@ -10374,22 +10171,23 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       this.runtimeLog(
         `Map completed: ${results.length + completedRows} results (${results.length} succeeded, 0 failed, ${completedRows} duplicate keys skipped)`,
       );
+      const pureCompletedRows = results.map((row, index) =>
+        completedMapRowOutcome({
+          key: executionRowKey(
+            this.toOutputRow(items[index] as Record<string, unknown>),
+            index,
+          ),
+          inputIndex: executionRowIndex(index),
+          data: this.toPersistedOutputRow(row),
+        }),
+      );
       return {
-        completedRows: results.map((row, index) =>
-          completedMapRowOutcome({
-            key: executionRowKey(
-              this.toOutputRow(items[index] as Record<string, unknown>),
-              index,
-            ),
-            inputIndex: executionRowIndex(index),
-            data: this.toPersistedOutputRow(row),
-          }),
-        ),
+        completedRows: pureCompletedRows,
         failedRows: [],
         completedRowCount: results.length,
         failedRowCount: 0,
         failureSamples: [],
-        previewRows: results.slice(0, 5),
+        previewRows: pureCompletedRows.slice(0, 5),
         retainedRowsComplete: true,
       };
     }
@@ -10401,7 +10199,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       for (let index = fromIndex; index < toIndex; index += 1) {
         appendedKeys.push(keyForIndex(index));
       }
-      updateMapFrameProgress({ pendingRowKeys: appendedKeys });
+      mapProgress.update({ pendingRowKeys: appendedKeys });
     });
 
     // Bound on how many row resolver bodies exist at once. An explicit
@@ -10662,7 +10460,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 rowKey,
                 normalizedTableNamespace,
               );
-              updateMapFrameProgress({ failedDelta: 1, failedRowKey: rowKey });
             });
             return FAILED_ROW;
           } finally {
@@ -10753,19 +10550,18 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         });
         completedRowCount += 1;
         if (previewRows.length < 5) {
-          previewRows.push(this.toMaterializedOutputRow(completedRow.data));
+          previewRows.push({ key: completedRow.key, data: completedRow.data });
         }
         retainPersistedRow(completedRow, completedRowsToPersist);
         await enqueueIncrementalPersist(completedRow, () => {
           this.clearActiveMapCheckpointUpdate(rowKey, normalizedTableNamespace);
-          updateMapFrameProgress({ completedRowKey: rowKey });
         });
         return COMPLETED_ROW;
       } catch (error) {
         if (isPlayRowExecutionSuspendedError(error)) {
           waitingBaseRows.set(idx, baseRow);
           this.pendingRowEventBoundaries.push(error.boundary);
-          updateMapFrameProgress({
+          mapProgress.update({
             pendingRowKey: rowKey,
             activeBoundaryId: error.boundary.boundaryId,
             emitEventType: 'map.suspended',
@@ -10794,7 +10590,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             retryAtMs: error.retryAtMs,
           });
           providerBackpressureRowCount += 1;
-          updateMapFrameProgress({ pendingRowKey: rowKey });
+          mapProgress.update({ pendingRowKey: rowKey });
           const fieldName = activeFieldName;
           if (!fieldName) {
             throw new Error(
@@ -10849,20 +10645,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               },
             ];
           });
-          const existingFrame =
-            this.checkpoint.mapFrames?.[mapScope.mapInvocationId];
-          this.setMapFrame({
-            ...(existingFrame ?? {
-              mapInvocationId: mapScope.mapInvocationId,
-              mapNodeId: mapScope.mapNodeId ?? null,
-              logicalNamespace: mapScope.logicalNamespace,
-              artifactTableNamespace: mapScope.artifactTableNamespace,
-              totalRows: currentTotalRows(),
-              completedRowKeys: [],
-              pendingRowKeys: [],
-              startedAt: Date.now(),
-            }),
-            status: 'suspended',
+          mapProgress.suspend({
             pendingRowKeys: suspendedInputRows.map(({ data, inputIndex }) =>
               executionRowKey(data, inputIndex),
             ),
@@ -10871,18 +10654,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               error.suspension.kind === 'sleep'
                 ? error.suspension.boundaryId
                 : null,
-            updatedAt: Date.now(),
-          });
-          this.emitExecutionEvent({
-            type: 'map.suspended',
-            mapInvocationId: mapScope.mapInvocationId,
-            mapNodeId: mapScope.mapNodeId ?? null,
-            logicalNamespace: mapScope.logicalNamespace,
-            artifactTableNamespace: mapScope.artifactTableNamespace,
-            completedRows: completedKeys.size,
-            failedRows: 0,
-            totalRows: currentTotalRows(),
-            at: Date.now(),
           });
           // ctx.sleep() emitted its boundary checkpoint before control reached
           // this row catch. Emit once more after recording the admitted plan so
@@ -10892,7 +10663,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           throw error;
         }
         const fieldName = rowContext.getStore()?.fieldName;
-        updateMapFrameProgress({
+        mapProgress.update({
           failedDelta: 1,
           status: 'failed',
           emitEventType: 'map.failed',
@@ -10959,34 +10730,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             items[idx] = null as unknown as T;
           }
         : null;
-    let lastMapActivityKey: string | null = null;
-    tracksResolverActivity = true;
-    const publishMapActivity = () => {
-      const counts = mapActivityCounts();
-      const key = `${counts.startedRows}:${counts.activeRows}:${counts.waitingRows}`;
-      if (key === lastMapActivityKey) return;
-      lastMapActivityKey = key;
-      // Admission samples do not rebuild checkpoint key sets. The map's
-      // writer continues to own durable settlement and checkpoint flushing.
-      this.emitExecutionEvent({
-        type: 'map.progress',
-        mapInvocationId: mapScope.mapInvocationId,
-        mapNodeId: mapScope.mapNodeId ?? null,
-        logicalNamespace: mapScope.logicalNamespace,
-        artifactTableNamespace: mapScope.artifactTableNamespace,
-        completedRows:
-          liveNumber(runtimeOptions?.progressCompletedOffset, completedRows) +
-          (liveFrameSets?.completedRowKeys.size ?? 0),
-        failedRows:
-          liveNumber(runtimeOptions?.progressFailedOffset, 0) +
-          (liveFrameSets?.failedRowsCount ?? 0),
-        totalRows: currentTotalRows(),
-        supersededRows: liveNumber(runtimeOptions?.progressSupersededOffset, 0),
-        ...counts,
-        ...this.inlineChildAggregateEventFields(),
-        at: Date.now(),
-      });
-    };
+    const publishMapActivity = () => mapProgress.publishActivity();
     const mapActivityTimer = setInterval(
       publishMapActivity,
       PROGRESS_HEARTBEAT_INTERVAL_MS,
@@ -11008,12 +10752,11 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           releaseDispatchedInputRow?.(idx);
           settledResults[idx] = await mapRowFlow.run({ baseRow }, async () => {
             this.assertRowAdmissionOpen();
-            startedResolverRows += 1;
-            activeResolverRows += 1;
+            mapProgress.resolverStarted();
             try {
               return await runRow(idx, baseRow);
             } finally {
-              activeResolverRows -= 1;
+              mapProgress.resolverFinished();
             }
           });
         } catch (error) {
@@ -11251,24 +10994,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       await incrementalPersistence?.checkpoint(checkpointUpdates);
       await incrementalPersistence?.flush();
       await this.runtimeStepReceiptCompletionWriter.flush();
-      updateMapFrameProgress({
-        status: 'suspended',
-        activeBoundaryId: null,
-        emitEventType: 'map.suspended',
-      });
-      const frame = this.checkpoint.mapFrames?.[mapScope.mapInvocationId];
-      if (!frame) {
-        throw new Error('Suspended map lost its durable execution frame.');
-      }
-      this.setMapFrame({
-        ...frame,
-        completedRowKeys: frame.completedRowKeys.filter(
-          (key) => !waitingRowKeys.has(key),
-        ),
-        pendingRowKeys: rowFeed ? [] : [...waitingRowKeys],
+      mapProgress.suspend({
+        pendingRowKeys: [...waitingRowKeys],
         suspendedInputRows,
         activeBoundaryId: null,
-        updatedAt: Date.now(),
       });
       if (earliestHold && providerWakeAtMs !== null) {
         this.runtimeLog(
@@ -11337,7 +11066,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     // not announce a terminal state with that bounded egress still retained.
     await this.runtimeStepReceiptCompletionWriter.flush();
     if (emitTerminalEvent) {
-      updateMapFrameProgress({
+      mapProgress.update({
         status: 'completed',
         activeBoundaryId: null,
         emitEventType: 'map.completed',