deepline 0.1.179 → 0.1.180

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

@@ -19,17 +19,57 @@ export type ChunkExecutionResult<TRequest, TResult> = {
   error?: unknown;
 };
 
+function planExecutionChunks<TRequest>(
+  requests: TRequest[],
+  batchSize: number,
+  maxChunkWeight: number | undefined,
+  weightOf: ((request: TRequest) => number) | undefined,
+): TRequest[][] {
+  const maxUnits = Math.max(1, Math.floor(batchSize));
+  const weightCap =
+    maxChunkWeight != null && weightOf != null
+      ? Math.max(1, Math.floor(maxChunkWeight))
+      : null;
+  const chunks: TRequest[][] = [];
+  let current: TRequest[] = [];
+  let weight = 0;
+  for (const request of requests) {
+    if (
+      current.length > 0 &&
+      (current.length >= maxUnits ||
+        (weightCap != null && weight >= weightCap))
+    ) {
+      chunks.push(current);
+      current = [];
+      weight = 0;
+    }
+    current.push(request);
+    if (weightCap != null && weightOf != null) {
+      weight += Math.max(1, Math.floor(weightOf(request)));
+    }
+  }
+  if (current.length > 0) chunks.push(current);
+  return chunks;
+}
+
 export async function executeChunkedRequests<TRequest, TResult>(input: {
   requests: TRequest[];
   batchSize: number;
+  maxChunkWeight?: number;
+  weightOf?: (request: TRequest) => number;
   execute: (request: TRequest) => Promise<TResult>;
   onChunkComplete?: (
     results: Array<ChunkExecutionResult<TRequest, TResult>>,
   ) => void | Promise<void>;
 }): Promise<Array<ChunkExecutionResult<TRequest, TResult>>> {
   const results: Array<ChunkExecutionResult<TRequest, TResult>> = [];
-  for (let start = 0; start < input.requests.length; start += input.batchSize) {
-    const chunk = input.requests.slice(start, start + input.batchSize);
+  const chunks = planExecutionChunks(
+    input.requests,
+    input.batchSize,
+    input.maxChunkWeight,
+    input.weightOf,
+  );
+  for (const chunk of chunks) {
     let notifyChain: Promise<void> = Promise.resolve();
     const notify = async (
       entry: ChunkExecutionResult<TRequest, TResult>,

package/dist/bundling-sources/apps/play-runner-workers/src/runtime/tool-receipts.ts

@@ -29,6 +29,116 @@ export function canReclaimTimedOutWorkerToolReceipt(input: {
   return Boolean(currentRunId);
 }
 
+/**
+ * Staleness floor for the dead-owner reclaim fast path. A `running` receipt
+ * left by a different run whose last write is older than this is treated as an
+ * orphan from a dead run — no live worker will ever complete it. Running
+ * receipts carry no heartbeat (updatedAt is frozen at claim time), so this is a
+ * conservative constant, not a heartbeat multiple.
+ */
+export const RUNNING_RECEIPT_DEAD_OWNER_STALENESS_MS = 60_000;
+
+/**
+ * Decide whether a `running` receipt should be reclaimed IMMEDIATELY, skipping
+ * the completion poll.
+ *
+ * The poll (`waitForCompletedRuntimeReceipt`) issues one service-binding
+ * subrequest per 250ms tick, up to the receipt's wait budget (~1320 ticks for a
+ * 5.5-minute default). On resume, a map can carry many receipts left `running`
+ * by a DEAD prior run; polling each one burns its full tick budget waiting on a
+ * receipt no live worker will complete, which blows Cloudflare's ~1000
+ * subrequests-per-invocation budget and kills the resume with
+ * "Too many subrequests by single Worker invocation" (prod resume deaths
+ * 20260703t230209 / 20260703t232104).
+ *
+ * A receipt is a dead-owner orphan when it is owned by a DIFFERENT run (a
+ * same-run `running` is this run replaying — its owner may still be live) and
+ * its last write is stale (or missing entirely — a live owner would carry a
+ * recent claim timestamp). Those reclaim immediately, matching the dispatch
+ * code's own contract ("on resume it reclaims and re-executes"). A live or
+ * freshly-claimed owner keeps the poll.
+ */
+export function shouldReclaimRunningReceiptWithoutPolling(input: {
+  ownerRunId?: string | null;
+  currentRunId: string;
+  updatedAt?: string | null;
+  nowMs?: number;
+  stalenessFloorMs?: number;
+}): boolean {
+  const currentRunId = input.currentRunId.trim();
+  const ownerRunId = input.ownerRunId?.trim() ?? '';
+  // Only a receipt owned by a different run can be a dead prior-run orphan.
+  if (!currentRunId || !ownerRunId || ownerRunId === currentRunId) return false;
+  const floorMs =
+    input.stalenessFloorMs ?? RUNNING_RECEIPT_DEAD_OWNER_STALENESS_MS;
+  // No freshness signal at all: treat as stale. A live owner would carry a
+  // recent claim timestamp; an orphan from a dead run may carry none.
+  if (!input.updatedAt) return true;
+  const updatedAtMs = Date.parse(input.updatedAt);
+  if (!Number.isFinite(updatedAtMs)) return true;
+  const now = input.nowMs ?? Date.now();
+  return now - updatedAtMs >= floorMs;
+}
+
+/** Metadata a `running` receipt carries about its owner and last write. */
+export interface RunningReceiptOwnershipInput {
+  ownerRunId?: string | null;
+  currentRunId: string;
+  updatedAt?: string | null;
+  nowMs?: number;
+  stalenessFloorMs?: number;
+}
+
+/** Outcome of polling a `running` receipt for completion. */
+export type RunningReceiptPollOutcome =
+  /** The poll saw the receipt complete and already resolved the group. */
+  | { kind: 'completed' }
+  /** The poll timed out; the receipt is still `running`. */
+  | { kind: 'timed_out'; error: unknown }
+  /** The poll failed for a non-timeout reason (e.g. the receipt failed). */
+  | { kind: 'errored'; error: unknown };
+
+/**
+ * Orchestrate the resume-time handling of a `running` receipt: reclaim it
+ * immediately when it is a dead-owner orphan, otherwise poll for completion and
+ * only reclaim after the poll times out. Kept as a pure, dependency-injected
+ * function (the poll and reclaim side effects are passed in) so the
+ * "skip the poll for a dead owner" decision is unit-testable with a poll counter
+ * — the Worker scheduler that owns the real effects imports `cloudflare:workers`
+ * and cannot be loaded under vitest.
+ *
+ * Behavior (must match the scheduler's prior inline logic exactly):
+ * - dead-owner + reclaim-eligible → `reclaim` now, never polling;
+ * - otherwise `poll`; on `completed` the group is already resolved (return []);
+ *   on a non-timeout error `reject` and stop; on timeout, `reclaim` if still
+ *   eligible else `reject` with the timeout error.
+ */
+export async function reclaimRunningReceiptGroupAfterWait<TClaimed>(input: {
+  ownership: RunningReceiptOwnershipInput;
+  timeoutError: unknown;
+  poll: () => Promise<RunningReceiptPollOutcome>;
+  reclaim: (rejectionOnFallthrough: unknown) => Promise<TClaimed[]>;
+  reject: (error: unknown) => void;
+}): Promise<TClaimed[]> {
+  if (
+    shouldReclaimRunningReceiptWithoutPolling(input.ownership) &&
+    canReclaimTimedOutWorkerToolReceipt(input.ownership)
+  ) {
+    return await input.reclaim(input.timeoutError);
+  }
+  const outcome = await input.poll();
+  if (outcome.kind === 'completed') return [];
+  if (outcome.kind === 'errored') {
+    input.reject(outcome.error);
+    return [];
+  }
+  if (!canReclaimTimedOutWorkerToolReceipt(input.ownership)) {
+    input.reject(outcome.error);
+    return [];
+  }
+  return await input.reclaim(outcome.error);
+}
+
 export function canReclaimFailedWorkerToolReceipt(input: {
   error?: string | null;
 }): boolean {
@@ -36,7 +146,8 @@ export function canReclaimFailedWorkerToolReceipt(input: {
   return Boolean(
     error &&
     (/\b(cancell?ed|aborted|terminate[d]?)\b/i.test(error) ||
-      /\bmax runtime\b/i.test(error)),
+      /\bmax runtime\b/i.test(error) ||
+      /persistence failure|durable receipts? could not be marked/i.test(error)),
   );
 }
 

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

@@ -642,6 +642,98 @@ function decodeBase64Bytes(value: string): Uint8Array {
   return bytes;
 }
 
+/**
+ * A staged-file upload target minted by POST /api/v2/plays/files/stage/mint.
+ * When `alreadyStaged` is true the server already holds the content-addressed
+ * object and `uploadUrl` is null; otherwise the client PUTs the body to
+ * `uploadUrl` with `uploadHeaders`.
+ */
+type MintStagedFileUpload = {
+  logicalPath: string;
+  contentHash: string;
+  ref: PlayStagedFileRef;
+  alreadyStaged: boolean;
+  uploadUrl: string | null;
+  uploadHeaders: Record<string, string> | null;
+  uploadExpiresAt: string | null;
+};
+
+// Legacy multipart staging proxies the body through the serverless function,
+// which caps request bodies near 4.5MB. Stay conservatively below that so the
+// fail-loud guidance fires before the platform returns an opaque 413.
+const STAGE_LEGACY_MULTIPART_MAX_BYTES = 4_000_000;
+
+const STAGE_DIRECT_UPLOAD_MAX_ATTEMPTS = 3;
+
+function stagedUploadIdentity(logicalPath: string, contentHash: string): string {
+  return `${contentHash}:${logicalPath}`;
+}
+
+function isStagedUploadMintUnsupported(error: unknown): boolean {
+  // A server without the mint route returns 404. Treat only that as
+  // "unsupported, fall back"; every other failure propagates.
+  return error instanceof DeeplineError && error.statusCode === 404;
+}
+
+function formatMegabytes(bytes: number): string {
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+async function uploadStagedFileToPresignedUrl(input: {
+  url: string;
+  headers: Record<string, string>;
+  body: Uint8Array;
+  logicalPath: string;
+}): Promise<void> {
+  // Wrap the bytes in a fresh Blob so the body is a BodyInit and the upload is
+  // re-runnable across retries (a consumed stream would not be).
+  const arrayBuffer = input.body.buffer.slice(
+    input.body.byteOffset,
+    input.body.byteOffset + input.body.byteLength,
+  ) as ArrayBuffer;
+  let lastError: unknown;
+  for (
+    let attempt = 1;
+    attempt <= STAGE_DIRECT_UPLOAD_MAX_ATTEMPTS;
+    attempt += 1
+  ) {
+    try {
+      const response = await fetch(input.url, {
+        method: 'PUT',
+        headers: input.headers,
+        body: new Blob([arrayBuffer]),
+      });
+      if (response.ok) {
+        return;
+      }
+      const text = await response.text().catch(() => '');
+      lastError = new DeeplineError(
+        `Direct storage upload of ${input.logicalPath} failed: ${response.status} ${text.slice(0, 200)}`,
+        response.status,
+        'STAGED_FILE_UPLOAD_FAILED',
+        { logicalPath: input.logicalPath },
+      );
+      // 4xx (other than throttling) will not recover on retry.
+      if (response.status < 500 && response.status !== 429) {
+        break;
+      }
+    } catch (error) {
+      lastError = error;
+    }
+    if (attempt < STAGE_DIRECT_UPLOAD_MAX_ATTEMPTS) {
+      await sleep(250 * attempt);
+    }
+  }
+  throw lastError instanceof Error
+    ? lastError
+    : new DeeplineError(
+        `Direct storage upload of ${input.logicalPath} failed.`,
+        undefined,
+        'STAGED_FILE_UPLOAD_FAILED',
+        { logicalPath: input.logicalPath },
+      );
+}
+
 function readStringArray(value: unknown): string[] {
   return Array.isArray(value)
     ? value.filter((line): line is string => typeof line === 'string')
@@ -1265,6 +1357,34 @@ export class DeeplineClient {
     });
   }
 
+  /**
+   * Re-establish this workspace's tenant storage contract: role/DB connect
+   * grants plus materialized table grants. Org-admin only. Use when a run fails
+   * with WORKSPACE_STORAGE_NOT_READY.
+   */
+  async repairIngestionStorage(input?: { provider?: string }): Promise<{
+    connection_grants: { runtime_role: string; customer_db_role: string };
+    repaired: unknown[];
+    count: number;
+  }> {
+    // forbiddenAsApiError: the repair route returns a meaningful 403 for
+    // non-org-admin callers. Without it, http.ts collapses 403 into a generic
+    // AuthError (statusCode 401) and the CLI's "requires org admin" branch
+    // could never fire.
+    return this.http.post<{
+      connection_grants: { runtime_role: string; customer_db_role: string };
+      repaired: unknown[];
+      count: number;
+    }>(
+      '/api/v2/ingestion/repair',
+      {
+        ...(input?.provider ? { provider: input.provider } : {}),
+      },
+      undefined,
+      { forbiddenAsApiError: true },
+    );
+  }
+
   // ——————————————————————————————————————————————————————————
   // Plays — submission and lifecycle
   // ——————————————————————————————————————————————————————————
@@ -1829,6 +1949,123 @@ export class DeeplineClient {
       bytes: number;
     }>,
   ): Promise<PlayStagedFileRef[]> {
+    // Primary path: mint presigned R2 PUT targets and upload each file body
+    // straight to storage. This bypasses the ~4.5MB serverless request-body
+    // limit that the legacy multipart proxy hits (413
+    // FUNCTION_PAYLOAD_TOO_LARGE), so large enriched CSVs stage and resume.
+    let uploads: MintStagedFileUpload[];
+    try {
+      uploads = await this.mintStagedPlayFileUploads(
+        files.map((file) => ({
+          logicalPath: file.logicalPath,
+          contentHash: file.contentHash,
+          contentType: file.contentType,
+          bytes: file.bytes,
+        })),
+      );
+    } catch (error) {
+      if (isStagedUploadMintUnsupported(error)) {
+        // The connected server predates direct-to-storage staging. Fall back to
+        // the legacy multipart proxy, but only for files small enough to clear
+        // the serverless body limit; larger files fail loud with guidance.
+        return this.stagePlayFilesViaMultipart(files);
+      }
+      throw error;
+    }
+
+    const uploadByIdentity = new Map<string, MintStagedFileUpload>();
+    for (const upload of uploads) {
+      uploadByIdentity.set(
+        stagedUploadIdentity(upload.logicalPath, upload.contentHash),
+        upload,
+      );
+    }
+
+    await Promise.all(
+      files.map(async (file) => {
+        const upload = uploadByIdentity.get(
+          stagedUploadIdentity(file.logicalPath, file.contentHash),
+        );
+        if (!upload) {
+          throw new DeeplineError(
+            `The staging server did not return an upload target for ${file.logicalPath}.`,
+            undefined,
+            'STAGED_FILE_MINT_INCOMPLETE',
+          );
+        }
+        if (upload.alreadyStaged || !upload.uploadUrl) {
+          return;
+        }
+        await uploadStagedFileToPresignedUrl({
+          url: upload.uploadUrl,
+          headers: upload.uploadHeaders ?? {
+            'content-type': file.contentType,
+          },
+          body: decodeBase64Bytes(file.contentBase64),
+          logicalPath: file.logicalPath,
+        });
+      }),
+    );
+
+    return files.map((file) => {
+      const upload = uploadByIdentity.get(
+        stagedUploadIdentity(file.logicalPath, file.contentHash),
+      );
+      if (!upload) {
+        throw new DeeplineError(
+          `The staging server did not return an upload target for ${file.logicalPath}.`,
+          undefined,
+          'STAGED_FILE_MINT_INCOMPLETE',
+        );
+      }
+      return upload.ref;
+    });
+  }
+
+  /**
+   * Mint short-lived presigned upload targets for staged play files.
+   *
+   * Internal primitive used by {@link stagePlayFiles}. The server returns an
+   * already-staged ref (no upload needed) for content-addressed files it
+   * already holds, or a presigned PUT URL the caller uploads the body to.
+   */
+  async mintStagedPlayFileUploads(
+    files: Array<{
+      logicalPath: string;
+      contentHash: string;
+      contentType: string;
+      bytes: number;
+    }>,
+  ): Promise<MintStagedFileUpload[]> {
+    const response = await this.http.post<{
+      uploads: MintStagedFileUpload[];
+    }>('/api/v2/plays/files/stage/mint', { files });
+    return response.uploads ?? [];
+  }
+
+  private async stagePlayFilesViaMultipart(
+    files: Array<{
+      logicalPath: string;
+      contentBase64: string;
+      contentHash: string;
+      contentType: string;
+      bytes: number;
+    }>,
+  ): Promise<PlayStagedFileRef[]> {
+    for (const file of files) {
+      if (file.bytes > STAGE_LEGACY_MULTIPART_MAX_BYTES) {
+        throw new DeeplineError(
+          `Cannot stage ${file.logicalPath} (${formatMegabytes(file.bytes)}): the connected Deepline server does not support direct-to-storage uploads, and this file exceeds the ~4.5MB request-body limit the legacy upload path is subject to. Update the Deepline server (or target code.deepline.com) to stage files this large.`,
+          413,
+          'STAGED_FILE_TOO_LARGE_FOR_LEGACY_UPLOAD',
+          {
+            logicalPath: file.logicalPath,
+            bytes: file.bytes,
+            maxBytes: STAGE_LEGACY_MULTIPART_MAX_BYTES,
+          },
+        );
+      }
+    }
     const buildFormData = () => {
       const formData = new FormData();
       formData.set(

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

@@ -38,6 +38,8 @@ import {
 const MAX_DIAGNOSTIC_HEADER_LENGTH = 120;
 const COWORK_NETWORK_HINT =
   'Claude Cowork appears to be running Deepline in a network-restricted sandbox. In Claude Desktop, open Settings > Capabilities, turn on Allow network egress, and set Domain allowlist to All domains for the Cowork session.';
+const REQUEST_TIMEOUT_MARKER = Symbol('deeplineRequestTimeout');
+const REQUEST_ABORT_MARKER = Symbol('deeplineRequestAbort');
 
 interface RequestOptions {
   method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -72,6 +74,83 @@ interface StreamOptions {
   signal?: AbortSignal;
 }
 
+type RequestAbortTaggedError = Error & {
+  [REQUEST_TIMEOUT_MARKER]?: number;
+  [REQUEST_ABORT_MARKER]?: true;
+};
+
+function normalizeRequestAbortError(
+  error: unknown,
+  input: { timeoutMs: number; timedOut: boolean },
+): Error {
+  const normalized = error instanceof Error ? error : new Error(String(error));
+  const tagged = normalized as RequestAbortTaggedError;
+  if (input.timedOut) {
+    tagged[REQUEST_TIMEOUT_MARKER] = input.timeoutMs;
+  } else if (isAbortLikeError(normalized)) {
+    tagged[REQUEST_ABORT_MARKER] = true;
+  }
+  return normalized;
+}
+
+function isAbortLikeError(error: Error): boolean {
+  const name = error.name.toLowerCase();
+  const message = error.message.toLowerCase();
+  return (
+    name === 'aborterror' ||
+    message.includes('operation was aborted') ||
+    message === 'aborted'
+  );
+}
+
+function mapNetworkError(
+  baseUrl: string,
+  error: Error | null,
+  targetLabel: string,
+): {
+  message: string;
+  code: string;
+  details?: Record<string, unknown>;
+} {
+  const tagged = error as RequestAbortTaggedError | null;
+  const timeoutMs = tagged?.[REQUEST_TIMEOUT_MARKER];
+  if (typeof timeoutMs === 'number') {
+    return {
+      message: `Request to ${targetLabel} timed out after ${timeoutMs}ms while waiting for a response.`,
+      code: 'NETWORK_TIMEOUT',
+      details: { timeoutMs, target: targetLabel },
+    };
+  }
+  if (tagged?.[REQUEST_ABORT_MARKER]) {
+    return {
+      message: `Request to ${targetLabel} was aborted before it completed.`,
+      code: 'NETWORK_ABORTED',
+    };
+  }
+  return {
+    message: error?.message
+      ? `Unable to connect to ${baseUrl}. ${error.message}`
+      : `Unable to connect to ${baseUrl}. Is the computer able to access the url?`,
+    code: 'NETWORK_ERROR',
+  };
+}
+
+function describeRequestTarget(path: string): string {
+  const toolExecuteMatch = path.match(
+    /^\/api\/v2\/integrations\/([^/?#]+)\/execute(?:[/?#]|$)/,
+  );
+  if (toolExecuteMatch) {
+    return providerLabelFromToolId(decodeURIComponent(toolExecuteMatch[1]));
+  }
+  return 'Deepline';
+}
+
+function providerLabelFromToolId(toolId: string): string {
+  const normalized = toolId.trim().toLowerCase();
+  const provider = normalized.split(/[_:./-]+/)[0];
+  return provider || normalized || 'provider';
+}
+
 /**
  * Low-level HTTP client used internally by {@link DeeplineClient}.
  *
@@ -246,10 +325,12 @@ export class HttpClient {
 
       for (const candidateUrl of candidateUrls) {
         const controller = new AbortController();
-        const timeoutId = setTimeout(
-          () => controller.abort(),
-          options?.timeout ?? this.config.timeout,
-        );
+        const timeoutMs = options?.timeout ?? this.config.timeout;
+        let requestTimedOut = false;
+        const timeoutId = setTimeout(() => {
+          requestTimedOut = true;
+          controller.abort();
+        }, timeoutMs);
 
         try {
           const response = await fetch(candidateUrl, {
@@ -375,7 +456,10 @@ export class HttpClient {
             lastError = error;
             break;
           }
-          lastError = error instanceof Error ? error : new Error(String(error));
+          lastError = normalizeRequestAbortError(error, {
+            timeoutMs,
+            timedOut: requestTimedOut,
+          });
         }
       }
 
@@ -385,10 +469,17 @@ export class HttpClient {
     if (lastError instanceof DeeplineError) {
       throw lastError;
     }
-    const errorMessage = lastError?.message
-      ? `Unable to connect to ${baseUrl}. ${lastError.message}`
-      : `Unable to connect to ${baseUrl}. Is the computer able to access the url?`;
-    throw new DeeplineError(withCoworkNetworkHint(errorMessage));
+    const mappedNetworkError = mapNetworkError(
+      baseUrl,
+      lastError,
+      describeRequestTarget(path),
+    );
+    throw new DeeplineError(
+      withCoworkNetworkHint(mappedNetworkError.message),
+      undefined,
+      mappedNetworkError.code,
+      mappedNetworkError.details,
+    );
   }
 
   /**

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

@@ -105,10 +105,10 @@ export const SDK_RELEASE = {
   // 0.1.154 removes the short-lived generated enrich StepOptions recompute
   // fields shipped in 0.1.153.
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
-  version: '0.1.179',
+  version: '0.1.180',
   apiContract: '2026-06-dataset-handle-results-hard-cutover',
   supportPolicy: {
-    latest: '0.1.179',
+    latest: '0.1.180',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
     commandMinimumSupported: [

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

@@ -26,9 +26,60 @@ export interface CompiledRequestBatch<TRequest> {
   splitResults: (value: unknown) => Array<unknown | null>;
 }
 
+/**
+ * Plan chunk boundaries. A chunk closes when it reaches `batchSize` units OR,
+ * when a `maxChunkWeight` + `weightOf` exposure cap is supplied, when its
+ * cumulative weight reaches that cap — whichever comes first. A single unit that
+ * alone exceeds either limit still forms its own chunk (batches are atomic and
+ * never split). The weight cap is the persistence-latch dispatch-wave bound:
+ * without it a large `batchSize` (provider-pacing hint) would let a whole
+ * chunk's provider calls bill before the latch can gate the rest.
+ */
+function planExecutionChunks<TRequest>(
+  requests: TRequest[],
+  batchSize: number,
+  maxChunkWeight: number | undefined,
+  weightOf: ((request: TRequest) => number) | undefined,
+): TRequest[][] {
+  const maxUnits = Math.max(1, Math.floor(batchSize));
+  const weightCap =
+    maxChunkWeight != null && weightOf != null
+      ? Math.max(1, Math.floor(maxChunkWeight))
+      : null;
+  const chunks: TRequest[][] = [];
+  let current: TRequest[] = [];
+  let weight = 0;
+  for (const request of requests) {
+    if (
+      current.length > 0 &&
+      (current.length >= maxUnits ||
+        (weightCap != null && weight >= weightCap))
+    ) {
+      chunks.push(current);
+      current = [];
+      weight = 0;
+    }
+    current.push(request);
+    if (weightCap != null && weightOf != null) {
+      weight += Math.max(1, Math.floor(weightOf(request)));
+    }
+  }
+  if (current.length > 0) chunks.push(current);
+  return chunks;
+}
+
 export async function executeChunkedRequests<TRequest, TResult>(input: {
   requests: TRequest[];
   batchSize: number;
+  /**
+   * Optional exposure cap: the maximum cumulative `weightOf` a single chunk may
+   * dispatch before the caller's per-unit latch check runs again. Set to
+   * PROVIDER_DISPATCH_WAVE_SIZE by the batch dispatch paths so a persistence
+   * failure prevents the rest of a large batch group instead of billing it all.
+   */
+  maxChunkWeight?: number;
+  /** Per-request weight toward `maxChunkWeight` (e.g. batch member count). */
+  weightOf?: (request: TRequest) => number;
   execute: (request: TRequest) => Promise<TResult>;
   /**
    * Loud per-request failure hook. A rejected request is recorded as a
@@ -43,8 +94,13 @@ export async function executeChunkedRequests<TRequest, TResult>(input: {
 }): Promise<Array<ChunkExecutionResult<TRequest, TResult>>> {
   const results: Array<ChunkExecutionResult<TRequest, TResult>> = [];
 
-  for (let start = 0; start < input.requests.length; start += input.batchSize) {
-    const chunk = input.requests.slice(start, start + input.batchSize);
+  const chunks = planExecutionChunks(
+    input.requests,
+    input.batchSize,
+    input.maxChunkWeight,
+    input.weightOf,
+  );
+  for (const chunk of chunks) {
     let notifyChain: Promise<void> = Promise.resolve();
     const notify = async (
       entry: ChunkExecutionResult<TRequest, TResult>,