deepline 0.1.182 → 0.1.183

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

@@ -1,9 +1,14 @@
 import {
   chooseMapChunkSize,
+  EXECUTION_PLAN_DEFAULTS,
   type ExecutionPlan,
 } from '../../../../shared_libs/play-runtime/execution-plan';
-import { getPlayRuntimeBatchStrategy } from '../../../../shared_libs/play-runtime/play-runtime-batching-registry';
 import { TOOL_CALLING_MAP_CHUNK_SIZE } from '../../../../shared_libs/play-runtime/map-chunk-limits';
+import { getPlayRuntimeBatchStrategy } from '../../../../shared_libs/play-runtime/play-runtime-batching-registry';
+import {
+  WORKER_PLATFORM_SUBREQUESTS_PER_UNBATCHED_TOOL_CALL,
+  WORKER_PLATFORM_SUBREQUEST_SOFT_LIMIT,
+} from './worker-platform-budget';
 import {
   flattenStaticSubsteps,
   getTopLevelPipelineSubsteps,
@@ -14,15 +19,61 @@ import {
 
 export const CACHE_ENABLED_SIMPLE_MAP_CHUNK_SIZE = 10_000;
 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. Very dense waterfalls may still need one-row chunks to stay under
-// the per-invocation subrequest budget.
-export const UNBATCHED_TOOL_SUBREQUESTS_PER_CHUNK_BUDGET = 200;
-// Fresh unbatched tool calls use runtime API, receipt, and coordinator/rate
-// callbacks on the Worker no-batch path. Batch-cap rows by the shared
-// per-call budget rather than a synthetic-tool special case.
-export const SUBREQUESTS_PER_UNBATCHED_TOOL_CALL = 5;
+export const WORKER_SUBREQUEST_SAFE_TOOL_CALLS_PER_CHUNK =
+  TOOL_CALLING_MAP_CHUNK_SIZE;
+export const UNBATCHED_TOOL_SUBREQUESTS_PER_CHUNK_BUDGET =
+  WORKER_PLATFORM_SUBREQUEST_SOFT_LIMIT;
+export const SUBREQUESTS_PER_UNBATCHED_TOOL_CALL =
+  WORKER_PLATFORM_SUBREQUESTS_PER_UNBATCHED_TOOL_CALL;
+
+// A batched tool over a chunk of N rows does not spend the unbatched provider
+// budget for every row. Durable receipt claim/complete/fail are bulk RPCs for
+// the whole drained tool group, but provider execution still happens once per
+// compiled batch. Static planning cannot know input-dependent bucket keys, so
+// it must assume worst-case provider fanout (one compiled batch per row) unless
+// the batching registry grows a proof that all rows share a bucket.
+export const BATCHED_TOOL_SUBREQUESTS_PER_BATCH = 2;
+export const BULK_RECEIPT_SUBREQUESTS_PER_CHUNK = 3;
+// Conservative batch size assumed only when a batchable tool's registry
+// maxBatchSize is unknown. Smaller = more batches = more subrequests = safer.
+export const ASSUMED_BATCH_SIZE_FLOOR = 100;
+const MAX_BATCHABLE_SUBREQUEST_SAFE_ROWS = 1_000_000;
+
+function assumedBatchSizeFor(minBatchableBatchSize: number): number {
+  return minBatchableBatchSize > 0
+    ? minBatchableBatchSize
+    : ASSUMED_BATCH_SIZE_FLOOR;
+}
+
+// Per-chunk subrequest cost of the batchable tool work in a map chunk. Shared
+// by the chunk sizer (inverts it to find safe rows/chunk) and the live budget
+// projection in entry.ts so the two never drift.
+export function estimateBatchedToolChunkSubrequests(input: {
+  batchableToolCallsPerRow: number;
+  coalescedBatchableToolCallsPerRow?: number;
+  rows: number;
+  assumedBatchSize: number;
+}): number {
+  if (input.batchableToolCallsPerRow <= 0 || input.rows <= 0) return 0;
+  const toolCallsPerRow = Math.max(1, input.batchableToolCallsPerRow);
+  const coalescedToolCallsPerRow = Math.min(
+    toolCallsPerRow,
+    Math.max(0, input.coalescedBatchableToolCallsPerRow ?? 0),
+  );
+  const worstCaseToolCallsPerRow = Math.max(
+    0,
+    toolCallsPerRow - coalescedToolCallsPerRow,
+  );
+  const coalescedCompiledBatches =
+    Math.ceil(input.rows / Math.max(1, input.assumedBatchSize)) *
+    coalescedToolCallsPerRow;
+  const worstCaseCompiledBatches = input.rows * worstCaseToolCallsPerRow;
+  return (
+    BATCHED_TOOL_SUBREQUESTS_PER_BATCH *
+      (coalescedCompiledBatches + worstCaseCompiledBatches) +
+    BULK_RECEIPT_SUBREQUESTS_PER_CHUNK * toolCallsPerRow
+  );
+}
 export type WorkerMapChunkPlanInput = {
   mapName: string;
   rowCountHint: number | null;
@@ -39,14 +90,61 @@ type ChunkSizingMap = Pick<
   | 'defaultChunkSize'
   | 'stepsPerChunk'
 > &
-  Partial<Pick<PlanMap, 'externalStepFields'>>;
+  Partial<
+    Pick<PlanMap, 'externalStepFields' | 'stepFields' | 'waterfallStages'>
+  >;
 type ChunkSizingPlan = {
   maps: ChunkSizingMap[];
   toolDeclarations?: ExecutionPlan['toolDeclarations'];
   softWorkflowStepBudget?: number | null;
 };
 
-type MapToolStats = [totalToolCount: number, unbatchedSubrequestCount: number];
+type MapToolStats = [
+  totalToolCount: number,
+  unbatchedToolCount: number,
+  unbatchedSubrequestCount: number,
+  // Smallest registry maxBatchSize across the batchable tools counted so far
+  // (0 when no batchable tool has been seen). Smallest = most batches = most
+  // subrequests, so it is the conservative choice for chunk sizing.
+  minBatchableBatchSize: number,
+  coalescedBatchableToolCount: number,
+];
+type MapControlWorkStats = {
+  childPlaySubmits: number;
+  eventWaits: number;
+};
+
+const EMPTY_CONTROL_WORK_STATS: MapControlWorkStats = {
+  childPlaySubmits: 0,
+  eventWaits: 0,
+};
+
+export type WorkerMapDispatchPlan = {
+  rowsPerChunk: number;
+  estimatedExternalStepsPerRow: number;
+  workEstimate: WorkerMapWorkEstimate;
+  reason:
+    | 'external-pressure'
+    | 'tool-free-large-cache'
+    | 'tool-free-plan'
+    | 'default-plan';
+};
+
+export type WorkerMapWorkEstimate = {
+  cpuRowsPerRow: number;
+  runtimeSheetReadsPerChunk: number;
+  runtimeSheetWritesPerChunk: number;
+  durableReceiptOpsPerRow: number;
+  providerToolCallsPerRow: number;
+  unbatchedProviderToolCallsPerRow: number;
+  // Registry batch size assumed for the batchable tools in this map (smallest
+  // maxBatchSize across them, or ASSUMED_BATCH_SIZE_FLOOR when unknown). Drives
+  // the batched-tool subrequest projection.
+  assumedBatchSize: number;
+  coalescedBatchableProviderToolCallsPerRow: number;
+  childPlaySubmitsPerRow: number;
+  eventWaitsPerRow: number;
+};
 
 function fieldRoot(field: string | null | undefined): string {
   return String(field ?? '').split('.', 1)[0] ?? '';
@@ -71,22 +169,82 @@ function declarationBelongsToMapOutput(
   );
 }
 
-function countTool(toolId: string): MapToolStats {
-  if (getPlayRuntimeBatchStrategy(toolId) !== null) return [1, 0];
-  return [1, SUBREQUESTS_PER_UNBATCHED_TOOL_CALL];
+function countTool(
+  toolId: string,
+  options?: { staticSingleBucket?: boolean },
+): MapToolStats {
+  const batchStrategy = getPlayRuntimeBatchStrategy(toolId);
+  if (batchStrategy !== null) {
+    return [
+      1,
+      0,
+      0,
+      Math.max(1, Math.floor(batchStrategy.maxBatchSize)),
+      options?.staticSingleBucket === true ? 1 : 0,
+    ];
+  }
+  return [1, 1, SUBREQUESTS_PER_UNBATCHED_TOOL_CALL, 0, 0];
+}
+
+function minPositiveBatchSize(a: number, b: number): number {
+  if (a <= 0) return Math.max(0, b);
+  if (b <= 0) return Math.max(0, a);
+  return Math.min(a, b);
+}
+
+function minProviderBranchCoalescedCount(
+  branchStats: readonly MapToolStats[],
+): number {
+  let minCoalesced: number | null = null;
+  for (const [total, , , , coalesced] of branchStats) {
+    if (total <= 0) continue;
+    minCoalesced =
+      minCoalesced === null ? coalesced : Math.min(minCoalesced, coalesced);
+  }
+  return minCoalesced ?? 0;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function hasStaticSingleBatchBucket(input: {
+  toolId: string;
+  paramsSource?: string | null;
+  sourceText?: string | null;
+}): boolean {
+  const strategy = getPlayRuntimeBatchStrategy(input.toolId);
+  const bucketFields = strategy?.bucketKeyPayloadFields;
+  if (!bucketFields || bucketFields.length === 0) return false;
+  const source = [input.paramsSource, input.sourceText]
+    .filter((value): value is string => typeof value === 'string')
+    .join('\n');
+  if (!source) return false;
+  return bucketFields.every((field) => {
+    const pattern = new RegExp(
+      `(^|[^A-Za-z0-9_$])${escapeRegExp(field)}([^A-Za-z0-9_$]|$)`,
+    );
+    return !pattern.test(source);
+  });
 }
 
 function addStats(
-  [total, subrequests]: MapToolStats,
+  [total, unbatched, subrequests, batchSize, coalesced]: MapToolStats,
   stats: MapToolStats,
 ): MapToolStats {
-  return [total + stats[0], subrequests + stats[1]];
+  return [
+    total + stats[0],
+    unbatched + stats[1],
+    subrequests + stats[2],
+    minPositiveBatchSize(batchSize, stats[3]),
+    coalesced + stats[4],
+  ];
 }
 
 function countToolSubsteps(
   substeps: readonly PlayStaticSubstep[],
 ): MapToolStats {
-  let stats: MapToolStats = [0, 0];
+  let stats: MapToolStats = [0, 0, 0, 0, 0];
 
   for (const substep of substeps) {
     stats = addStats(stats, countToolSubstep(substep));
@@ -97,14 +255,29 @@ function countToolSubsteps(
 
 function countToolSubstep(substep: PlayStaticSubstep): MapToolStats {
   if (substep.type === 'tool') {
-    return countTool(substep.toolId);
+    return countTool(substep.toolId, {
+      staticSingleBucket: hasStaticSingleBatchBucket({
+        toolId: substep.toolId,
+        paramsSource: substep.paramsSource,
+        sourceText: substep.sourceText,
+      }),
+    });
   }
 
   if (substep.type === 'waterfall') {
-    let stats: MapToolStats = [0, 0];
+    let stats: MapToolStats = [0, 0, 0, 0, 0];
     for (const step of substep.steps ?? []) {
       if (!step.toolId) continue;
-      stats = addStats(stats, countTool(step.toolId));
+      stats = addStats(
+        stats,
+        countTool(step.toolId, {
+          staticSingleBucket: hasStaticSingleBatchBucket({
+            toolId: step.toolId,
+            paramsSource: step.paramsSource,
+            sourceText: substep.sourceText,
+          }),
+        }),
+      );
     }
     return stats;
   }
@@ -118,13 +291,26 @@ function countToolSubstep(substep: PlayStaticSubstep): MapToolStats {
       const branchStats = substep.branches.map((branch) =>
         countToolSubsteps(branch.steps),
       );
-      return branchStats.reduce<MapToolStats>(
-        ([totalMax, subrequestsMax], [total, subrequests]) => [
+      const maxBranchStats = branchStats.reduce<MapToolStats>(
+        (
+          [totalMax, unbatchedMax, subrequestsMax, batchSizeMin, coalescedMax],
+          [total, unbatched, subrequests, batchSize, coalesced],
+        ) => [
           Math.max(totalMax, total),
+          Math.max(unbatchedMax, unbatched),
           Math.max(subrequestsMax, subrequests),
+          minPositiveBatchSize(batchSizeMin, batchSize),
+          Math.max(coalescedMax, coalesced),
         ],
-        [0, 0],
+        [0, 0, 0, 0, 0],
       );
+      return [
+        maxBranchStats[0],
+        maxBranchStats[1],
+        maxBranchStats[2],
+        maxBranchStats[3],
+        minProviderBranchCoalescedCount(branchStats),
+      ];
     }
     return countToolSubsteps(substep.steps);
   }
@@ -133,7 +319,77 @@ function countToolSubstep(substep: PlayStaticSubstep): MapToolStats {
     return countToolSubsteps(substep.steps ?? []);
   }
 
-  return [0, 0];
+  return [0, 0, 0, 0, 0];
+}
+
+function addControlWorkStats(
+  left: MapControlWorkStats,
+  right: MapControlWorkStats,
+): MapControlWorkStats {
+  return {
+    childPlaySubmits: left.childPlaySubmits + right.childPlaySubmits,
+    eventWaits: left.eventWaits + right.eventWaits,
+  };
+}
+
+function maxControlWorkStats(
+  left: MapControlWorkStats,
+  right: MapControlWorkStats,
+): MapControlWorkStats {
+  return {
+    childPlaySubmits: Math.max(left.childPlaySubmits, right.childPlaySubmits),
+    eventWaits: Math.max(left.eventWaits, right.eventWaits),
+  };
+}
+
+function countControlWorkSubsteps(
+  substeps: readonly PlayStaticSubstep[],
+): MapControlWorkStats {
+  return substeps.reduce<MapControlWorkStats>(
+    (acc, substep) =>
+      addControlWorkStats(acc, countControlWorkSubstep(substep)),
+    EMPTY_CONTROL_WORK_STATS,
+  );
+}
+
+function countControlWorkSubstep(
+  substep: PlayStaticSubstep,
+): MapControlWorkStats {
+  if (substep.type === 'play_call') {
+    return { childPlaySubmits: 1, eventWaits: 0 };
+  }
+
+  if (substep.type === 'tool') {
+    return {
+      childPlaySubmits: 0,
+      eventWaits:
+        substep.isEventWait === true || substep.toolId === 'test_wait_for_event'
+          ? 1
+          : 0,
+    };
+  }
+
+  if (substep.type === 'step_suite') {
+    return countControlWorkSubsteps(substep.steps);
+  }
+
+  if (substep.type === 'control_flow') {
+    if (substep.kind === 'conditional' && substep.branches?.length) {
+      return substep.branches
+        .map((branch) => countControlWorkSubsteps(branch.steps))
+        .reduce<MapControlWorkStats>(
+          (acc, stats) => maxControlWorkStats(acc, stats),
+          EMPTY_CONTROL_WORK_STATS,
+        );
+    }
+    return countControlWorkSubsteps(substep.steps);
+  }
+
+  if (substep.type === 'dataset') {
+    return countControlWorkSubsteps(substep.steps ?? []);
+  }
+
+  return EMPTY_CONTROL_WORK_STATS;
 }
 
 function countStepSuiteTools(
@@ -153,11 +409,8 @@ function countStepSuiteTools(
     conditionalChildren.length < childStats.length / 2
   ) {
     return childStats.reduce<MapToolStats>(
-      ([totalSum, subrequestsSum], { stats: [total, subrequests] }) => [
-        totalSum + total,
-        subrequestsSum + subrequests,
-      ],
-      [0, 0],
+      (acc, { stats }) => addStats(acc, stats),
+      [0, 0, 0, 0, 0],
     );
   }
 
@@ -168,11 +421,8 @@ function countStepSuiteTools(
   });
   if (!sameRoot) {
     return childStats.reduce<MapToolStats>(
-      ([totalSum, subrequestsSum], { stats: [total, subrequests] }) => [
-        totalSum + total,
-        subrequestsSum + subrequests,
-      ],
-      [0, 0],
+      (acc, { stats }) => addStats(acc, stats),
+      [0, 0, 0, 0, 0],
     );
   }
 
@@ -183,18 +433,12 @@ function countStepSuiteTools(
         !(step.type === 'control_flow' && step.kind === 'conditional'),
     )
     .reduce<MapToolStats>(
-      ([totalSum, subrequestsSum], { stats: [total, subrequests] }) => [
-        totalSum + total,
-        subrequestsSum + subrequests,
-      ],
-      [0, 0],
+      (acc, { stats }) => addStats(acc, stats),
+      [0, 0, 0, 0, 0],
     );
   const conditionalStats = conditionalChildren.reduce<MapToolStats>(
-    ([totalSum, subrequestsSum], { stats: [total, subrequests] }) => [
-      totalSum + total,
-      subrequestsSum + subrequests,
-    ],
-    [0, 0],
+    (acc, { stats }) => addStats(acc, stats),
+    [0, 0, 0, 0, 0],
   );
 
   return addStats(unconditionalStats, conditionalStats);
@@ -203,11 +447,26 @@ function countStepSuiteTools(
 function countProducerTools(
   producers: readonly PlayStaticColumnProducer[],
 ): MapToolStats {
-  let stats: MapToolStats = [0, 0];
+  let stats: MapToolStats = [0, 0, 0, 0, 0];
 
   for (const producer of producers) {
     if (producer.kind === 'tool' && producer.toolId) {
-      stats = addStats(stats, countTool(producer.toolId));
+      stats = addStats(
+        stats,
+        countTool(producer.toolId, {
+          staticSingleBucket: hasStaticSingleBatchBucket({
+            toolId: producer.toolId,
+            paramsSource:
+              producer.substep.type === 'tool'
+                ? producer.substep.paramsSource
+                : undefined,
+            sourceText:
+              producer.substep.type === 'tool'
+                ? producer.substep.sourceText
+                : undefined,
+          }),
+        }),
+      );
     }
     if (producer.substep.type === 'waterfall') {
       stats = addStats(stats, countToolSubstep(producer.substep));
@@ -251,17 +510,42 @@ function countMapLocalTools(input: {
   );
   if (!dataset) return null;
 
-  if (dataset.steps?.length) {
-    return countToolSubsteps(dataset.steps);
-  }
-
+  if (dataset.steps?.length) return countToolSubsteps(dataset.steps);
   if (dataset.columns?.length) {
     return countProducerTools(
       dataset.columns.flatMap((column) => column.producers),
     );
   }
+  return [0, 0, 0, 0, 0];
+}
+
+function countMapLocalControlWork(input: {
+  staticPipeline: PlayStaticPipeline | null | undefined;
+  planMap: ChunkSizingMap | null | undefined;
+  mapName: string;
+}): MapControlWorkStats | null {
+  if (!input.staticPipeline || !input.planMap) return null;
+  const planMap = input.planMap;
+  const dataset = flattenStaticSubsteps(
+    getTopLevelPipelineSubsteps(input.staticPipeline),
+  ).find(
+    (substep): substep is Extract<PlayStaticSubstep, { type: 'dataset' }> =>
+      substep.type === 'dataset' &&
+      datasetBelongsToPlanMap(substep, planMap, input.mapName),
+  );
+  if (!dataset) return null;
 
-  return [0, 0];
+  if (dataset.steps?.length) return countControlWorkSubsteps(dataset.steps);
+  if (dataset.columns?.length) {
+    return dataset.columns
+      .flatMap((column) => column.producers)
+      .reduce<MapControlWorkStats>(
+        (acc, producer) =>
+          addControlWorkStats(acc, countControlWorkSubstep(producer.substep)),
+        EMPTY_CONTROL_WORK_STATS,
+      );
+  }
+  return EMPTY_CONTROL_WORK_STATS;
 }
 
 function countFallbackDeclarationTools(input: {
@@ -269,7 +553,7 @@ function countFallbackDeclarationTools(input: {
   outputFields: readonly string[];
   externalStepFields?: readonly string[];
 }): MapToolStats {
-  let stats: MapToolStats = [0, 0];
+  let stats: MapToolStats = [0, 0, 0, 0, 0];
 
   for (const declaration of input.declarations) {
     if (
@@ -292,7 +576,7 @@ function countDeclarationTools(
 ): MapToolStats {
   return declarations.reduce<MapToolStats>(
     (stats, declaration) => addStats(stats, countTool(declaration.toolId)),
-    [0, 0],
+    [0, 0, 0, 0, 0],
   );
 }
 
@@ -347,6 +631,12 @@ function buildStaticChunkSizingPlan(
 export function chooseWorkerMapRowsPerChunk(
   input: WorkerMapChunkPlanInput,
 ): number {
+  return chooseWorkerMapDispatchPlan(input).rowsPerChunk;
+}
+
+export function chooseWorkerMapDispatchPlan(
+  input: WorkerMapChunkPlanInput,
+): WorkerMapDispatchPlan {
   const plan: ChunkSizingPlan | null = input.executionPlan
     ? {
         maps: input.executionPlan.maps,
@@ -365,6 +655,11 @@ export function chooseWorkerMapRowsPerChunk(
     planMap,
     mapName: input.mapName,
   });
+  const staticMapControlWorkStats = countMapLocalControlWork({
+    staticPipeline: input.staticPipeline,
+    planMap,
+    mapName: input.mapName,
+  });
   const mapToolStats =
     staticMapToolStats ??
     (plan && planMap
@@ -375,42 +670,211 @@ export function chooseWorkerMapRowsPerChunk(
         })
       : plan
         ? countDeclarationTools(plan.toolDeclarations ?? [])
-        : [0, 0]);
+        : [0, 0, 0, 0, 0]);
+  const estimatedExternalStepsPerRow = estimateExternalStepsForMap({
+    planMap,
+    mapToolStats,
+  });
+  const workEstimate = estimateMapWork({
+    estimatedExternalStepsPerRow,
+    mapToolStats,
+    controlWorkStats: staticMapControlWorkStats ?? EMPTY_CONTROL_WORK_STATS,
+  });
+  const controlSubrequestsPerRow =
+    workEstimate.childPlaySubmitsPerRow + workEstimate.eventWaitsPerRow;
+  const allProviderCallsAreCoalescedBatchable =
+    workEstimate.providerToolCallsPerRow > 0 &&
+    workEstimate.unbatchedProviderToolCallsPerRow === 0 &&
+    workEstimate.coalescedBatchableProviderToolCallsPerRow >=
+      workEstimate.providerToolCallsPerRow &&
+    controlSubrequestsPerRow === 0;
+  const preferredChunkSize = allProviderCallsAreCoalescedBatchable
+    ? Math.max(
+        planMap?.defaultChunkSize ?? 0,
+        EXECUTION_PLAN_DEFAULTS.largeMapChunkSize,
+      )
+    : planMap?.defaultChunkSize;
   const rowsPerChunk = chooseMapChunkSize({
     totalRows: input.rowCountHint,
     mapCount: Math.max(1, plan?.maps.length ?? 1),
-    stepsPerChunk: planMap?.stepsPerChunk ?? 1,
-    preferredChunkSize: planMap?.defaultChunkSize,
+    stepsPerChunk:
+      estimatedExternalStepsPerRow > 0
+        ? Math.max(estimatedExternalStepsPerRow, planMap?.stepsPerChunk ?? 1)
+        : 1,
+    preferredChunkSize,
     softWorkflowStepBudget: plan?.softWorkflowStepBudget,
   });
+  if (estimatedExternalStepsPerRow > 0 || controlSubrequestsPerRow > 0) {
+    const subrequestSafeRows = subrequestSafeRowsForMap({
+      planMap,
+      mapToolStats,
+      staticMapToolStats,
+      estimatedExternalStepsPerRow,
+      workEstimate,
+    });
+    if (subrequestSafeRows < rowsPerChunk) {
+      const externalPressurePlan: WorkerMapDispatchPlan = {
+        rowsPerChunk: subrequestSafeRows,
+        estimatedExternalStepsPerRow,
+        workEstimate,
+        reason: 'external-pressure',
+      };
+      return externalPressurePlan;
+    }
+    return {
+      rowsPerChunk,
+      estimatedExternalStepsPerRow,
+      workEstimate,
+      reason: 'external-pressure',
+    };
+  }
 
-  const toolFreeSimpleMap =
-    !!planMap && planMap.stepsPerChunk === 1 && mapToolStats[0] === 0;
+  const toolFreeMap = !!planMap && mapToolStats[0] === 0;
+  const toolFreeSimpleMap = toolFreeMap && planMap.stepsPerChunk === 1;
   if (
     toolFreeSimpleMap &&
     (input.rowCountHint === null ||
       input.rowCountHint >= CACHE_ENABLED_SIMPLE_MAP_CHUNK_SIZE)
   ) {
-    return Math.max(rowsPerChunk, CACHE_ENABLED_SIMPLE_MAP_CHUNK_SIZE);
-  }
-
-  if (mapToolStats[1] > 0) {
-    const unbatchedSubrequestsPerRow =
-      staticMapToolStats !== null
-        ? mapToolStats[1]
-        : Math.max(
-            (planMap?.stepsPerChunk ?? 1) * SUBREQUESTS_PER_UNBATCHED_TOOL_CALL,
-            mapToolStats[1],
-          );
-    const unbatchedToolRowsPerChunk = Math.max(
-      1,
-      Math.floor(
-        UNBATCHED_TOOL_SUBREQUESTS_PER_CHUNK_BUDGET /
-          unbatchedSubrequestsPerRow,
-      ),
+    const largeRowsPerChunk = Math.max(
+      rowsPerChunk,
+      CACHE_ENABLED_SIMPLE_MAP_CHUNK_SIZE,
     );
-    return Math.min(rowsPerChunk, unbatchedToolRowsPerChunk);
+    return {
+      rowsPerChunk: largeRowsPerChunk,
+      estimatedExternalStepsPerRow: 0,
+      workEstimate,
+      reason: 'tool-free-large-cache',
+    };
   }
 
-  return rowsPerChunk;
+  return {
+    rowsPerChunk,
+    estimatedExternalStepsPerRow: 0,
+    workEstimate,
+    reason: toolFreeMap ? 'tool-free-plan' : 'default-plan',
+  };
+}
+
+function estimateMapWork(input: {
+  estimatedExternalStepsPerRow: number;
+  mapToolStats: MapToolStats;
+  controlWorkStats: MapControlWorkStats;
+}): WorkerMapWorkEstimate {
+  return {
+    cpuRowsPerRow: 1,
+    runtimeSheetReadsPerChunk: 1,
+    runtimeSheetWritesPerChunk: 1,
+    durableReceiptOpsPerRow: input.estimatedExternalStepsPerRow,
+    providerToolCallsPerRow: input.mapToolStats[0],
+    unbatchedProviderToolCallsPerRow: input.mapToolStats[1],
+    assumedBatchSize: assumedBatchSizeFor(input.mapToolStats[3]),
+    coalescedBatchableProviderToolCallsPerRow: input.mapToolStats[4],
+    childPlaySubmitsPerRow: input.controlWorkStats.childPlaySubmits,
+    eventWaitsPerRow: input.controlWorkStats.eventWaits,
+  };
+}
+
+function estimateExternalStepsForMap(input: {
+  planMap: ChunkSizingMap | undefined;
+  mapToolStats: MapToolStats;
+}): number {
+  if (!input.planMap) return input.mapToolStats[0];
+  const explicitExternalSteps = Array.isArray(input.planMap.externalStepFields)
+    ? input.planMap.externalStepFields.length
+    : 0;
+  return Math.max(explicitExternalSteps, input.mapToolStats[0]);
+}
+
+function subrequestSafeRowsForMap(input: {
+  planMap: ChunkSizingMap | undefined;
+  mapToolStats: MapToolStats;
+  staticMapToolStats: MapToolStats | null;
+  estimatedExternalStepsPerRow: number;
+  workEstimate: WorkerMapWorkEstimate;
+}): number {
+  const hasToolWork = input.mapToolStats[0] > 0;
+  const unbatchedToolCount = input.mapToolStats[1];
+  const unbatchedSubrequestCount = input.mapToolStats[2];
+  const controlSubrequestsPerRow =
+    input.workEstimate.childPlaySubmitsPerRow +
+    input.workEstimate.eventWaitsPerRow;
+  const controlRows =
+    controlSubrequestsPerRow > 0
+      ? Math.max(
+          1,
+          Math.floor(
+            (UNBATCHED_TOOL_SUBREQUESTS_PER_CHUNK_BUDGET -
+              input.workEstimate.runtimeSheetReadsPerChunk -
+              input.workEstimate.runtimeSheetWritesPerChunk) /
+              controlSubrequestsPerRow,
+          ),
+        )
+      : Number.POSITIVE_INFINITY;
+  // Largest chunk whose batched tool work stays under the subrequest ceiling.
+  // Invert estimateBatchedToolChunkSubrequests. Static planning does not know
+  // bucket cardinality, so it assumes worst-case provider fanout (one compiled
+  // batch per row per batchable tool call) while keeping durable receipt RPCs
+  // fixed per drained tool group.
+  const batchableToolRows =
+    hasToolWork && unbatchedToolCount <= 0
+      ? (() => {
+          const batchableToolCallsPerRow = input.mapToolStats[0];
+          const costForRows = (rows: number) =>
+            estimateBatchedToolChunkSubrequests({
+              batchableToolCallsPerRow,
+              coalescedBatchableToolCallsPerRow:
+                input.workEstimate.coalescedBatchableProviderToolCallsPerRow,
+              rows,
+              assumedBatchSize: input.workEstimate.assumedBatchSize,
+            }) +
+            input.workEstimate.runtimeSheetReadsPerChunk +
+            input.workEstimate.runtimeSheetWritesPerChunk;
+          if (costForRows(1) > UNBATCHED_TOOL_SUBREQUESTS_PER_CHUNK_BUDGET) {
+            return 1;
+          }
+          let low = 1;
+          let high = MAX_BATCHABLE_SUBREQUEST_SAFE_ROWS;
+          while (low < high) {
+            const mid = Math.ceil((low + high) / 2);
+            if (
+              costForRows(mid) <= UNBATCHED_TOOL_SUBREQUESTS_PER_CHUNK_BUDGET
+            ) {
+              low = mid;
+            } else {
+              high = mid - 1;
+            }
+          }
+          return low;
+        })()
+      : Number.POSITIVE_INFINITY;
+  if (hasToolWork && unbatchedToolCount <= 0) {
+    return Math.min(batchableToolRows, controlRows);
+  }
+  const genericRows =
+    input.estimatedExternalStepsPerRow > 0
+      ? Math.max(
+          1,
+          Math.floor(
+            WORKER_SUBREQUEST_SAFE_TOOL_CALLS_PER_CHUNK /
+              input.estimatedExternalStepsPerRow,
+          ),
+        )
+      : Number.POSITIVE_INFINITY;
+  if (unbatchedToolCount <= 0) return Math.min(genericRows, controlRows);
+  const unbatchedSubrequestsPerRow =
+    input.staticMapToolStats !== null
+      ? unbatchedSubrequestCount
+      : Math.max(
+          (input.planMap?.stepsPerChunk ?? 1) *
+            SUBREQUESTS_PER_UNBATCHED_TOOL_CALL,
+          unbatchedSubrequestCount,
+        );
+  const unbatchedRows = Math.max(
+    1,
+    Math.floor(
+      UNBATCHED_TOOL_SUBREQUESTS_PER_CHUNK_BUDGET / unbatchedSubrequestsPerRow,
+    ),
+  );
+  return Math.min(unbatchedRows, controlRows);
 }