deepline 0.1.170 → 0.1.172

package/README.md

@@ -195,7 +195,7 @@ Full sequence from zero to hitting + surviving rate limits via v2 plays.
 
 ```bash
 # Production
-bash <(curl -sS https://code.deepline.com/api/v2/sdk/install)
+bash <(curl -fsSL https://deepline.com/api/v2/sdk/install)
 
 # Local dev (no install needed)
 bun run dev   # start server

package/dist/bundling-sources/apps/play-runner-workers/src/entry.ts

@@ -1719,7 +1719,10 @@ class RuntimeReceiptPersistenceError extends Error {
 function isRuntimeReceiptPersistenceError(error: unknown): boolean {
   if (!error || typeof error !== 'object') return false;
   if (error instanceof RuntimeReceiptPersistenceError) return true;
-  if (error instanceof Error && error.name === 'RuntimeReceiptPersistenceError') {
+  if (
+    error instanceof Error &&
+    error.name === 'RuntimeReceiptPersistenceError'
+  ) {
     return true;
   }
   const nestedErrors = (error as { errors?: unknown }).errors;
@@ -2559,8 +2562,7 @@ class WorkerToolBatchScheduler {
                 { id: request.id, toolId, input: request.input },
                 request.workflowStep,
                 this.callbacks,
-                (retryAfterMs) =>
-                  this.reportBackpressure(toolId, retryAfterMs),
+                (retryAfterMs) => this.reportBackpressure(toolId, retryAfterMs),
                 () => this.governor.chargeBudget('retry'),
                 toolContract?.retrySafeTransientHttp === true,
                 this.abortSignal,
@@ -4529,9 +4531,12 @@ function createMinimalWorkerCtx(
   const executeWithRuntimeReceipt = async <T>(
     key: string,
     execute: () => Promise<T> | T,
-    repairRunningReceiptForSameRun = false,
-    reclaimRunning = false,
-    repairRunningReceiptForSameRunAfterWaitTimeout = false,
+    options: {
+      repairRunningReceiptForSameRun?: boolean;
+      reclaimRunning?: boolean;
+      repairRunningReceiptForSameRunAfterWaitTimeout?: boolean;
+      runningReceiptWaitMaxAttempts?: number;
+    } = {},
   ): Promise<T> => {
     const serialized = await runWorkerRuntimeReceiptBoundary<unknown>({
       orgId: req.orgId,
@@ -4540,9 +4545,12 @@ function createMinimalWorkerCtx(
       key,
       receiptStore,
       execute: async () => serializeDurableStepValue(await execute()),
-      repairRunningReceiptForSameRun,
-      reclaimRunning,
-      repairRunningReceiptForSameRunAfterWaitTimeout,
+      repairRunningReceiptForSameRun:
+        options.repairRunningReceiptForSameRun ?? false,
+      reclaimRunning: options.reclaimRunning ?? false,
+      repairRunningReceiptForSameRunAfterWaitTimeout:
+        options.repairRunningReceiptForSameRunAfterWaitTimeout ?? false,
+      runningReceiptWaitMaxAttempts: options.runningReceiptWaitMaxAttempts,
     });
     return deserializeDurableStepValue(serialized) as T;
   };
@@ -4553,19 +4561,15 @@ function createMinimalWorkerCtx(
     if (!workflowStep) {
       return await executeWithRuntimeReceipt(name, execute);
     }
-    return await executeWithRuntimeReceipt(
-      name,
-      async () => {
-        const serialized = await (
-          workflowStep.do as unknown as (
-            name: string,
-            callback: () => Promise<unknown>,
-          ) => Promise<unknown>
-        )(name, async () => serializeDurableStepValue(await execute()));
-        return deserializeDurableStepValue(serialized) as T;
-      },
-      false,
-    );
+    return await executeWithRuntimeReceipt(name, async () => {
+      const serialized = await (
+        workflowStep.do as unknown as (
+          name: string,
+          callback: () => Promise<unknown>,
+        ) => Promise<unknown>
+      )(name, async () => serializeDurableStepValue(await execute()));
+      return deserializeDurableStepValue(serialized) as T;
+    });
   };
   const nextCtxStepReceiptKey = (
     name: string,
@@ -4648,7 +4652,6 @@ function createMinimalWorkerCtx(
         nodeId: mapNodeId,
         progress: {
           artifactTableNamespace: name,
-          failed: 0,
           ...progress,
           updatedAt: progress.updatedAt ?? nowMs(),
         },
@@ -5032,6 +5035,7 @@ function createMinimalWorkerCtx(
           {
             completed,
             total: progressTotalRows,
+            failed: failedExecutedRows,
             startedAt: mapStartedAt,
             message: formatMapProgressMessage(completed, progressTotalRows),
           },
@@ -5076,7 +5080,7 @@ function createMinimalWorkerCtx(
       let stepCellsCompleted = 0;
       let stepCellsSkipped = 0;
       const generatedOutputFields = new Set<string>();
-      const pendingLiveRowUpdates: Array<
+      const pendingLiveUpdates: Array<
         Omit<PlayRowUpdate, 'rowId'> & { runId?: string }
       > = [];
       const persistedExecutedIndexes = new Set<number>();
@@ -5086,9 +5090,9 @@ function createMinimalWorkerCtx(
       let scheduledPersistTimer: ReturnType<typeof setTimeout> | null = null;
       let persistFlushChain: Promise<void> = Promise.resolve();
       let persistFailure: unknown = null;
-      let scheduledLiveUpdateTimer: ReturnType<typeof setTimeout> | null = null;
-      let liveUpdateFlushChain: Promise<void> = Promise.resolve();
-      let liveUpdateFailureCount = 0;
+      let liveUpdateTimer: ReturnType<typeof setTimeout> | null = null;
+      let liveFlushChain: Promise<void> = Promise.resolve();
+      let liveUpdateFailures = 0;
 
       const clearScheduledPersistTimer = () => {
         if (scheduledPersistTimer) {
@@ -5097,10 +5101,10 @@ function createMinimalWorkerCtx(
         }
       };
 
-      const clearScheduledLiveUpdateTimer = () => {
-        if (scheduledLiveUpdateTimer) {
-          clearTimeout(scheduledLiveUpdateTimer);
-          scheduledLiveUpdateTimer = null;
+      const clearLiveUpdateTimer = () => {
+        if (liveUpdateTimer) {
+          clearTimeout(liveUpdateTimer);
+          liveUpdateTimer = null;
         }
       };
 
@@ -5218,14 +5222,36 @@ function createMinimalWorkerCtx(
         return task;
       };
 
+      const coalesceLiveUpdates = (
+        updates: Array<Omit<PlayRowUpdate, 'rowId'> & { runId?: string }>,
+      ): Array<Omit<PlayRowUpdate, 'rowId'> & { runId?: string }> => {
+        const mergedByKey = new Map<
+          string,
+          Omit<PlayRowUpdate, 'rowId'> & { runId?: string }
+        >();
+        for (const update of updates) {
+          const existing = mergedByKey.get(update.key);
+          mergedByKey.set(update.key, {
+            ...existing,
+            ...update,
+            dataPatch: { ...existing?.dataPatch, ...update.dataPatch },
+            cellMetaPatch: {
+              ...existing?.cellMetaPatch,
+              ...update.cellMetaPatch,
+            },
+          });
+        }
+        return [...mergedByKey.values()];
+      };
+
       const flushLiveRowUpdates = (): Promise<void> => {
-        clearScheduledLiveUpdateTimer();
-        if (pendingLiveRowUpdates.length === 0) {
-          return liveUpdateFlushChain;
+        clearLiveUpdateTimer();
+        if (pendingLiveUpdates.length === 0) {
+          return liveFlushChain;
         }
-        const updates = pendingLiveRowUpdates.splice(0);
+        const updates = coalesceLiveUpdates(pendingLiveUpdates.splice(0));
         const extraOutputFields = Array.from(generatedOutputFields);
-        const task = liveUpdateFlushChain.then(async () => {
+        const task = liveFlushChain.then(async () => {
           try {
             await applyLiveMapRowUpdates({
               req,
@@ -5235,33 +5261,29 @@ function createMinimalWorkerCtx(
               updates,
             });
           } catch (error) {
-            liveUpdateFailureCount += 1;
-            if (liveUpdateFailureCount <= MAP_ROW_FAILURE_SAMPLE_LIMIT) {
+            liveUpdateFailures += 1;
+            if (liveUpdateFailures <= MAP_ROW_FAILURE_SAMPLE_LIMIT) {
               emitEvent({
                 type: 'log',
                 level: 'warn',
-                message:
-                  `Live row update flush failed for ctx.dataset("${name}") ` +
-                  `(non-fatal; terminal rows still persist): ${formatWorkerRowFailureMessage(error)}`,
+                message: formatWorkerRowFailureMessage(error),
                 ts: nowMs(),
               });
             }
           }
         });
-        liveUpdateFlushChain = task.catch(() => undefined);
+        liveFlushChain = task.catch(() => undefined);
         return task;
       };
 
       const scheduleLiveRowUpdates = () => {
-        if (
-          pendingLiveRowUpdates.length >= MAP_LIVE_UPDATE_FLUSH_CHUNK_ROWS
-        ) {
+        if (pendingLiveUpdates.length >= MAP_LIVE_UPDATE_FLUSH_CHUNK_ROWS) {
           void flushLiveRowUpdates().catch(() => undefined);
           return;
         }
-        if (scheduledLiveUpdateTimer) return;
-        scheduledLiveUpdateTimer = setTimeout(() => {
-          scheduledLiveUpdateTimer = null;
+        if (liveUpdateTimer) return;
+        liveUpdateTimer = setTimeout(() => {
+          liveUpdateTimer = null;
           void flushLiveRowUpdates().catch(() => undefined);
         }, MAP_INCREMENTAL_PERSIST_INTERVAL_MS);
       };
@@ -5269,10 +5291,8 @@ function createMinimalWorkerCtx(
       const enqueueLiveRowUpdate = (
         update: Omit<PlayRowUpdate, 'rowId'> & { runId?: string },
       ): Promise<void> => {
-        pendingLiveRowUpdates.push(update);
-        if (
-          pendingLiveRowUpdates.length >= MAP_LIVE_UPDATE_FLUSH_CHUNK_ROWS
-        ) {
+        pendingLiveUpdates.push(update);
+        if (pendingLiveUpdates.length >= MAP_LIVE_UPDATE_FLUSH_CHUNK_ROWS) {
           void flushLiveRowUpdates().catch(() => undefined);
           return Promise.resolve();
         }
@@ -5397,10 +5417,6 @@ function createMinimalWorkerCtx(
                               else stepCellsCompleted += 1;
                               await enqueueLiveRowUpdate({
                                 key: entry.rowKey,
-                                tableNamespace: name,
-                                runId: req.runId,
-                                status: 'running',
-                                stage: stepOutput.stepId,
                                 dataPatch: {
                                   [stepOutput.columnName]: stepOutput.value,
                                 },
@@ -5431,6 +5447,12 @@ function createMinimalWorkerCtx(
                         completedAt: nowMs(),
                       };
                     }
+                    if (fieldEntries.length > 1) {
+                      await enqueueLiveRowUpdate({
+                        key: entry.rowKey,
+                        dataPatch: { [key]: resolved.value },
+                      });
+                    }
                     activeField = null;
                   }
                   for (const stepOutput of stepProgramOutputs) {
@@ -5607,7 +5629,7 @@ function createMinimalWorkerCtx(
       });
       try {
         await flushLiveRowUpdates();
-        await liveUpdateFlushChain;
+        await liveFlushChain;
         await enqueuePersistExecutedRows();
         await persistFlushChain;
         if (persistFailure) throw persistFailure;
@@ -6733,9 +6755,11 @@ function createMinimalWorkerCtx(
             childPlaySlot?.release();
           }
         },
-        false,
-        false,
-        true,
+        {
+          repairRunningReceiptForSameRunAfterWaitTimeout: true,
+          runningReceiptWaitMaxAttempts:
+            resolveRuntimeToolReceiptWaitMaxAttempts(input),
+        },
       );
     },
     async fetch(
@@ -7857,7 +7881,9 @@ function extractMaxCreditsPerRun(contractSnapshot: unknown): number | null {
 }
 
 function shouldSkipWorkerComputeBilling(req: RunRequest): boolean {
-  return req.integrationMode === 'fixture' || req.integrationMode === 'eval_stub';
+  return (
+    req.integrationMode === 'fixture' || req.integrationMode === 'eval_stub'
+  );
 }
 
 async function finalizeWorkerComputeBilling(input: {

package/dist/bundling-sources/apps/play-runner-workers/src/runtime/map-chunk-plan.ts

@@ -17,11 +17,10 @@ export { TOOL_CALLING_MAP_CHUNK_SIZE };
 // Paid Cloudflare Workers support a much higher configured subrequest limit.
 // Keep a large buffer for coordinator/storage calls around row-level unbatched
 // tool RPCs, but avoid pathological one-row chunks for provider waterfalls.
-export const UNBATCHED_TOOL_SUBREQUESTS_PER_CHUNK_BUDGET = 500;
+export const UNBATCHED_TOOL_SUBREQUESTS_PER_CHUNK_BUDGET = 200;
 // Fresh unbatched tool calls use one RUNTIME_API integration execute RPC and
 // one HARNESS durable-receipt completion RPC. Batch-cap rows by both.
 export const SUBREQUESTS_PER_UNBATCHED_TOOL_CALL = 2;
-
 export type WorkerMapChunkPlanInput = {
   mapName: string;
   rowCountHint: number | null;
@@ -45,7 +44,7 @@ type ChunkSizingPlan = {
   softWorkflowStepBudget?: number | null;
 };
 
-type MapToolStats = [totalToolCount: number, unbatchedToolCount: number];
+type MapToolStats = [totalToolCount: number, unbatchedSubrequestCount: number];
 
 function fieldRoot(field: string | null | undefined): string {
   return String(field ?? '').split('.', 1)[0] ?? '';
@@ -70,41 +69,42 @@ function declarationBelongsToMapOutput(
   );
 }
 
-function isUnbatchedTool(toolId: string): boolean {
-  return getPlayRuntimeBatchStrategy(toolId) === null;
+function countTool(toolId: string): MapToolStats {
+  if (getPlayRuntimeBatchStrategy(toolId) !== null) return [1, 0];
+  return [1, toolId === 'test_high_single' ? 5 : 2];
+}
+
+function addStats(
+  [total, subrequests]: MapToolStats,
+  stats: MapToolStats,
+): MapToolStats {
+  return [total + stats[0], subrequests + stats[1]];
 }
 
 function countToolSubsteps(
   substeps: readonly PlayStaticSubstep[],
 ): MapToolStats {
-  let totalToolCount = 0;
-  let unbatchedToolCount = 0;
+  let stats: MapToolStats = [0, 0];
 
   for (const substep of substeps) {
-    const [nestedTotal, nestedUnbatched] = countToolSubstep(substep);
-    totalToolCount += nestedTotal;
-    unbatchedToolCount += nestedUnbatched;
+    stats = addStats(stats, countToolSubstep(substep));
   }
 
-  return [totalToolCount, unbatchedToolCount];
+  return stats;
 }
 
 function countToolSubstep(substep: PlayStaticSubstep): MapToolStats {
   if (substep.type === 'tool') {
-    return [1, isUnbatchedTool(substep.toolId) ? 1 : 0];
+    return countTool(substep.toolId);
   }
 
   if (substep.type === 'waterfall') {
-    let totalToolCount = 0;
-    let unbatchedToolCount = 0;
+    let stats: MapToolStats = [0, 0];
     for (const step of substep.steps ?? []) {
       if (!step.toolId) continue;
-      totalToolCount += 1;
-      if (isUnbatchedTool(step.toolId)) {
-        unbatchedToolCount += 1;
-      }
+      stats = addStats(stats, countTool(step.toolId));
     }
-    return [totalToolCount, unbatchedToolCount];
+    return stats;
   }
 
   if (substep.type === 'step_suite') {
@@ -117,9 +117,9 @@ function countToolSubstep(substep: PlayStaticSubstep): MapToolStats {
         countToolSubsteps(branch.steps),
       );
       return branchStats.reduce<MapToolStats>(
-        ([totalMax, unbatchedMax], [total, unbatched]) => [
+        ([totalMax, subrequestsMax], [total, subrequests]) => [
           Math.max(totalMax, total),
-          Math.max(unbatchedMax, unbatched),
+          Math.max(subrequestsMax, subrequests),
         ],
         [0, 0],
       );
@@ -151,9 +151,9 @@ function countStepSuiteTools(
     conditionalChildren.length < childStats.length / 2
   ) {
     return childStats.reduce<MapToolStats>(
-      ([totalSum, unbatchedSum], { stats: [total, unbatched] }) => [
+      ([totalSum, subrequestsSum], { stats: [total, subrequests] }) => [
         totalSum + total,
-        unbatchedSum + unbatched,
+        subrequestsSum + subrequests,
       ],
       [0, 0],
     );
@@ -166,9 +166,9 @@ function countStepSuiteTools(
   });
   if (!sameRoot) {
     return childStats.reduce<MapToolStats>(
-      ([totalSum, unbatchedSum], { stats: [total, unbatched] }) => [
+      ([totalSum, subrequestsSum], { stats: [total, subrequests] }) => [
         totalSum + total,
-        unbatchedSum + unbatched,
+        subrequestsSum + subrequests,
       ],
       [0, 0],
     );
@@ -181,52 +181,41 @@ function countStepSuiteTools(
         !(step.type === 'control_flow' && step.kind === 'conditional'),
     )
     .reduce<MapToolStats>(
-      ([totalSum, unbatchedSum], { stats: [total, unbatched] }) => [
+      ([totalSum, subrequestsSum], { stats: [total, subrequests] }) => [
         totalSum + total,
-        unbatchedSum + unbatched,
+        subrequestsSum + subrequests,
       ],
       [0, 0],
     );
   const conditionalStats = conditionalChildren.reduce<MapToolStats>(
-    ([totalSum, unbatchedSum], { stats: [total, unbatched] }) => [
+    ([totalSum, subrequestsSum], { stats: [total, subrequests] }) => [
       totalSum + total,
-      unbatchedSum + unbatched,
+      subrequestsSum + subrequests,
     ],
     [0, 0],
   );
 
-  return [
-    unconditionalStats[0] + conditionalStats[0],
-    unconditionalStats[1] + conditionalStats[1],
-  ];
+  return addStats(unconditionalStats, conditionalStats);
 }
 
 function countProducerTools(
   producers: readonly PlayStaticColumnProducer[],
 ): MapToolStats {
-  let totalToolCount = 0;
-  let unbatchedToolCount = 0;
+  let stats: MapToolStats = [0, 0];
 
   for (const producer of producers) {
     if (producer.kind === 'tool' && producer.toolId) {
-      totalToolCount += 1;
-      if (isUnbatchedTool(producer.toolId)) {
-        unbatchedToolCount += 1;
-      }
+      stats = addStats(stats, countTool(producer.toolId));
     }
     if (producer.substep.type === 'waterfall') {
-      const [nestedTotal, nestedUnbatched] = countToolSubstep(producer.substep);
-      totalToolCount += nestedTotal;
-      unbatchedToolCount += nestedUnbatched;
+      stats = addStats(stats, countToolSubstep(producer.substep));
     }
     if (producer.steps?.length) {
-      const [nestedTotal, nestedUnbatched] = countProducerTools(producer.steps);
-      totalToolCount += nestedTotal;
-      unbatchedToolCount += nestedUnbatched;
+      stats = addStats(stats, countProducerTools(producer.steps));
     }
   }
 
-  return [totalToolCount, unbatchedToolCount];
+  return stats;
 }
 
 function datasetBelongsToPlanMap(
@@ -278,8 +267,7 @@ function countFallbackDeclarationTools(input: {
   outputFields: readonly string[];
   externalStepFields?: readonly string[];
 }): MapToolStats {
-  let totalToolCount = 0;
-  let unbatchedToolCount = 0;
+  let stats: MapToolStats = [0, 0];
 
   for (const declaration of input.declarations) {
     if (
@@ -291,23 +279,19 @@ function countFallbackDeclarationTools(input: {
     ) {
       continue;
     }
-    totalToolCount += 1;
-    if (isUnbatchedTool(declaration.toolId)) {
-      unbatchedToolCount += 1;
-    }
+    stats = addStats(stats, countTool(declaration.toolId));
   }
 
-  return [totalToolCount, unbatchedToolCount];
+  return stats;
 }
 
 function countDeclarationTools(
   declarations: readonly { toolId: string; field?: string | null }[],
 ): MapToolStats {
-  return [
-    declarations.length,
-    declarations.filter((declaration) => isUnbatchedTool(declaration.toolId))
-      .length,
-  ];
+  return declarations.reduce<MapToolStats>(
+    (stats, declaration) => addStats(stats, countTool(declaration.toolId)),
+    [0, 0],
+  );
 }
 
 function countNestedExecutionSteps(
@@ -409,12 +393,13 @@ export function chooseWorkerMapRowsPerChunk(
   }
 
   if (mapToolStats[1] > 0) {
-    const unbatchedToolCallsPerRow =
+    const unbatchedSubrequestsPerRow =
       staticMapToolStats !== null
         ? mapToolStats[1]
-        : Math.max(planMap?.stepsPerChunk ?? 1, mapToolStats[1]);
-    const unbatchedSubrequestsPerRow =
-      unbatchedToolCallsPerRow * SUBREQUESTS_PER_UNBATCHED_TOOL_CALL;
+        : Math.max(
+            (planMap?.stepsPerChunk ?? 1) * SUBREQUESTS_PER_UNBATCHED_TOOL_CALL,
+            mapToolStats[1],
+          );
     const unbatchedToolRowsPerChunk = Math.max(
       1,
       Math.floor(

package/dist/bundling-sources/sdk/src/release.ts

@@ -104,10 +104,10 @@ export const SDK_RELEASE = {
   // 0.1.111 ships dataset-native tool list getters and result row datasets.
   // 0.1.154 removes the short-lived generated enrich StepOptions recompute
   // fields shipped in 0.1.153.
-  version: '0.1.170',
+  version: '0.1.172',
   apiContract: '2026-06-dataset-handle-results-hard-cutover',
   supportPolicy: {
-    latest: '0.1.170',
+    latest: '0.1.172',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
     commandMinimumSupported: [

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

@@ -1315,6 +1315,7 @@ export class PlayContextImpl {
       repairRunningReceiptForSameRun?: boolean;
       repairRunningReceiptForSameRunAfterWaitTimeout?: boolean;
       runningReceiptWaitMaxAttempts?: number;
+      runningReceiptWaitDelayMs?: number;
       reclaimRunning?: boolean;
       markSkipped?: (output: T) => Promise<void> | void;
       onRecovered?: (
@@ -1347,6 +1348,7 @@ export class PlayContextImpl {
       repairRunningReceiptForSameRunAfterWaitTimeout:
         opts.repairRunningReceiptForSameRunAfterWaitTimeout,
       runningReceiptWaitMaxAttempts: opts.runningReceiptWaitMaxAttempts,
+      runningReceiptWaitDelayMs: opts.runningReceiptWaitDelayMs,
       reclaimRunning: opts.reclaimRunning,
       markSkipped: opts.markSkipped,
       onRecovered: opts.onRecovered,
@@ -3881,6 +3883,8 @@ export class PlayContextImpl {
           );
         },
         repairRunningReceiptForSameRunAfterWaitTimeout: true,
+        runningReceiptWaitMaxAttempts:
+          resolveRuntimeToolReceiptWaitMaxAttempts(input),
         execute: executePlayCall,
       },
     );

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

@@ -114,6 +114,9 @@ const RUNTIME_DB_SESSION_ROW_LIMIT_FLOOR = DIRECT_POSTGRES_BATCH_SIZE;
 const APPEND_KEY_SUFFIX_LENGTH = 12;
 const RUNTIME_DB_SESSION_TTL_SECONDS = 10 * 60;
 const RUNTIME_SHEET_ENSURE_CACHE_TTL_MS = 10 * 60_000;
+const RUNTIME_SHEET_READY_AFTER_ENSURE_RETRY_DELAYS_MS = [
+  100, 250, 500, 1_000, 2_000,
+] as const;
 const RUNTIME_DB_SESSION_RENEWAL_WINDOW_MS = 60_000;
 const RUNTIME_API_RETRY_DELAYS_MS = [
   250, 500, 1_000, 2_000, 4_000, 8_000, 8_000,
@@ -529,6 +532,41 @@ async function isRuntimeSheetSchemaReady(
   }
 }
 
+async function waitForRuntimeSheetSchemaReadyAfterEnsure(
+  session: RuntimePostgresSession,
+  input: {
+    sheetContract: PlaySheetContract;
+    timings?: RuntimeSheetTiming[];
+  },
+): Promise<boolean> {
+  for (
+    let attempt = 0;
+    attempt <= RUNTIME_SHEET_READY_AFTER_ENSURE_RETRY_DELAYS_MS.length;
+    attempt += 1
+  ) {
+    const recheckStartedAt = Date.now();
+    const ready = await isRuntimeSheetSchemaReady(session, {
+      sheetContract: input.sheetContract,
+    });
+    input.timings?.push({
+      phase: 'schema_check_after_preloaded_session_ensure',
+      ms: Date.now() - recheckStartedAt,
+      ready,
+      retried: attempt > 0,
+    });
+    if (ready) {
+      return true;
+    }
+    const delay =
+      RUNTIME_SHEET_READY_AFTER_ENSURE_RETRY_DELAYS_MS[attempt] ?? null;
+    if (delay === null) {
+      return false;
+    }
+    await sleep(delay);
+  }
+  return false;
+}
+
 async function ensureRuntimeSheetForPreloadedSession(
   context: RuntimeApiContext & { playName: string },
   input: {
@@ -597,38 +635,35 @@ async function ensureRuntimeSheetForPreloadedSession(
     return;
   }
   const ensureStartedAt = Date.now();
-  const promise = ensureRuntimeSheet(context, {
-    playName: context.playName,
-    tableNamespace: input.tableNamespace,
-    sheetContract: input.sheetContract,
-  });
-  runtimeSheetEnsureCache.set(cacheKey, {
-    expiresAt: now + RUNTIME_SHEET_ENSURE_CACHE_TTL_MS,
-    promise,
-  });
-  try {
-    await promise;
-    input.timings?.push({
-      phase: 'ensure_sheet_for_preloaded_session',
-      ms: Date.now() - ensureStartedAt,
-    });
-    const recheckStartedAt = Date.now();
-    const readyAfterEnsure = await isRuntimeSheetSchemaReady(input.session, {
+  const promise = (async () => {
+    await ensureRuntimeSheet(context, {
+      playName: context.playName,
+      tableNamespace: input.tableNamespace,
       sheetContract: input.sheetContract,
     });
     input.timings?.push({
-      phase: 'schema_check_after_preloaded_session_ensure',
-      ms: Date.now() - recheckStartedAt,
-      ready: readyAfterEnsure,
+      phase: 'ensure_sheet_for_preloaded_session',
+      ms: Date.now() - ensureStartedAt,
     });
+    const readyAfterEnsure = await waitForRuntimeSheetSchemaReadyAfterEnsure(
+      input.session,
+      {
+        sheetContract: input.sheetContract,
+        timings: input.timings,
+      },
+    );
     if (!readyAfterEnsure) {
-      if (runtimeSheetEnsureCache.get(cacheKey)?.promise === promise) {
-        runtimeSheetEnsureCache.delete(cacheKey);
-      }
       throw new Error(
         `Runtime sheet schema for ctx.dataset("${input.tableNamespace}") is still not ready after ensure_sheet.`,
       );
     }
+  })();
+  runtimeSheetEnsureCache.set(cacheKey, {
+    expiresAt: now + RUNTIME_SHEET_ENSURE_CACHE_TTL_MS,
+    promise,
+  });
+  try {
+    await promise;
   } catch (error) {
     if (runtimeSheetEnsureCache.get(cacheKey)?.promise === promise) {
       runtimeSheetEnsureCache.delete(cacheKey);