deepline 0.3.128 → 0.3.129

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

@@ -107,6 +107,8 @@ import {
   PLAY_RUNTIME_SHEET_ATTEMPT_LEASE_TTL_MS,
   PLAY_RUNTIME_WORK_RECEIPT_LEASE_TTL_MS,
 } from './lease-policy';
+import { BoundedBatchFunction } from './bounded-batch-function';
+import { jsonByteLengthUpTo } from './output-size-limits';
 import {
   parseRuntimeTestFaultCounts,
   PLAY_RUNTIME_TEST_FAULT_HEADER,
@@ -334,6 +336,49 @@ const RUNTIME_API_RESOLVE_PLAY_RETRY_DELAYS_MS = [
 ] as const;
 const RUNTIME_API_DEFAULT_RETRY_AFTER_MS = 2_000;
 const RUNTIME_API_REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * One gateway dataset-read response must fit below the 16 MiB request/response
+ * transport ceiling, leaving room for the JSON envelope and proxy framing.
+ * This is a decoded-body budget; it is enforced on both sides of the hop.
+ */
+export const RUNTIME_SHEET_READ_BATCH_MAX_RESPONSE_BYTES = 12 * 1024 * 1024;
+export const RUNTIME_SHEET_READ_BATCH_MAX_PAGES = 4;
+const RUNTIME_SHEET_READ_BATCH_MAX_IN_FLIGHT = 2;
+const RUNTIME_SHEET_READ_BATCH_MAX_RETAINED_PAGES = 8;
+const RUNTIME_SHEET_READ_BATCH_MAX_RETAINED_REQUEST_BYTES = 64 * 1024;
+const RUNTIME_SHEET_READ_BATCH_FLUSH_MS = 5;
+/**
+ * A page queues only until an in-flight batch frees its slot, and the in-flight
+ * batches run in parallel, so the longest honest wait is one worst-case runtime
+ * API call: its request timeout on every attempt plus the whole retry ladder.
+ * Past that the lane is wedged rather than busy, and a wedged lane must fail
+ * loudly instead of parking a map row on a promise nothing will settle.
+ */
+export const RUNTIME_SHEET_READ_BATCH_MAX_QUEUE_WAIT_MS =
+  RUNTIME_API_REQUEST_TIMEOUT_MS * (RUNTIME_API_RETRY_DELAYS_MS.length + 1) +
+  RUNTIME_API_RETRY_DELAYS_MS.reduce((total, delay) => total + delay, 0);
+
+export type RuntimeSheetDatasetPageInput = {
+  limit: number;
+  offset: number;
+};
+
+export type RuntimeSheetDatasetPage = {
+  rows: Record<string, unknown>[];
+  limit: number;
+  offset: number;
+};
+
+export class RuntimeSheetDatasetReadBatchTooLargeError extends Error {
+  readonly code = 'runtime_sheet_read_batch_too_large';
+
+  constructor(readonly observedBytes: number) {
+    super(
+      `Runtime dataset read batch exceeds the ${RUNTIME_SHEET_READ_BATCH_MAX_RESPONSE_BYTES} byte decoded response budget (observed at least ${observedBytes} bytes).`,
+    );
+    this.name = 'RuntimeSheetDatasetReadBatchTooLargeError';
+  }
+}
 // A sheet admission can legitimately wait behind two large transactional
 // writes. Keep the caller alive long enough for the FIFO admission queue to
 // make progress instead of aborting a healthy queued start after 30 seconds.
@@ -514,6 +559,10 @@ type RuntimeApiActionRequest =
       action: 'runtime_sheet_read_rows';
       input: Parameters<typeof readRuntimeSheetDatasetRows>[1];
     }
+  | {
+      action: 'runtime_sheet_read_rows_batch';
+      input: Parameters<typeof readRuntimeSheetDatasetRowsBatch>[1];
+    }
   | {
       action: 'runtime_sheet_read_row_keys';
       input: Parameters<typeof readRuntimeSheetDatasetRowKeys>[1];
@@ -632,6 +681,76 @@ function normalizeRuntimeUserEmail(
   return email ? email : null;
 }
 
+class RuntimeApiResponseTooLargeError extends Error {
+  constructor(
+    readonly action: RuntimeApiActionRequest['action'],
+    readonly limitBytes: number,
+    readonly observedBytes: number,
+  ) {
+    super(
+      `Runtime API ${action} response exceeds the ${limitBytes} byte decoded-body budget (observed at least ${observedBytes} bytes).`,
+    );
+    this.name = 'RuntimeApiResponseTooLargeError';
+  }
+}
+
+function runtimeApiResponseByteLimit(
+  action: RuntimeApiActionRequest['action'],
+): number {
+  return action === 'runtime_sheet_read_rows_batch'
+    ? RUNTIME_SHEET_READ_BATCH_MAX_RESPONSE_BYTES
+    : 16 * 1024 * 1024;
+}
+
+async function readRuntimeApiResponseJson(input: {
+  response: Response;
+  action: RuntimeApiActionRequest['action'];
+}): Promise<unknown> {
+  const limitBytes = runtimeApiResponseByteLimit(input.action);
+  const declaredLength = Number(
+    input.response.headers.get('content-length') ?? 0,
+  );
+  if (Number.isFinite(declaredLength) && declaredLength > limitBytes) {
+    await input.response.body?.cancel().catch(() => undefined);
+    throw new RuntimeApiResponseTooLargeError(
+      input.action,
+      limitBytes,
+      declaredLength,
+    );
+  }
+  if (!input.response.body) return null;
+  const reader = input.response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let bytes = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const nextBytes = bytes + value.byteLength;
+      if (nextBytes > limitBytes) {
+        await reader.cancel().catch(() => undefined);
+        throw new RuntimeApiResponseTooLargeError(
+          input.action,
+          limitBytes,
+          nextBytes,
+        );
+      }
+      chunks.push(value);
+      bytes = nextBytes;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const body = new Uint8Array(bytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  if (body.byteLength === 0) return null;
+  return JSON.parse(new TextDecoder().decode(body)) as unknown;
+}
+
 async function postRuntimeApi<TResponse>(
   context: RuntimeApiContext,
   body: RuntimeApiActionRequest,
@@ -668,8 +787,14 @@ async function postRuntimeApi<TResponse>(
       });
       let parsedValue: unknown;
       try {
-        parsedValue = await response.json();
+        parsedValue = await readRuntimeApiResponseJson({
+          response,
+          action: body.action,
+        });
       } catch (error) {
+        if (error instanceof RuntimeApiResponseTooLargeError) {
+          throw error;
+        }
         if (abortController.signal.aborted || context.abortSignal?.aborted) {
           throw error;
         }
@@ -683,6 +808,9 @@ async function postRuntimeApi<TResponse>(
           : null;
     } catch (error) {
       clearTimeout(timeout);
+      if (error instanceof RuntimeApiResponseTooLargeError) {
+        throw error;
+      }
       if (context.abortSignal?.aborted) {
         throw context.abortSignal.reason ?? error;
       }
@@ -750,6 +878,18 @@ async function postRuntimeApi<TResponse>(
           : typeof parsed?.debug_error === 'string'
             ? parsed.debug_error
             : null;
+    if (
+      response.status === 413 &&
+      body.action === 'runtime_sheet_read_rows_batch' &&
+      parsed?.code === 'runtime_sheet_read_batch_too_large'
+    ) {
+      throw new RuntimeSheetDatasetReadBatchTooLargeError(
+        typeof parsed.observed_bytes === 'number' &&
+          Number.isFinite(parsed.observed_bytes)
+          ? parsed.observed_bytes
+          : RUNTIME_SHEET_READ_BATCH_MAX_RESPONSE_BYTES + 1,
+      );
+    }
     if (
       response.status === 503 &&
       parsed?.code === 'runtime_postgres_admission_backpressure'
@@ -916,7 +1056,7 @@ function runtimeApiMaxAttempts(
 }
 
 export function isTransientRuntimeApiErrorMessage(message: string): boolean {
-  return /timeout exceeded when trying to connect|timed out|fetch failed|ECONNRESET|ECONNREFUSED|UND_ERR_CONNECT_TIMEOUT|requested endpoint could not be found, or you don't have access|RUNTIME_SCHEDULER_(?:SATURATED|UNAVAILABLE|SCHEMA_NOT_READY)|Runtime scheduler DB pool is saturated|Runtime scheduler DB circuit breaker is open|Runtime scheduler schema .* is not ready/i.test(
+  return /timeout exceeded when trying to connect|timed out|fetch failed|ECONNRESET|ECONNREFUSED|UND_ERR_CONNECT_TIMEOUT|requested endpoint could not be found, or you don't have access|Neon API request failed \((?:408|429|502|503|504)\)|RUNTIME_SCHEDULER_(?:SATURATED|UNAVAILABLE|SCHEMA_NOT_READY)|RUNTIME_RATE_STATE_UNAVAILABLE|Runtime scheduler DB pool is saturated|Runtime scheduler DB circuit breaker is open|Runtime rate state .* is unavailable/i.test(
     message,
   );
 }
@@ -5355,7 +5495,12 @@ export async function completeRuntimeWorkReceipt(
             input.runId,
           ],
         );
-        if (insertedRows[0]) return mapRuntimeWorkReceiptRow(insertedRows[0]);
+        if (insertedRows[0]) {
+          return {
+            ...mapRuntimeWorkReceiptRow(insertedRows[0]),
+            completionDisposition: 'persisted',
+          };
+        }
         const { rows: winnerRows } = await client.query<
           Record<string, unknown>
         >(
@@ -5368,7 +5513,12 @@ export async function completeRuntimeWorkReceipt(
             LIMIT 1`,
           [workReceiptKeyHex(input.key), RECEIPT_STATUS_COMPLETED],
         );
-        return winnerRows[0] ? mapRuntimeWorkReceiptRow(winnerRows[0]) : null;
+        return winnerRows[0]
+          ? {
+              ...mapRuntimeWorkReceiptRow(winnerRows[0]),
+              completionDisposition: 'existing',
+            }
+          : null;
       }
       const runAttempt = normalizeRuntimeRunAttempt(input.runAttempt);
       const { rows } = await client.query<Record<string, unknown>>(
@@ -6857,11 +7007,46 @@ type CompleteRuntimeMapRowChunksInput = {
   outputFields: string[];
 };
 
+/**
+ * Why a terminal row write was rejected as stale. Runtime Sheet rows are fenced
+ * by their schedule-time `_write_version` alone (the legacy attempt-lease
+ * predicates are stubbed to TRUE/FALSE in sheet-attempt-sql.ts), so a stale
+ * versioned write always means the row is owned by a different admission than
+ * the one the writer carries:
+ *  - `newer_write_version`: a later admission (rerun, resumed attempt, or a
+ *    concurrent run of the same play) re-admitted the row after this writer
+ *    admitted it.
+ *  - `older_write_version`: the row was admitted under an older version than
+ *    the writer sent; the writer's version never admitted this row.
+ *  - `already_terminal`: an unversioned writer hit an already-enriched row.
+ *    Nothing is being overwritten, so this is the one benign reason.
+ *  - `unreported`: the gateway returned stale keys without reasons (predates
+ *    this field). Treated as superseded: every stale versioned write is.
+ */
+export type RuntimeMapRowsStaleReason =
+  | 'newer_write_version'
+  | 'older_write_version'
+  | 'already_terminal'
+  | 'unreported';
+
+export type RuntimeMapRowsStaleRow = {
+  key: string;
+  reason: RuntimeMapRowsStaleReason;
+  /** The admission version currently stamped on the sheet row. */
+  rowVersionStamp: number | null;
+};
+
 export type RuntimeMapRowsWriteResult = {
   /** Submitted row identities durably accepted, including idempotent replays. */
   committedKeys: string[];
   /** Submitted row identities rejected because a newer write owns the row. */
   staleKeys: string[];
+  /**
+   * Why each stale key was rejected. Present only when the write produced stale
+   * keys and the classifying side reported reasons; a gateway that predates
+   * this field returns stale keys without it.
+   */
+  staleRows?: RuntimeMapRowsStaleRow[];
   /** Physical row mutations. Idempotent commits do not increment this count. */
   updated: number;
   /** Compatibility alias retained for callers that still call stale rows fenced. */
@@ -6874,16 +7059,67 @@ export type RuntimeMapRowsWriteResult = {
 
 type RuntimeMapRowsMutationResult = {
   updated: number;
-  fencedKeys: string[];
+  fencedRows: RuntimeMapRowsStaleRow[];
   conflictKeys: string[];
 };
 
+const RUNTIME_MAP_ROWS_STALE_REASONS: ReadonlySet<RuntimeMapRowsStaleReason> =
+  new Set([
+    'newer_write_version',
+    'older_write_version',
+    'already_terminal',
+    'unreported',
+  ]);
+
+function parseRuntimeMapRowsFencedRows(
+  value: unknown,
+): RuntimeMapRowsStaleRow[] {
+  const entries =
+    typeof value === 'string' ? (JSON.parse(value) as unknown) : value;
+  if (entries == null) return [];
+  if (!Array.isArray(entries)) {
+    throw new Error(
+      'Runtime Sheet terminal write returned a malformed fenced_rows column.',
+    );
+  }
+  return entries.map((entry) => {
+    const row = entry as Partial<RuntimeMapRowsStaleRow> | null;
+    if (
+      !row ||
+      typeof row.key !== 'string' ||
+      typeof row.reason !== 'string' ||
+      !RUNTIME_MAP_ROWS_STALE_REASONS.has(row.reason)
+    ) {
+      throw new Error(
+        `Runtime Sheet terminal write returned a malformed fenced row: ${JSON.stringify(entry)}.`,
+      );
+    }
+    const rowVersionStamp =
+      row.rowVersionStamp == null ? null : Number(row.rowVersionStamp);
+    return {
+      key: row.key,
+      reason: row.reason,
+      rowVersionStamp:
+        rowVersionStamp !== null && Number.isFinite(rowVersionStamp)
+          ? rowVersionStamp
+          : null,
+    };
+  });
+}
+
 function classifyRuntimeMapRowsWrite(input: {
   submittedKeys: Iterable<string>;
   updated: number;
-  fencedKeys: Iterable<string>;
+  fencedKeys?: Iterable<string>;
+  fencedRows?: Iterable<RuntimeMapRowsStaleRow>;
 }): RuntimeMapRowsWriteResult {
-  const staleKeys = [...new Set(input.fencedKeys)];
+  const staleRowsByKey = new Map<string, RuntimeMapRowsStaleRow>();
+  for (const row of input.fencedRows ?? []) {
+    if (!staleRowsByKey.has(row.key)) staleRowsByKey.set(row.key, row);
+  }
+  const staleKeys = [
+    ...new Set([...staleRowsByKey.keys(), ...(input.fencedKeys ?? [])]),
+  ];
   const staleSet = new Set(staleKeys);
   const committedKeys = [...new Set(input.submittedKeys)].filter(
     (key) => !staleSet.has(key),
@@ -6891,6 +7127,9 @@ function classifyRuntimeMapRowsWrite(input: {
   return {
     committedKeys,
     staleKeys,
+    ...(staleRowsByKey.size > 0
+      ? { staleRows: [...staleRowsByKey.values()] }
+      : {}),
     updated: input.updated,
     fencedKeys: staleKeys,
     staleDropped: staleKeys.length,
@@ -6898,6 +7137,99 @@ function classifyRuntimeMapRowsWrite(input: {
   };
 }
 
+/**
+ * The stale rows of a terminal write that prove this writer no longer owns the
+ * sheet: every stale key except the ones the caller verified as idempotent
+ * same-run settlements and the benign unversioned `already_terminal` case. A
+ * result without `staleRows` (a gateway that predates reasons) reports its
+ * stale keys as `unreported`, which counts as superseded: a versioned write can
+ * only be stale when the row carries a different admission version.
+ */
+export function supersededRuntimeMapRows(
+  result: Pick<RuntimeMapRowsWriteResult, 'staleKeys' | 'staleRows'>,
+  options: { exceptKeys?: Iterable<string> } = {},
+): RuntimeMapRowsStaleRow[] {
+  const except = new Set(options.exceptKeys ?? []);
+  const reported = new Map(
+    (result.staleRows ?? []).map((row) => [row.key, row] as const),
+  );
+  const superseded: RuntimeMapRowsStaleRow[] = [];
+  for (const key of new Set(result.staleKeys)) {
+    if (except.has(key)) continue;
+    const row = reported.get(key) ?? {
+      key,
+      reason: 'unreported' as const,
+      rowVersionStamp: null,
+    };
+    if (row.reason === 'already_terminal') continue;
+    superseded.push(row);
+  }
+  return superseded;
+}
+
+/**
+ * A terminal write batch was rejected because the Runtime Sheet rows belong to
+ * a different write version than this attempt carries. The attempt has been
+ * superseded: nothing it executes from here on can be persisted, so it must
+ * stop instead of spending provider calls on rows that will be dropped. Thrown
+ * by the runner's terminal-write handler and by the Context when a handler
+ * reports `supersededKeys`; both trip the persistence latch.
+ */
+export class RuntimeSheetAttemptSupersededError extends Error {
+  readonly tableNamespace: string;
+  readonly runId: string;
+  readonly writeVersion: number | null;
+  readonly submittedRows: number;
+  readonly supersededRows: RuntimeMapRowsStaleRow[];
+
+  constructor(input: {
+    tableNamespace: string;
+    runId: string;
+    writeVersionValue: number | null;
+    submittedRows: number;
+    supersededRows: RuntimeMapRowsStaleRow[];
+  }) {
+    const reasonCounts = new Map<RuntimeMapRowsStaleReason, number>();
+    for (const row of input.supersededRows) {
+      reasonCounts.set(row.reason, (reasonCounts.get(row.reason) ?? 0) + 1);
+    }
+    const reasons = [...reasonCounts.entries()]
+      .map(([reason, count]) => `${reason}=${count}`)
+      .join(', ');
+    const samples = input.supersededRows
+      .slice(0, 5)
+      .map(
+        (row) =>
+          `key=${row.key} row_write_version=${row.rowVersionStamp ?? 'unknown'}`,
+      )
+      .join('; ');
+    super(
+      `RUNTIME_SHEET_ATTEMPT_SUPERSEDED: Runtime Sheet table "${input.tableNamespace}" ` +
+        `rejected ${input.supersededRows.length} of ${input.submittedRows} terminal row write(s) ` +
+        `from run ${input.runId} at write version ${input.writeVersionValue ?? 'none'} ` +
+        `because the rows are owned by a different write version (${reasons || 'unreported'}). ` +
+        `This attempt has been superseded by a newer admission of these rows and must stop ` +
+        `executing: nothing it persists from here on can be accepted. Sample: ${samples}.`,
+    );
+    this.name = 'RuntimeSheetAttemptSupersededError';
+    this.tableNamespace = input.tableNamespace;
+    this.runId = input.runId;
+    this.writeVersion = input.writeVersionValue;
+    this.submittedRows = input.submittedRows;
+    this.supersededRows = input.supersededRows;
+  }
+}
+
+export function isRuntimeSheetAttemptSupersededError(
+  error: unknown,
+): error is RuntimeSheetAttemptSupersededError {
+  if (error instanceof RuntimeSheetAttemptSupersededError) return true;
+  return (
+    error instanceof Error &&
+    error.name === 'RuntimeSheetAttemptSupersededError'
+  );
+}
+
 function writableEnrichedRuntimeSheetAttemptSql(
   tableAlias: string,
   attemptOwnerRunIdExpression: string,
@@ -6918,7 +7250,7 @@ async function completeRuntimeMapRowChunks(
   input: CompleteRuntimeMapRowChunksInput,
 ): Promise<RuntimeMapRowsMutationResult> {
   let updated = 0;
-  const fencedKeys: string[] = [];
+  const fencedRows: RuntimeMapRowsStaleRow[] = [];
   const conflictKeys: string[] = [];
   for (const chunk of input.chunks) {
     const chunkKeys = chunk.map((row) => row.key);
@@ -6946,7 +7278,7 @@ async function completeRuntimeMapRowChunks(
     const { rows } = await client.query<{
       updated: number;
       matched_keys: string[];
-      fenced_keys: string[];
+      fenced_rows: unknown;
       conflict_keys: string[];
     }>(
       `WITH updates AS (
@@ -7062,7 +7394,13 @@ async function completeRuntimeMapRowChunks(
            FROM applied_rows
        ),
        fenced_rows AS (
-         SELECT updates.matched_key AS _key
+         SELECT updates.matched_key AS _key,
+                CASE
+                  WHEN $13::bigint IS NOT NULL AND target._write_version > $13::bigint THEN 'newer_write_version'
+                  WHEN $13::bigint IS NOT NULL AND target._write_version < $13::bigint THEN 'older_write_version'
+                  ELSE 'already_terminal'
+                END AS reason,
+                target._write_version AS row_write_version
            FROM matched_updates AS updates
            JOIN ${sheetTable(session)} AS target
              ON target._key = updates.matched_key
@@ -7166,7 +7504,7 @@ async function completeRuntimeMapRowChunks(
        SELECT
          (SELECT count(*)::int FROM applied_rows) AS updated,
          coalesce((SELECT array_agg(matched_key) FROM matched_updates), '{}'::text[]) AS matched_keys,
-         coalesce((SELECT array_agg(_key) FROM fenced_rows), '{}'::text[]) AS fenced_keys,
+         coalesce((SELECT jsonb_agg(jsonb_build_object('key', _key, 'reason', reason, 'rowVersionStamp', row_write_version)) FROM fenced_rows), '[]'::jsonb) AS fenced_rows,
          coalesce((SELECT array_agg(_key) FROM same_version_conflicts), '{}'::text[]) AS conflict_keys,
          (SELECT count(*)::int FROM summary_delta) AS summary_delta_count,
          (SELECT count(*)::int FROM column_delta) AS column_delta_count`,
@@ -7187,14 +7525,14 @@ async function completeRuntimeMapRowChunks(
       ],
     );
     const matchedKeys = new Set(rows[0]?.matched_keys ?? []);
-    const chunkFencedKeys = rows[0]?.fenced_keys ?? [];
+    const chunkFencedRows = parseRuntimeMapRowsFencedRows(rows[0]?.fenced_rows);
     const chunkConflictKeys = rows[0]?.conflict_keys ?? [];
     // An exact-version replay that already produced the same terminal value is
     // accepted idempotently even when SQL has no physical mutation to apply.
-    // Stale versions remain excluded through fenced_keys.
+    // Stale versions remain excluded through fenced_rows.
     const appliedCount = Number(rows[0]?.updated ?? 0);
     updated += appliedCount;
-    fencedKeys.push(...chunkFencedKeys);
+    fencedRows.push(...chunkFencedRows);
     conflictKeys.push(...chunkConflictKeys);
 
     if (chunkConflictKeys.length > 0) {
@@ -7217,10 +7555,10 @@ async function completeRuntimeMapRowChunks(
       { ...input, chunks: [repairChunk] },
     );
     updated += repaired.updated;
-    fencedKeys.push(...repaired.fencedKeys);
+    fencedRows.push(...repaired.fencedRows);
     conflictKeys.push(...repaired.conflictKeys);
   }
-  return { updated, fencedKeys, conflictKeys };
+  return { updated, fencedRows, conflictKeys };
 }
 
 async function completeRuntimeMapRowChunksWithInputIndexRepair(
@@ -7229,7 +7567,7 @@ async function completeRuntimeMapRowChunksWithInputIndexRepair(
   input: CompleteRuntimeMapRowChunksInput,
 ): Promise<RuntimeMapRowsMutationResult> {
   let updated = 0;
-  const fencedKeys: string[] = [];
+  const fencedRows: RuntimeMapRowsStaleRow[] = [];
   const conflictKeys: string[] = [];
   for (const chunk of input.chunks) {
     const chunkKeys = chunk.map((row) => row.key);
@@ -7249,7 +7587,7 @@ async function completeRuntimeMapRowChunksWithInputIndexRepair(
     );
     const { rows } = await client.query<{
       _key?: string;
-      fenced_keys?: string[];
+      fenced_rows?: unknown;
       conflict_keys?: string[];
       updated?: number;
     }>(
@@ -7362,7 +7700,13 @@ async function completeRuntimeMapRowChunksWithInputIndexRepair(
            FROM applied_rows
        ),
        fenced_rows AS (
-         SELECT updates.submitted_key AS _key
+         SELECT updates.submitted_key AS _key,
+                CASE
+                  WHEN $13::bigint IS NOT NULL AND target._write_version > $13::bigint THEN 'newer_write_version'
+                  WHEN $13::bigint IS NOT NULL AND target._write_version < $13::bigint THEN 'older_write_version'
+                  ELSE 'already_terminal'
+                END AS reason,
+                target._write_version AS row_write_version
            FROM matched_updates AS updates
            JOIN ${sheetTable(session)} AS target
              ON target._key = updates.matched_key
@@ -7463,7 +7807,7 @@ async function completeRuntimeMapRowChunksWithInputIndexRepair(
        )
        SELECT
          (SELECT count(*)::int FROM applied_rows) AS updated,
-         coalesce((SELECT array_agg(_key) FROM fenced_rows), '{}'::text[]) AS fenced_keys,
+         coalesce((SELECT jsonb_agg(jsonb_build_object('key', _key, 'reason', reason, 'rowVersionStamp', row_write_version)) FROM fenced_rows), '[]'::jsonb) AS fenced_rows,
          coalesce((SELECT array_agg(_key) FROM same_version_conflicts), '{}'::text[]) AS conflict_keys`,
       [
         chunkKeys,
@@ -7482,10 +7826,10 @@ async function completeRuntimeMapRowChunksWithInputIndexRepair(
       ],
     );
     updated += Number(rows[0]?.updated ?? 0);
-    fencedKeys.push(...(rows[0]?.fenced_keys ?? []));
+    fencedRows.push(...parseRuntimeMapRowsFencedRows(rows[0]?.fenced_rows));
     conflictKeys.push(...(rows[0]?.conflict_keys ?? []));
   }
-  return { updated, fencedKeys, conflictKeys };
+  return { updated, fencedRows, conflictKeys };
 }
 
 async function insertMissingCompletedMapRowChunks(
@@ -7680,7 +8024,7 @@ async function failRuntimeMapRowChunks(
   },
 ): Promise<RuntimeMapRowsMutationResult> {
   let updated = 0;
-  const fencedKeys: string[] = [];
+  const fencedRows: RuntimeMapRowsStaleRow[] = [];
   const conflictKeys: string[] = [];
   for (const chunk of input.chunks) {
     const chunkKeys = chunk.map((row) => row.key);
@@ -7713,7 +8057,7 @@ async function failRuntimeMapRowChunks(
     );
     const { rows } = await client.query<{
       updated?: number;
-      fenced_keys?: string[];
+      fenced_rows?: unknown;
       conflict_keys?: string[];
     }>(
       `WITH updates AS (
@@ -7829,7 +8173,13 @@ async function failRuntimeMapRowChunks(
            FROM applied_rows
        ),
        fenced_rows AS (
-         SELECT updates.matched_key AS _key
+         SELECT updates.matched_key AS _key,
+                CASE
+                  WHEN $16::bigint IS NOT NULL AND target._write_version > $16::bigint THEN 'newer_write_version'
+                  WHEN $16::bigint IS NOT NULL AND target._write_version < $16::bigint THEN 'older_write_version'
+                  ELSE 'already_terminal'
+                END AS reason,
+                target._write_version AS row_write_version
            FROM matched_updates AS updates
            JOIN ${sheetTable(session)} AS target
              ON target._key = updates.matched_key
@@ -7908,7 +8258,7 @@ async function failRuntimeMapRowChunks(
        )
        SELECT
          (SELECT count(*)::int FROM applied_rows) AS updated,
-         coalesce((SELECT array_agg(_key) FROM fenced_rows), '{}'::text[]) AS fenced_keys,
+         coalesce((SELECT jsonb_agg(jsonb_build_object('key', _key, 'reason', reason, 'rowVersionStamp', row_write_version)) FROM fenced_rows), '[]'::jsonb) AS fenced_rows,
          coalesce((SELECT array_agg(_key) FROM same_version_conflicts), '{}'::text[]) AS conflict_keys`,
       [
         chunkKeys,
@@ -7930,13 +8280,13 @@ async function failRuntimeMapRowChunks(
       ],
     );
     const appliedCount = Number(rows[0]?.updated ?? 0);
-    const chunkFencedKeys = rows[0]?.fenced_keys ?? [];
+    const chunkFencedRows = parseRuntimeMapRowsFencedRows(rows[0]?.fenced_rows);
     const chunkConflictKeys = rows[0]?.conflict_keys ?? [];
     updated += appliedCount;
-    fencedKeys.push(...chunkFencedKeys);
+    fencedRows.push(...chunkFencedRows);
     conflictKeys.push(...chunkConflictKeys);
   }
-  return { updated, fencedKeys, conflictKeys };
+  return { updated, fencedRows, conflictKeys };
 }
 
 /**
@@ -8006,6 +8356,11 @@ export async function completeRuntimeMapRows(
         submittedKeys,
         updated: result.updated,
         fencedKeys: staleKeys,
+        // A gateway that predates stale reasons omits staleRows; keep it
+        // absent so the caller classifies those keys as unreported.
+        fencedRows: Array.isArray(result.staleRows)
+          ? parseRuntimeMapRowsFencedRows(result.staleRows)
+          : undefined,
       }),
       // Preserve the gateway's compatibility classification during rollout.
       fencedKeys: result.fencedKeys,
@@ -8141,11 +8496,11 @@ export async function completeRuntimeMapRows(
               );
               return {
                 updated: updated.updated + inserted.inserted,
-                fencedKeys: updated.fencedKeys,
+                fencedRows: updated.fencedRows,
                 conflictKeys: updated.conflictKeys,
               };
             })()
-          : { updated: 0, fencedKeys: [], conflictKeys: [] };
+          : { updated: 0, fencedRows: [], conflictKeys: [] };
       const failed =
         failedRows.length > 0
           ? await failRuntimeMapRowChunks(client, session, {
@@ -8164,7 +8519,7 @@ export async function completeRuntimeMapRows(
                 input.tableNamespace,
               ),
             })
-          : { updated: 0, fencedKeys: [], conflictKeys: [] };
+          : { updated: 0, fencedRows: [], conflictKeys: [] };
       const conflictKeys = [...completed.conflictKeys, ...failed.conflictKeys];
       if (conflictKeys.length > 0) {
         throw new Error(
@@ -8178,7 +8533,7 @@ export async function completeRuntimeMapRows(
       return classifyRuntimeMapRowsWrite({
         submittedKeys: uniqueRows.keys(),
         updated: completed.updated + failed.updated,
-        fencedKeys: [...completed.fencedKeys, ...failed.fencedKeys],
+        fencedRows: [...completed.fencedRows, ...failed.fencedRows],
       });
     },
   );
@@ -8207,27 +8562,160 @@ export function createCompleteRuntimeMapRowsOperation(
   return () => completeRuntimeMapRows(context, frozenInput);
 }
 
-export async function readRuntimeSheetDatasetRows(
+export type RuntimeSheetDatasetReadInput = {
+  tableNamespace: string;
+  runId?: string | null;
+  rowMode?: 'output' | 'all';
+  limit: number;
+  offset: number;
+};
+
+export type RuntimeSheetDatasetReadBatchInput = Omit<
+  RuntimeSheetDatasetReadInput,
+  'limit' | 'offset'
+> & {
+  pages: readonly RuntimeSheetDatasetPageInput[];
+};
+
+export type RuntimeSheetDatasetReadBatchResult = {
+  pages: RuntimeSheetDatasetPage[];
+};
+
+function normalizeRuntimeSheetDatasetPage(
+  input: RuntimeSheetDatasetPageInput,
+): RuntimeSheetDatasetPageInput {
+  if (!input || typeof input !== 'object') {
+    throw new Error('Runtime dataset page input must be an object.');
+  }
+  if (!Number.isFinite(input.limit) || !Number.isFinite(input.offset)) {
+    throw new Error('Runtime dataset page limit and offset must be finite.');
+  }
+  return {
+    limit: Math.max(
+      1,
+      Math.min(DIRECT_POSTGRES_BATCH_SIZE, Math.floor(input.limit)),
+    ),
+    offset: Math.max(0, Math.floor(input.offset)),
+  };
+}
+
+function assertRuntimeSheetDatasetReadBatchResponse(
+  value: unknown,
+  requestedPages: readonly RuntimeSheetDatasetPageInput[],
+): asserts value is RuntimeSheetDatasetReadBatchResult {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Runtime dataset batch response must be an object.');
+  }
+  const pages = (value as { pages?: unknown }).pages;
+  if (!Array.isArray(pages) || pages.length !== requestedPages.length) {
+    throw new Error(
+      `Runtime dataset batch response must contain ${requestedPages.length} correlated page result(s).`,
+    );
+  }
+  for (const [index, requested] of requestedPages.entries()) {
+    const page = pages[index];
+    if (!page || typeof page !== 'object' || Array.isArray(page)) {
+      throw new Error(
+        `Runtime dataset batch response page ${index} must be an object.`,
+      );
+    }
+    const result = page as Partial<RuntimeSheetDatasetPage>;
+    if (
+      result.limit !== requested.limit ||
+      result.offset !== requested.offset ||
+      !Array.isArray(result.rows) ||
+      result.rows.length > requested.limit ||
+      result.rows.some(
+        (row) => !row || typeof row !== 'object' || Array.isArray(row),
+      )
+    ) {
+      throw new Error(
+        `Runtime dataset batch response page ${index} is not correlated to its requested offset and limit.`,
+      );
+    }
+  }
+}
+
+function assertRuntimeSheetDatasetReadBatchWithinBudget(
+  value: RuntimeSheetDatasetReadBatchResult,
+): void {
+  const measurement = jsonByteLengthUpTo(
+    value,
+    RUNTIME_SHEET_READ_BATCH_MAX_RESPONSE_BYTES,
+  );
+  if (measurement.exceeded) {
+    throw new RuntimeSheetDatasetReadBatchTooLargeError(measurement.bytes);
+  }
+}
+
+function isRuntimeSheetDatasetReadBatchUnsupportedError(
+  error: unknown,
+): boolean {
+  return (
+    error instanceof Error &&
+    /Unsupported runtime data-plane action/i.test(error.message)
+  );
+}
+
+/**
+ * Redeem several ordered dataset pages under one scoped DB session or gateway
+ * request. The response deliberately stays positional: a caller can only
+ * receive the page it asked for, in the order it asked for it.
+ */
+export async function readRuntimeSheetDatasetRowsBatch(
   context: RuntimeApiContext & { playName: string },
-  input: {
-    tableNamespace: string;
-    runId?: string | null;
-    rowMode?: 'output' | 'all';
-    limit: number;
-    offset: number;
-  },
-): Promise<{ rows: Record<string, unknown>[]; limit: number; offset: number }> {
+  input: RuntimeSheetDatasetReadBatchInput,
+): Promise<RuntimeSheetDatasetReadBatchResult> {
+  if (!Array.isArray(input.pages)) {
+    throw new Error('Runtime dataset read batch pages must be an array.');
+  }
+  if (
+    input.pages.length === 0 ||
+    input.pages.length > RUNTIME_SHEET_READ_BATCH_MAX_PAGES
+  ) {
+    throw new Error(
+      `Runtime dataset read batch requires 1-${RUNTIME_SHEET_READ_BATCH_MAX_PAGES} pages.`,
+    );
+  }
+  const pages = input.pages.map(normalizeRuntimeSheetDatasetPage);
   if (context.dbSessionStrategy === 'gateway_only') {
-    return await postRuntimeApi(context, {
-      action: 'runtime_sheet_read_rows',
-      input,
-    });
+    try {
+      const result = await postRuntimeApi<RuntimeSheetDatasetReadBatchResult>(
+        context,
+        {
+          action: 'runtime_sheet_read_rows_batch',
+          input: { ...input, pages },
+        },
+      );
+      assertRuntimeSheetDatasetReadBatchResponse(result, pages);
+      return result;
+    } catch (error) {
+      // New runners can cross a rolling gateway fleet. Keep the old
+      // single-page action readable until the batch action is everywhere;
+      // this is a compatibility fallback, never a second read of an accepted
+      // batch response.
+      if (!isRuntimeSheetDatasetReadBatchUnsupportedError(error)) {
+        throw error;
+      }
+      const legacyPages: RuntimeSheetDatasetPage[] = [];
+      for (const page of pages) {
+        legacyPages.push(
+          await postRuntimeApi(context, {
+            action: 'runtime_sheet_read_rows',
+            input: {
+              tableNamespace: input.tableNamespace,
+              runId: input.runId,
+              rowMode: input.rowMode,
+              ...page,
+            },
+          }),
+        );
+      }
+      const result = { pages: legacyPages };
+      assertRuntimeSheetDatasetReadBatchResponse(result, pages);
+      return result;
+    }
   }
-  const limit = Math.max(
-    1,
-    Math.min(DIRECT_POSTGRES_BATCH_SIZE, Math.floor(input.limit)),
-  );
-  const offset = Math.max(0, Math.floor(input.offset));
   const session = requireRuntimePostgresSession(
     await getRuntimeDbSession(
       {
@@ -8239,20 +8727,176 @@ export async function readRuntimeSheetDatasetRows(
         tableNamespace: input.tableNamespace,
         logicalTable: 'sheet_rows',
         operations: ['rows.read'],
-        limits: { maxRows: runtimeDbSessionRowLimit(limit) },
+        limits: {
+          maxRows: runtimeDbSessionRowLimit(
+            pages.reduce((total, page) => total + page.limit, 0),
+          ),
+        },
       },
     ),
   );
-  const rows = await readRuntimeRows(session, {
-    limit,
-    offset,
-    runId: input.runId ?? null,
+  const results: RuntimeSheetDatasetPage[] = [];
+  for (const page of pages) {
+    const rows = await readRuntimeRows(session, {
+      limit: page.limit,
+      offset: page.offset,
+      runId: input.runId ?? null,
+      rowMode: input.rowMode,
+    });
+    results.push({
+      rows: rows.map((row) => row.data),
+      limit: page.limit,
+      offset: page.offset,
+    });
+    // Stop before a later page turns a bounded response into several retained
+    // page bodies. The caller will split this read in offset order.
+    assertRuntimeSheetDatasetReadBatchWithinBudget({ pages: results });
+  }
+  const result = { pages: results };
+  assertRuntimeSheetDatasetReadBatchResponse(result, pages);
+  assertRuntimeSheetDatasetReadBatchWithinBudget(result);
+  return result;
+}
+
+export async function readRuntimeSheetDatasetRows(
+  context: RuntimeApiContext & { playName: string },
+  input: RuntimeSheetDatasetReadInput,
+): Promise<RuntimeSheetDatasetPage> {
+  const result = await readRuntimeSheetDatasetRowsBatch(context, {
+    tableNamespace: input.tableNamespace,
+    runId: input.runId,
     rowMode: input.rowMode,
+    pages: [{ limit: input.limit, offset: input.offset }],
+  });
+  return result.pages[0]!;
+}
+
+async function readRuntimeSheetDatasetPageWithAdaptiveLimit(
+  context: RuntimeApiContext & { playName: string },
+  input: RuntimeSheetDatasetReadInput,
+  knownTooLarge = false,
+): Promise<RuntimeSheetDatasetPage> {
+  if (!knownTooLarge) {
+    try {
+      return await readRuntimeSheetDatasetRows(context, input);
+    } catch (error) {
+      if (
+        !(error instanceof RuntimeSheetDatasetReadBatchTooLargeError) ||
+        input.limit <= 1
+      ) {
+        throw error;
+      }
+    }
+  }
+  if (input.limit <= 1) {
+    throw new RuntimeSheetDatasetReadBatchTooLargeError(
+      RUNTIME_SHEET_READ_BATCH_MAX_RESPONSE_BYTES + 1,
+    );
+  }
+  const firstLimit = Math.ceil(input.limit / 2);
+  const first = await readRuntimeSheetDatasetPageWithAdaptiveLimit(context, {
+    ...input,
+    limit: firstLimit,
+  });
+  if (first.rows.length < firstLimit) {
+    return { ...first, limit: input.limit };
+  }
+  const second = await readRuntimeSheetDatasetPageWithAdaptiveLimit(context, {
+    ...input,
+    limit: input.limit - firstLimit,
+    offset: input.offset + first.rows.length,
   });
   return {
-    rows: rows.map((row) => row.data),
-    limit,
-    offset,
+    rows: [...first.rows, ...second.rows],
+    limit: input.limit,
+    offset: input.offset,
+  };
+}
+
+export type RuntimeSheetDatasetPageReader = {
+  read(input: RuntimeSheetDatasetPageInput): Promise<RuntimeSheetDatasetPage>;
+};
+
+/**
+ * The common lazy-handle reader. It batches only pages that share every
+ * authority fact and has bounded request retention, active requests, and
+ * decoded response size. The rare oversized response is split in order rather
+ * than silently truncating the dataset or increasing the memory ceiling.
+ */
+export function createRuntimeSheetDatasetPageReader(input: {
+  context: RuntimeApiContext & { playName: string };
+  tableNamespace: string;
+  runId?: string | null;
+  rowMode?: 'output' | 'all';
+}): RuntimeSheetDatasetPageReader {
+  const tokenDigest = createHash('sha256')
+    .update(input.context.executorToken?.trim() ?? '')
+    .digest('hex')
+    .slice(0, 24);
+  const scope = [
+    input.context.baseUrl?.trim() ?? '',
+    tokenDigest,
+    input.context.orgId?.trim() ?? '',
+    input.context.playName,
+    input.runId?.trim() ?? input.context.runId?.trim() ?? '',
+    input.tableNamespace,
+    input.rowMode ?? 'output',
+  ].join('::');
+  const reads = new BoundedBatchFunction<
+    RuntimeSheetDatasetPageInput,
+    RuntimeSheetDatasetPage,
+    string
+  >({
+    keyId: (key) => key,
+    estimateBytes: (page) =>
+      new TextEncoder().encode(JSON.stringify(page)).byteLength,
+    execute: async ({ values }) => {
+      const read = (pages: readonly RuntimeSheetDatasetPageInput[]) =>
+        readRuntimeSheetDatasetRowsBatch(input.context, {
+          tableNamespace: input.tableNamespace,
+          runId: input.runId,
+          rowMode: input.rowMode,
+          pages,
+        });
+      try {
+        return (await read(values)).pages;
+      } catch (error) {
+        if (!(error instanceof RuntimeSheetDatasetReadBatchTooLargeError)) {
+          throw error;
+        }
+        const results: RuntimeSheetDatasetPage[] = [];
+        for (const [index, page] of values.entries()) {
+          results.push(
+            await readRuntimeSheetDatasetPageWithAdaptiveLimit(
+              input.context,
+              {
+                tableNamespace: input.tableNamespace,
+                runId: input.runId,
+                rowMode: input.rowMode,
+                ...page,
+              },
+              values.length === 1 && index === 0,
+            ),
+          );
+        }
+        return results;
+      }
+    },
+    maxBatchItems: RUNTIME_SHEET_READ_BATCH_MAX_PAGES,
+    maxBatchBytes: 16 * 1024,
+    maxRetainedItems: RUNTIME_SHEET_READ_BATCH_MAX_RETAINED_PAGES,
+    maxRetainedBytes: RUNTIME_SHEET_READ_BATCH_MAX_RETAINED_REQUEST_BYTES,
+    maxInFlightBatches: RUNTIME_SHEET_READ_BATCH_MAX_IN_FLIGHT,
+    flushMs: RUNTIME_SHEET_READ_BATCH_FLUSH_MS,
+  });
+  return {
+    read: (page) =>
+      reads.submit({
+        key: scope,
+        value: normalizeRuntimeSheetDatasetPage(page),
+        signal: input.context.abortSignal ?? undefined,
+        maxWaitMs: RUNTIME_SHEET_READ_BATCH_MAX_QUEUE_WAIT_MS,
+      }),
   };
 }
 
@@ -8622,6 +9266,11 @@ export function createRuntimeBackedPlayDataset(input: {
     ...input.context,
     runId: input.context.runId ?? input.runId,
   };
+  const pageReader = createRuntimeSheetDatasetPageReader({
+    context: runtimeContext,
+    tableNamespace: input.tableNamespace,
+    runId: input.runId ?? null,
+  });
   return createDeferredPlayDataset({
     datasetKind: input.datasetKind,
     datasetId: createRuntimeDatasetId(
@@ -8656,62 +9305,30 @@ export function createRuntimeBackedPlayDataset(input: {
         return Number(summary.stats.total ?? 0);
       },
       peek: async (limit) => {
-        const session = await getRuntimeDbSession(runtimeContext, {
-          tableNamespace: input.tableNamespace,
-          logicalTable: 'sheet_rows',
-          operations: ['rows.read'],
-        });
-        const rows = await readRuntimeRows(
-          requireRuntimePostgresSession(session),
-          {
-            limit,
-            offset: 0,
-            runId: input.runId ?? null,
-          },
-        );
-        return rows.map((row) => row.data);
+        if (limit <= 0) return [];
+        return (await pageReader.read({ limit, offset: 0 })).rows;
       },
       at: async (index) => {
-        const session = await getRuntimeDbSession(runtimeContext, {
-          tableNamespace: input.tableNamespace,
-          logicalTable: 'sheet_rows',
-          operations: ['rows.read'],
-        });
-        const rows = await readRuntimeRows(
-          requireRuntimePostgresSession(session),
-          {
-            limit: 1,
-            offset: index,
-            runId: input.runId ?? null,
-          },
-        );
-        return rows[0]?.data;
+        return (await pageReader.read({ limit: 1, offset: index })).rows[0];
       },
       materialize: async (limit) => {
         const pageSize = 1000;
         const materialized: Record<string, unknown>[] = [];
         let offset = 0;
         while (true) {
-          const session = await getRuntimeDbSession(runtimeContext, {
-            tableNamespace: input.tableNamespace,
-            logicalTable: 'sheet_rows',
-            operations: ['rows.read'],
-          });
-          const rows = await readRuntimeRows(
-            requireRuntimePostgresSession(session),
-            {
+          const rows = (
+            await pageReader.read({
               limit:
                 limit !== undefined
                   ? Math.min(pageSize, Math.max(0, limit - materialized.length))
                   : pageSize,
               offset,
-              runId: input.runId ?? null,
-            },
-          );
+            })
+          ).rows;
           if (rows.length === 0) {
             break;
           }
-          materialized.push(...rows.map((row) => row.data));
+          materialized.push(...rows);
           if (limit !== undefined && materialized.length >= limit) {
             return materialized.slice(0, limit);
           }
@@ -8725,26 +9342,17 @@ export function createRuntimeBackedPlayDataset(input: {
             const pageSize = 1000;
             let offset = 0;
             while (true) {
-              const session = await getRuntimeDbSession(runtimeContext, {
-                tableNamespace: input.tableNamespace,
-                logicalTable: 'sheet_rows',
-                operations: ['rows.read'],
+              const page = await pageReader.read({
+                limit: pageSize,
+                offset,
               });
-              const page = await readRuntimeRows(
-                requireRuntimePostgresSession(session),
-                {
-                  limit: pageSize,
-                  offset,
-                  runId: input.runId ?? null,
-                },
-              );
-              if (page.length === 0) {
+              if (page.rows.length === 0) {
                 return;
               }
-              for (const row of page) {
-                yield row.data;
+              for (const row of page.rows) {
+                yield row;
               }
-              offset += page.length;
+              offset += page.rows.length;
             }
           },
         }) as AsyncIterable<Record<string, unknown>>,