deepline 0.3.183 → 0.3.185

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/postgres.ts

@@ -269,7 +269,10 @@ const POSTGRES_SCHEDULER_SCHEMA_INIT_STATEMENT_TIMEOUT_MS = 60_000;
 // deployment retries do not re-enter the old cross-table DDL transaction.
 // v45 adds the bucket-leading expiration index used by rate-reservation
 // cleanup. Shared schemas build it concurrently through the deploy migrator.
-export const POSTGRES_SCHEDULER_SCHEMA_VERSION = 45;
+// v46 adds a bounded provider-scope Retry-After hold with shared adaptive-rate
+// state. The scope owns learning and dispatch across runs and tool rules;
+// existing deadline rows expand additively and initialize on their first seed.
+export const POSTGRES_SCHEDULER_SCHEMA_VERSION = 46;
 const POSTGRES_SCHEDULER_SCHEMA_MIGRATIONS_TABLE =
   'scheduler_schema_migrations';
 export const POSTGRES_SCHEDULER_OPEN_RECOVERY_INDEX =
@@ -1065,6 +1068,8 @@ export type PostgresSchedulerSchemaShapeRequirements = Readonly<{
   cronScheduleSchema?: boolean;
   /** v43 added per-run fair-share tracking for rate buckets; v42 ignores it. */
   rateRequesterFairShare?: boolean;
+  /** v45 added durable Retry-After holds shared across rules and runs. */
+  rateScopeRetryAfter?: boolean;
 }>;
 
 export async function hasCurrentPostgresSchedulerSchemaShape(
@@ -1371,6 +1376,31 @@ export async function hasCurrentPostgresSchedulerSchemaShape(
             )
           )
         )
+        AND (
+          $36::boolean = false
+          OR (
+            to_regclass($37) IS NOT NULL
+            AND (
+              SELECT count(DISTINCT column_name)
+              FROM information_schema.columns
+              WHERE table_schema = $1
+                AND table_name = 'rate_scope_holds'
+                AND column_name IN (
+                  'bucket_id', 'retry_at_ms', 'refill_per_sec', 'capacity', 'max_rps',
+                  'tokens', 'refilled_at_ms', 'next_dispatch_at_ms', 'seen_backpressure',
+                  'cool_until_ms', 'last_ramp_at_ms', 'rate_observation_started_at_ms',
+                  'rate_successes', 'rate_recovery_interval_ms',
+                  'rate_throttle_ceiling_rps'
+                )
+            ) = 15
+            AND (
+              SELECT count(DISTINCT column_name)
+              FROM information_schema.columns
+              WHERE table_schema = $1 AND table_name = 'rate_bucket'
+                AND column_name IN ('rate_observation_started_at_ms', 'rate_successes', 'rate_recovery_interval_ms')
+            ) = 3
+          )
+        )
         AND (
           $32::boolean = false
           OR (
@@ -1695,6 +1725,8 @@ export async function hasCurrentPostgresSchedulerSchemaShape(
       `${quotedSchema}.${quoteIdent(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE)}`,
       requirements.rateRequesterFairShare !== false,
       `${quotedSchema}.${quoteIdent('rate_requesters')}`,
+      requirements.rateScopeRetryAfter !== false,
+      `${quotedSchema}.${quoteIdent('rate_scope_holds')}`,
     ],
   );
   if (currentShape.rows[0]?.ready !== true) return false;

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

@@ -14,6 +14,9 @@ export type PlayExecutionSuspension =
       boundaryId: string;
       eventKey: string;
       timeoutMs: number;
+      eventExpiresAtMs?: number;
+      /** A terminal timeout's deliberate long park, not its original event wait. */
+      postTimeoutPark?: boolean;
       messageRef?: {
         channel: string;
         ts: string;
@@ -21,10 +24,13 @@ export type PlayExecutionSuspension =
     }
   | {
       kind: 'integration_event_batch';
+      /** Earliest pending provider row; absence preserves older event-only waits. */
+      providerWakeAtMs?: number;
       boundaries: Array<{
         boundaryId: string;
         eventKey: string;
         timeoutMs: number;
+        eventExpiresAtMs?: number;
         messageRef?: {
           channel: string;
           ts: string;
@@ -123,6 +129,7 @@ export class PlayRowExecutionSuspendedError extends Error {
     boundaryId: string;
     eventKey: string;
     timeoutMs: number;
+    eventExpiresAtMs?: number;
     messageRef?: {
       channel: string;
       ts: string;
@@ -133,6 +140,7 @@ export class PlayRowExecutionSuspendedError extends Error {
     boundaryId: string;
     eventKey: string;
     timeoutMs: number;
+    eventExpiresAtMs?: number;
     messageRef?: {
       channel: string;
       ts: string;
@@ -146,6 +154,19 @@ export class PlayRowExecutionSuspendedError extends Error {
   }
 }
 
+/** A provider wait is a control handoff, never a failed cell or receipt. */
+export class PlayRowProviderBackpressureError extends Error {
+  constructor(
+    readonly provider: string,
+    readonly retryAtMs: number,
+  ) {
+    super(
+      `Play row is waiting for ${provider} provider backpressure to clear.`,
+    );
+    this.name = 'PlayRowProviderBackpressureError';
+  }
+}
+
 export function isPlayRowExecutionSuspendedError(
   value: unknown,
 ): value is PlayRowExecutionSuspendedError {

package/dist/bundling-sources/shared_libs/play-runtime/tool-execute-retry-policy.ts

@@ -29,6 +29,8 @@ export const TOOL_EXECUTE_CONCURRENCY_BACKPRESSURE_MAX_ATTEMPTS = 65;
 // for an operation that has not opted into ordinary transient-5xx retries.
 // Keep its window aligned with other local control-plane queue signals.
 export const TOOL_EXECUTE_RUNTIME_SCHEDULER_CAPACITY_MAX_ATTEMPTS = 65;
+/** Re-admission after a stale shared provider permit is safely replayable. */
+export const TOOL_EXECUTE_PROVIDER_PACING_WAIT_MAX_ATTEMPTS = 65;
 export const TOOL_EXECUTE_TRANSPORT_MAX_ATTEMPTS = 3;
 export const TOOL_EXECUTE_TRANSPORT_RETRY_DELAY_MS = 1_000;
 export const TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS = 1_000;
@@ -69,6 +71,15 @@ export const TOOL_EXECUTE_RUNNER_ACCEPTS_CONCURRENCY_BACKPRESSURE =
 /** The capability tokens this runner build advertises on provider execute. */
 export const TOOL_EXECUTE_RUNNER_ACCEPTS_VALUE =
   TOOL_EXECUTE_RUNNER_ACCEPTS_CONCURRENCY_BACKPRESSURE;
+/** Runner proof headers consumed only by the execution gateway. */
+export const TOOL_EXECUTE_PROVIDER_RATE_SCOPE_HEADER =
+  'x-deepline-provider-rate-scope';
+export const TOOL_EXECUTE_PROVIDER_RATE_RETRY_SNAPSHOT_HEADER =
+  'x-deepline-provider-rate-retry-snapshot';
+/** Server-minted only for an internal executor's provider-owned 429. */
+export const TOOL_EXECUTE_PROVIDER_THROTTLE_HEADER =
+  'x-deepline-provider-throttle';
+export const TOOL_EXECUTE_PROVIDER_PACING_WAIT_CODE = 'PROVIDER_PACING_WAIT';
 
 /**
  * Parse the advertisement as a comma-separated token list so a later runner can
@@ -106,6 +117,7 @@ export type ToolExecuteHttpRetryDecision = {
     | 'rate_limit'
     | 'concurrency_backpressure'
     | 'runtime_scheduler_capacity'
+    | 'provider_pacing_wait'
     | 'idempotency_in_progress'
     | 'gateway_invocation_in_progress'
     | 'customer_db_storage_unavailable'
@@ -122,6 +134,8 @@ export type ToolExecuteHttpFailureOutcome = ToolExecuteHttpRetryDecision & {
   fate: 'retry' | 'settle_row_failure' | 'fail_run';
   retryDelayMs: number;
   backpressureDelayMs: number | null;
+  /** Retry-After for known-not-dispatched gateway pacing; not provider feedback. */
+  providerPacingWaitMs: number | null;
   chargeRetryBudget: boolean;
   /** The response proves the provider request was never dispatched. */
   knownNotDispatched: boolean;
@@ -214,6 +228,19 @@ function isRuntimeSchedulerCapacityResponse(input: {
   );
 }
 
+function isProviderPacingWaitResponse(input: {
+  status: number;
+  bodyText: string;
+}): boolean {
+  const body = parseJsonObject(input.bodyText);
+  return (
+    input.status === 503 &&
+    body?.code === TOOL_EXECUTE_PROVIDER_PACING_WAIT_CODE &&
+    body.failure_origin === 'deepline_rate_limit' &&
+    body.provider_request_dispatched === false
+  );
+}
+
 function idempotencyInProgressRetryDelayMs(attempt: number): number {
   return (
     TOOL_EXECUTE_IDEMPOTENCY_IN_PROGRESS_RETRY_DELAYS_MS[
@@ -249,6 +276,7 @@ function decideToolExecuteHttpRetry(input: {
   customerDbStorageUnavailable?: boolean;
   concurrencyBackpressure?: boolean;
   runtimeSchedulerCapacity?: boolean;
+  providerPacingWait?: boolean;
   hardBillingFailure?: boolean;
   hasRetryAfterHeader?: boolean;
   transientHttpRetrySafe?: boolean;
@@ -289,6 +317,13 @@ function decideToolExecuteHttpRetry(input: {
       reason: 'runtime_scheduler_capacity',
     };
   }
+  if (input.providerPacingWait) {
+    return {
+      retryable: true,
+      attemptCap: TOOL_EXECUTE_PROVIDER_PACING_WAIT_MAX_ATTEMPTS,
+      reason: 'provider_pacing_wait',
+    };
+  }
   if (input.gatewayInvocationInProgress) {
     return {
       retryable: true,
@@ -342,6 +377,7 @@ export function createToolExecuteHttpFailureAttemptTracker(): ToolExecuteHttpFai
     rate_limit: 0,
     concurrency_backpressure: 0,
     runtime_scheduler_capacity: 0,
+    provider_pacing_wait: 0,
     idempotency_in_progress: 0,
     gateway_invocation_in_progress: 0,
     customer_db_storage_unavailable: 0,
@@ -376,6 +412,10 @@ export function createToolExecuteHttpFailureAttemptTracker(): ToolExecuteHttpFai
           status: input.status,
           bodyText: input.bodyText ?? '',
         }),
+        providerPacingWait: isProviderPacingWaitResponse({
+          status: input.status,
+          bodyText: input.bodyText ?? '',
+        }),
         hasRetryAfterHeader: true,
         transientHttpRetrySafe: input.transientHttpRetrySafe === true,
       });
@@ -391,12 +431,12 @@ export function parseToolExecuteRetryAfterMs(
 ): number {
   if (!header) return TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS;
   const seconds = Number(header);
-  if (Number.isFinite(seconds) && seconds > 0) {
+  if (Number.isFinite(seconds) && seconds >= 0) {
     return Math.ceil(seconds * 1000);
   }
   const retryAt = Date.parse(header);
   if (Number.isFinite(retryAt)) {
-    return Math.max(1, retryAt - nowMs);
+    return Math.max(0, retryAt - nowMs);
   }
   return TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS;
 }
@@ -423,6 +463,7 @@ export function classifyToolExecuteHttpFailure(input: {
     isCustomerDbStorageUnavailableResponse(input);
   const concurrencyBackpressure = isConcurrencyBackpressureResponse(input);
   const runtimeSchedulerCapacity = isRuntimeSchedulerCapacityResponse(input);
+  const providerPacingWait = isProviderPacingWaitResponse(input);
   const initialRetryDecision = decideToolExecuteHttpRetry({
     status: input.status,
     idempotencyInProgress,
@@ -430,13 +471,33 @@ export function classifyToolExecuteHttpFailure(input: {
     customerDbStorageUnavailable,
     concurrencyBackpressure,
     runtimeSchedulerCapacity,
+    providerPacingWait,
     hasRetryAfterHeader,
     transientHttpRetrySafe,
   });
-  const retryAfterMs = parseToolExecuteRetryAfterMs(
-    input.retryAfterHeader,
-    input.nowMs,
-  );
+  const providerPacingWaitBody = providerPacingWait
+    ? parseJsonObject(input.bodyText)
+    : null;
+  const rawProviderPacingWaitMs = providerPacingWaitBody?.retry_after_ms;
+  const exactProviderPacingWaitMs =
+    typeof rawProviderPacingWaitMs === 'number' &&
+    Number.isFinite(rawProviderPacingWaitMs) &&
+    rawProviderPacingWaitMs >= 0
+      ? rawProviderPacingWaitMs
+      : null;
+  const attestedProviderDeadline =
+    providerPacingWait &&
+    (providerPacingWaitBody?.reason === 'retry_after' ||
+      providerPacingWaitBody?.reason === 'stale_permit') &&
+    typeof providerPacingWaitBody?.retry_at_ms === 'number' &&
+    Number.isFinite(providerPacingWaitBody.retry_at_ms) &&
+    providerPacingWaitBody.retry_at_ms > (input.nowMs ?? Date.now()) &&
+    exactProviderPacingWaitMs !== null &&
+    exactProviderPacingWaitMs > 0;
+  const retryAfterMs =
+    providerPacingWait && exactProviderPacingWaitMs !== null
+      ? exactProviderPacingWaitMs
+      : parseToolExecuteRetryAfterMs(input.retryAfterHeader, input.nowMs);
   const error = normalizeToolHttpErrorMessage({
     toolId: input.toolId,
     status: input.status,
@@ -446,7 +507,9 @@ export function classifyToolExecuteHttpFailure(input: {
     schemaVersion: input.schemaVersion,
     retryable: initialRetryDecision.retryable,
     retryAfterMs:
-      (input.status === 429 && hasRetryAfterHeader) || runtimeSchedulerCapacity
+      (input.status === 429 && hasRetryAfterHeader) ||
+      runtimeSchedulerCapacity ||
+      providerPacingWait
         ? retryAfterMs
         : null,
   });
@@ -458,6 +521,11 @@ export function classifyToolExecuteHttpFailure(input: {
     error.message = `${error.message} (provider call ${Math.round(input.providerLatencyMs)}ms)`;
   }
   const hardBillingFailure = isHardBillingToolHttpError(error);
+  const providerOwnedRateLimit =
+    input.status === 429 &&
+    !hardBillingFailure &&
+    error instanceof ToolExecutionError &&
+    error.origin === 'provider';
   const retryDecision = decideToolExecuteHttpRetry({
     status: input.status,
     idempotencyInProgress,
@@ -465,12 +533,15 @@ export function classifyToolExecuteHttpFailure(input: {
     customerDbStorageUnavailable,
     concurrencyBackpressure,
     runtimeSchedulerCapacity,
+    providerPacingWait,
     hardBillingFailure,
     hasRetryAfterHeader,
     transientHttpRetrySafe,
   });
   const shouldRetry =
-    retryDecision.retryable && input.attempt < retryDecision.attemptCap;
+    providerOwnedRateLimit ||
+    attestedProviderDeadline ||
+    (retryDecision.retryable && input.attempt < retryDecision.attemptCap);
   // In-attempt retry safety and later-run repairability are different
   // decisions. A non-idempotent 5xx must not be repeated automatically inside
   // this execution attempt, but an explicit later `plays run` must be able to
@@ -496,23 +567,37 @@ export function classifyToolExecuteHttpFailure(input: {
             TOOL_EXECUTE_RETRY_DELAY_MAX_MS,
             Math.max(retryAfterMs, TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS),
           )
-        : input.status === 429
-          ? Math.min(
-              TOOL_EXECUTE_RATE_LIMIT_RETRY_DELAY_MAX_MS,
-              Math.max(
-                retryAfterMs,
-                TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS * input.attempt,
-              ),
-            )
-          : retryDecision.reason === 'idempotency_in_progress' &&
-              !hasRetryAfterHeader
-            ? idempotencyInProgressRetryDelayMs(input.attempt)
-            : retryDecision.reason === 'gateway_invocation_in_progress' &&
+        : retryDecision.reason === 'provider_pacing_wait'
+          ? retryAfterMs
+          : input.status === 429
+            ? hasRetryAfterHeader
+              ? providerOwnedRateLimit
+                ? // The provider's explicit deadline is authoritative. Attempt-
+                  // scaled fallback backoff is only for a bare 429; extending a
+                  // valid Retry-After by the attempt number needlessly idles this
+                  // row after the shared provider pacer has already enforced the
+                  // deadline for every caller using the credential.
+                  retryAfterMs
+                : Math.max(
+                    retryAfterMs,
+                    TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS * input.attempt,
+                  )
+              : Math.min(
+                  TOOL_EXECUTE_RATE_LIMIT_RETRY_DELAY_MAX_MS,
+                  Math.max(
+                    retryAfterMs,
+                    TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS * input.attempt,
+                  ),
+                )
+            : retryDecision.reason === 'idempotency_in_progress' &&
                 !hasRetryAfterHeader
               ? idempotencyInProgressRetryDelayMs(input.attempt)
-              : retryAfterMs > 0
-                ? Math.min(TOOL_EXECUTE_RETRY_DELAY_MAX_MS, retryAfterMs)
-                : TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS;
+              : retryDecision.reason === 'gateway_invocation_in_progress' &&
+                  !hasRetryAfterHeader
+                ? idempotencyInProgressRetryDelayMs(input.attempt)
+                : retryAfterMs > 0
+                  ? Math.min(TOOL_EXECUTE_RETRY_DELAY_MAX_MS, retryAfterMs)
+                  : TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS;
   return {
     ...retryDecision,
     error,
@@ -528,24 +613,25 @@ export function classifyToolExecuteHttpFailure(input: {
     // caller, and malformed responses are never evidence that a provider is
     // throttling; feeding any of them into the pacer can incorrectly exhaust
     // every customer sharing that provider credential.
-    backpressureDelayMs:
-      input.status === 429 &&
-      retryDecision.reason !== 'hard_billing_error' &&
-      error instanceof ToolExecutionError &&
-      error.origin === 'provider'
-        ? hasRetryAfterHeader && retryAfterMs > 0
-          ? retryAfterMs
-          : TOOL_EXECUTE_BARE_RATE_LIMIT_BACKPRESSURE_MS
-        : null,
+    backpressureDelayMs: providerOwnedRateLimit
+      ? hasRetryAfterHeader
+        ? retryAfterMs
+        : TOOL_EXECUTE_BARE_RATE_LIMIT_BACKPRESSURE_MS
+      : null,
+    providerPacingWaitMs:
+      attestedProviderDeadline && shouldRetry ? retryAfterMs : null,
     chargeRetryBudget:
       shouldRetry &&
+      !providerOwnedRateLimit &&
       retryDecision.reason !== 'gateway_invocation_in_progress' &&
       retryDecision.reason !== 'concurrency_backpressure' &&
-      retryDecision.reason !== 'runtime_scheduler_capacity',
+      retryDecision.reason !== 'runtime_scheduler_capacity' &&
+      retryDecision.reason !== 'provider_pacing_wait',
     // Scheduler capacity and the relay's explicit concurrency shed both occur
     // before a provider request is dispatched. Carry that proof in the shared
     // classification so the retry boundary can safely pace either response
     // without asking a non-idempotent provider call to be replayed.
-    knownNotDispatched: runtimeSchedulerCapacity || concurrencyBackpressure,
+    knownNotDispatched:
+      runtimeSchedulerCapacity || concurrencyBackpressure || providerPacingWait,
   };
 }

package/dist/bundling-sources/shared_libs/play-runtime/tool-result.ts

@@ -1593,6 +1593,22 @@ function serializedListRowsFromRaw(input: {
   return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 }
 
+/**
+ * V2 receipts keep the complete provider body in rawV2. Use that body as the
+ * durable source for list handles instead of writing the same rows to the
+ * compatibility-only listRows field.
+ */
+function serializedListRowsFromRawV2(input: {
+  rawV2: unknown;
+  view: 'data' | 'rawV2';
+  metadata: ToolResultMetadataInput;
+}): Record<string, Array<Record<string, unknown>>> | undefined {
+  return serializedListRowsFromRaw({
+    raw: legacyRawFromToolResponseRawV2(input.rawV2, input.view),
+    metadata: input.metadata,
+  });
+}
+
 function preservedSerializedListRows(
   value: ToolExecuteResult,
 ): Record<string, Array<Record<string, unknown>>> | undefined {
@@ -1864,6 +1880,52 @@ function sameJsonValue(left: unknown, right: unknown): boolean {
   }
 }
 
+/**
+ * New V2 receipts must not carry a second full copy of list rows. Keep the
+ * optional field when the rows cannot be proven identical to the canonical
+ * rawV2 body; this makes the compaction conservative for unusual or historical
+ * envelopes while allowing ordinary V2 receipts to store rows exactly once.
+ */
+function listRowsAreInCanonicalRawV2(input: {
+  rawV2: unknown;
+  view: 'data' | 'rawV2';
+  metadata: ToolResultMetadataInput;
+  listRows: Record<string, Array<Record<string, unknown>>> | undefined;
+}): boolean {
+  if (!input.listRows || Object.keys(input.listRows).length === 0) {
+    return false;
+  }
+  const canonicalRows = serializedListRowsFromRawV2({
+    rawV2: input.rawV2,
+    view: input.view,
+    metadata: input.metadata,
+  });
+  if (!canonicalRows) return false;
+  return Object.entries(input.listRows).every(([name, rows]) =>
+    sameJsonValue(canonicalRows[name], rows),
+  );
+}
+
+function completeListRowsForDatasets(input: {
+  listRows: Record<string, Array<Record<string, unknown>>> | undefined;
+  listDatasets:
+    | Record<string, SerializedPlayDataset<Record<string, unknown>>>
+    | undefined;
+}): Record<string, Array<Record<string, unknown>>> | undefined {
+  if (!input.listRows || !input.listDatasets) return undefined;
+  const datasets = Object.entries(input.listDatasets);
+  if (datasets.length === 0) return undefined;
+  if (
+    !datasets.every(([name, dataset]) => {
+      const rows = input.listRows?.[name];
+      return rows !== undefined && rows.length >= dataset.count;
+    })
+  ) {
+    return undefined;
+  }
+  return input.listRows;
+}
+
 function responseMetaOutsideRawV2(input: {
   rawV2: unknown;
   view: 'data' | 'rawV2';
@@ -1931,6 +1993,14 @@ export function serializeToolExecuteResult(
   });
   if (Object.prototype.hasOwnProperty.call(value.toolResponse, 'rawV2')) {
     const view = value.toolResponse.view ?? 'rawV2';
+    const persistedListRows = listRowsAreInCanonicalRawV2({
+      rawV2: value.toolResponse.rawV2,
+      view,
+      metadata,
+      listRows,
+    })
+      ? undefined
+      : listRows;
     const responseMeta = responseMetaOutsideRawV2({
       rawV2: value.toolResponse.rawV2,
       view,
@@ -1960,7 +2030,7 @@ export function serializeToolExecuteResult(
         ...(responseMeta ? { responseMeta } : {}),
       },
       ...(listDatasets ? { listDatasets } : {}),
-      ...(listRows ? { listRows } : {}),
+      ...(persistedListRows ? { listRows: persistedListRows } : {}),
       ...(targetValues ? { targetValues } : {}),
       metadata,
       execution: value._metadata.execution,
@@ -2023,6 +2093,16 @@ export function deserializeToolExecuteResult(
     )
       ? value.toolResponse.legacyRaw
       : raw;
+    const listRows =
+      value.listRows ??
+      completeListRowsForDatasets({
+        listRows: serializedListRowsFromRawV2({
+          rawV2,
+          view,
+          metadata: value.metadata,
+        }),
+        listDatasets: value.listDatasets,
+      });
     return applySerializedListDatasets(
       applySerializedTargetValues(
         createToolExecuteResult({
@@ -2045,7 +2125,7 @@ export function deserializeToolExecuteResult(
         value.targetValues,
       ),
       value.listDatasets,
-      value.listRows,
+      listRows,
     );
   }
   return applySerializedListDatasets(

package/dist/bundling-sources/shared_libs/plays/tool-result-types.ts

@@ -119,7 +119,7 @@ export type SerializedToolExecuteResultV1 = {
     meta?: Record<string, unknown>;
   };
   listDatasets?: Record<string, SerializedPlayDataset<Record<string, unknown>>>;
-  /** Full declared list rows used to rehydrate list Dataset Handles. */
+  /** Full declared list rows retained by historical V1 receipts. */
   listRows?: Record<string, Array<Record<string, unknown>>>;
   /** Computed scalar/object getters preserved before raw list previews are clipped. */
   targetValues?: Record<string, ToolResultTargetMetadata>;
@@ -133,7 +133,7 @@ export type SerializedToolExecuteResultV1 = {
  */
 export type SerializedToolExecuteResultV2 = Omit<
   SerializedToolExecuteResultV1,
-  '__kind' | 'toolResponse'
+  '__kind' | 'toolResponse' | 'listRows'
 > & {
   __kind: 'deepline.tool_execute_result.v2';
   toolResponse: {
@@ -144,6 +144,11 @@ export type SerializedToolExecuteResultV2 = Omit<
     /** Deepline-owned additions not already represented in `rawV2.meta`. */
     responseMeta?: Record<string, unknown>;
   };
+  /**
+   * Compatibility fallback for older V2 receipts whose rawV2 body was not
+   * complete. New V2 receipts derive list rows from rawV2 and omit this copy.
+   */
+  listRows?: Record<string, Array<Record<string, unknown>>>;
 };
 
 export type SerializedToolExecuteResult =

package/dist/cli/index.js

@@ -3051,7 +3051,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.183",
+  version: "0.3.185",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -14141,6 +14141,7 @@ function mergeCanonicalRowsInfo(left, right) {
     source: preferred.source ?? fallback.source,
     datasetId: preferred.datasetId ?? fallback.datasetId,
     tableNamespace: preferred.tableNamespace ?? fallback.tableNamespace,
+    currentTableQueryCommand: preferred.currentTableQueryCommand ?? fallback.currentTableQueryCommand,
     ...left.recovered || right.recovered ? { recovered: true } : {},
     ...recoveredReturnPaths2.length ? { recoveredReturnPaths: recoveredReturnPaths2 } : {},
     ...currentTable ? { currentTable: true } : {},
@@ -14209,6 +14210,12 @@ function hasCurrentTableExport(value) {
   const exportCsv = value.actions.exportCsv;
   return isRecord8(exportCsv) && isRecord8(exportCsv.scope) && exportCsv.scope.kind === "database" && exportCsv.scope.mutability === "current";
 }
+function currentTableQueryCommand(value) {
+  if (!isRecord8(value) || !isRecord8(value.actions)) return void 0;
+  const query = value.actions.queryCurrentTable;
+  const command = isRecord8(query) ? query.command : void 0;
+  return typeof command === "string" && command.trim() ? command.trim() : void 0;
+}
 function recoveredReturnPaths(value) {
   if (!Array.isArray(value)) return [];
   return [
@@ -14316,6 +14323,9 @@ function canonicalRowsInfoFromCandidate(input2) {
       tableNamespace: typeof candidate.value.tableNamespace === "string" ? candidate.value.tableNamespace : null,
       ...candidate.value.recovered === true ? { recovered: true } : {},
       ...hasCurrentTableExport(candidate.value) ? { currentTable: true } : {},
+      ...currentTableQueryCommand(candidate.value) ? {
+        currentTableQueryCommand: currentTableQueryCommand(candidate.value)
+      } : {},
       ...recoveredReturnPaths(candidate.value.recoveredReturnPaths).length ? {
         recoveredReturnPaths: recoveredReturnPaths(
           candidate.value.recoveredReturnPaths
@@ -26317,7 +26327,20 @@ async function fetchBackingDatasetRows(input2) {
     offset += page.rows.length;
   }
   const rows = sheetRows.map(exportableSheetRow).filter((row) => Boolean(row));
-  const hasCompleteSettledPrefix = !currentTable && acceptsSettledRowsAsCompleteExport(input2.status) && settledTotal !== null && rows.length >= settledTotal;
+  const hasCompleteSettledPrefix = !currentTable && acceptsSettledRowsAsCompleteExport(input2.status) && settledTotal !== null && // A zero-row run-scoped read is not a settled export when the returned
+  // Dataset Handle advertised rows. That shape is the replay/reuse case:
+  // the rows belong to another writer (or the projection has not caught up)
+  // and must not erase the run package's advertised count.
+  (settledTotal > 0 || input2.rowsInfo.totalRows === 0) && rows.length >= settledTotal;
+  if (!currentTable && acceptsSettledRowsAsCompleteExport(input2.status) && settledTotal === 0 && rows.length === 0 && input2.rowsInfo.totalRows > 0) {
+    return {
+      ...input2.rowsInfo,
+      rows: [],
+      totalRows: input2.rowsInfo.totalRows,
+      complete: true,
+      source: `${input2.rowsInfo.source ?? "result.rows"} -> /api/v2/plays/${playName}/sheet?tableNamespace=${tableNamespace}`
+    };
+  }
   if (!currentTable && rows.length < input2.rowsInfo.totalRows && !hasCompleteSettledPrefix || currentTable && rows.length === 0 && input2.rowsInfo.totalRows > 0) {
     return null;
   }
@@ -26373,7 +26396,8 @@ function assertDatasetHasExportableRows(input2) {
     "output.csv",
     datasetLabel
   );
-  const explanation = terminalRunWithMissingAdvertisedRows ? ` The terminal result advertised ${advertisedRows} row(s), but none are currently attributed to this run's durable sheet. Those rows may have been reused from an earlier run or the projection may still be lagging; export refuses to guess another run's rows. Retry the same export after projection catches up (do not rerun the Play): ${retryCommand}. If it remains empty, inspect the full package with ${inspectCommand} and export the run that owns the durable dataset; this command will not use a database-wide table query that could mix runs.` : ` The run status is '${runStatus || "unknown"}', so it likely failed before persisting rows to this dataset. That means provider calls may have been billed without a durable row; inspect ${inspectCommand}, fix the failure cause, then rerun the Play so completed receipts can be reused.`;
+  const currentTableQueryCommand2 = input2.rowsInfo.currentTableQueryCommand;
+  const explanation = terminalRunWithMissingAdvertisedRows ? ` The terminal result advertised ${advertisedRows} row(s), but none are currently attributed to this run's durable sheet. Those rows may have been reused from an earlier run or the projection may still be lagging; export refuses to guess another run's rows. Retry the same export after projection catches up (do not rerun the Play): ${retryCommand}. If it remains empty, inspect the full package with ${inspectCommand}` + (currentTableQueryCommand2 ? `, then inspect the current table's _run_id/_writer_run_id with ${currentTableQueryCommand2} and export the run that owns those rows` : " and export the run that owns the durable dataset") + "; this command will not use a database-wide table query that could mix runs." : ` The run status is '${runStatus || "unknown"}', so it likely failed before persisting rows to this dataset. That means provider calls may have been billed without a durable row; inspect ${inspectCommand}, fix the failure cause, then rerun the Play so completed receipts can be reused.`;
   throw new DeeplineError(
     `Run ${input2.status.runId} has zero rows to export from dataset '${datasetLabel}'.` + explanation + (available.length > 0 ? ` Available datasets: ${available.join(", ")}.` : " No datasets were materialized for this run."),
     void 0,
@@ -26386,6 +26410,7 @@ function assertDatasetHasExportableRows(input2) {
       guidance: terminalRunWithMissingAdvertisedRows ? {
         inspect_command: inspectCommand,
         retry_command: retryCommand,
+        ...currentTableQueryCommand2 ? { lookup_writer_command: currentTableQueryCommand2 } : {},
         do_not_rerun: true,
         reason: "Run output is terminal but its rows are not attributed to this run; export refuses to guess another writer."
       } : {