deepline 0.1.187 → 0.1.188

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

@@ -168,6 +168,10 @@ import {
   WorkerRunWorkDispatcher,
   type WorkerRunMapBatchesResult,
 } from './runtime/run-work-dispatcher';
+import {
+  boundedWorkflowPreviewRows,
+  WORKFLOW_MAP_CHUNK_PREVIEW_MAX_BYTES,
+} from './runtime/workflow-preview';
 import { WORKER_PLATFORM_SUBREQUESTS_PER_UNBATCHED_TOOL_CALL } from './runtime/worker-platform-budget';
 import {
   PLAY_RUNTIME_CONTRACT,
@@ -252,6 +256,7 @@ import { normalizePlayRunFailure } from '../../../shared_libs/play-runtime/run-f
 import {
   createRuntimePersistenceLatch,
   isRuntimePersistenceCircuitOpenError,
+  RuntimePersistenceCircuitOpenError,
   tripRuntimePersistenceLatch,
 } from '../../../shared_libs/play-runtime/persistence-latch';
 import {
@@ -2420,7 +2425,8 @@ type WorkerMapBlockedChunkSummary = {
 };
 
 type WorkerMapChunkSummary<T extends Record<string, unknown>> =
-  WorkerMapCompletedChunkSummary<T> | WorkerMapBlockedChunkSummary;
+  | WorkerMapCompletedChunkSummary<T>
+  | WorkerMapBlockedChunkSummary;
 
 function serializeDurableStepValue<T>(value: T, depth = 0): T {
   if (depth > 20 || value == null) return value;
@@ -2479,7 +2485,9 @@ type WorkerConditionalStepResolver = {
 type WorkerStepProgramStep = {
   name: string;
   resolver:
-    WorkerStepResolver | WorkerConditionalStepResolver | WorkerStepProgram;
+    | WorkerStepResolver
+    | WorkerConditionalStepResolver
+    | WorkerStepProgram;
 };
 
 type WorkerStepProgram = {
@@ -3416,7 +3424,9 @@ function resolveSheetContractFromReq(
   // `staticPipeline` field is what `resolveSheetContractForTableNamespace`
   // expects. Reach in safely.
   const snapshot = req.contractSnapshot as
-    { staticPipeline?: unknown } | undefined | null;
+    | { staticPipeline?: unknown }
+    | undefined
+    | null;
   const pipeline = snapshot?.staticPipeline;
   if (!pipeline || typeof pipeline !== 'object' || Array.isArray(pipeline)) {
     return null;
@@ -3508,7 +3518,9 @@ async function releaseRuntimeLeasesOnTeardown(input: {
 
 function staticPipelineFromReq(req: RunRequest): PlayStaticPipeline | null {
   const snapshot = req.contractSnapshot as
-    { staticPipeline?: unknown } | undefined | null;
+    | { staticPipeline?: unknown }
+    | undefined
+    | null;
   const pipeline = snapshot?.staticPipeline;
   if (!pipeline || typeof pipeline !== 'object' || Array.isArray(pipeline)) {
     return null;
@@ -5100,6 +5112,15 @@ function createMinimalWorkerCtx(
         }
       };
 
+      const runtimePersistenceCircuitError = (): Error | null => {
+        if (persistFailure) {
+          tripRuntimePersistenceLatch(persistenceLatch, persistFailure);
+        }
+        return persistenceLatch.tripped
+          ? new RuntimePersistenceCircuitOpenError(persistenceLatch)
+          : null;
+      };
+
       const persistExecutedRows = async () => {
         const rowsToPersist = executedRows
           .map((row, executedIndex) =>
@@ -5207,11 +5228,13 @@ function createMinimalWorkerCtx(
         pendingPersistRows = 0;
         pendingPersistBytes = 0;
         const task = persistFlushChain.then(async () => {
-          if (persistFailure) throw persistFailure;
+          const circuitError = runtimePersistenceCircuitError();
+          if (circuitError) throw circuitError;
           await persistExecutedRows();
         });
         persistFlushChain = task.catch((error) => {
           persistFailure ??= error;
+          tripRuntimePersistenceLatch(persistenceLatch, error);
         });
         return task;
       };
@@ -5296,26 +5319,31 @@ function createMinimalWorkerCtx(
         return Promise.resolve();
       };
 
-      const schedulePersistExecutedRows = () => {
-        if (persistFailure) return;
+      const schedulePersistExecutedRows = (): Promise<void> | null => {
+        const circuitError = runtimePersistenceCircuitError();
+        if (circuitError) return Promise.reject(circuitError);
         if (
           pendingPersistRows >= MAP_INCREMENTAL_PERSIST_CHUNK_ROWS ||
           pendingPersistBytes >= MAP_INCREMENTAL_PERSIST_CHUNK_BYTES
         ) {
-          void enqueuePersistExecutedRows().catch(() => undefined);
-          return;
+          return enqueuePersistExecutedRows();
         }
-        if (scheduledPersistTimer) return;
+        if (scheduledPersistTimer) return null;
         scheduledPersistTimer = setTimeout(() => {
           scheduledPersistTimer = null;
           void enqueuePersistExecutedRows().catch(() => undefined);
         }, MAP_INCREMENTAL_PERSIST_INTERVAL_MS);
+        return null;
       };
 
-      const notePersistableRow = (row: Record<string, unknown>) => {
+      const notePersistableRow = async (
+        row: Record<string, unknown>,
+      ): Promise<void> => {
         pendingPersistRows += 1;
         pendingPersistBytes += JSON.stringify(row).length;
-        schedulePersistExecutedRows();
+        await (schedulePersistExecutedRows() ?? Promise.resolve());
+        const circuitError = runtimePersistenceCircuitError();
+        if (circuitError) throw circuitError;
       };
 
       let idx = 0;
@@ -5325,6 +5353,8 @@ function createMinimalWorkerCtx(
           (async () => {
             while (true) {
               if (abortSignal?.aborted) return;
+              const circuitError = runtimePersistenceCircuitError();
+              if (circuitError) throw circuitError;
               const myIndex = idx++;
               if (myIndex >= rowsToExecute.length) return;
               const rowSlot = await governor.acquireRowSlot({
@@ -5472,7 +5502,7 @@ function createMinimalWorkerCtx(
                   executedRows[myIndex] = enriched as T &
                     Record<string, unknown>;
                   completedExecutedRows += 1;
-                  notePersistableRow(enriched);
+                  await notePersistableRow(enriched);
                   reportChunkProgress(false);
                 } catch (rowError) {
                   // Receipt persistence errors stay run-fatal, but keep the
@@ -5522,7 +5552,7 @@ function createMinimalWorkerCtx(
                   };
                   failedExecutedRows += 1;
                   if (!failFastRowErrors) {
-                    notePersistableRow(enriched);
+                    await notePersistableRow(enriched);
                   }
                   // Bounded per-chunk samples: every failure is persisted on
                   // its row, but only the first few get a log line so a wide
@@ -5636,7 +5666,8 @@ function createMinimalWorkerCtx(
           rangeStart: baseOffset + chunkStart,
           rangeEnd: baseOffset + chunkStart,
           rowsRead: chunkRows.length,
-          rowsWritten: 0,
+          rowsWritten:
+            persistedExecutedIndexes.size + persistedFailedIndexes.size,
           rowsExecuted: rowsToExecute.length,
           rowsCached: 0,
           rowsDuplicateReused: duplicateInputReuseCount,
@@ -5867,7 +5898,11 @@ function createMinimalWorkerCtx(
         // storage may keep only the bounded preview sample; same-run play code
         // that needs more rows uses volatileWorkflowChunkRows, which is not
         // part of the persisted step result.
-        preview: toWorkflowSerializableValue(publicOut.slice(0, 5)),
+        preview: boundedWorkflowPreviewRows(publicOut, {
+          maxRows: WORKER_DATASET_PREVIEW_ROWS,
+          maxBytes: WORKFLOW_MAP_CHUNK_PREVIEW_MAX_BYTES,
+          serialize: toWorkflowSerializableValue,
+        }),
         cachedRows:
           includeCachedRowsInChunkResult &&
           out.length <= WORKER_DATASET_IN_MEMORY_ROWS
@@ -6993,7 +7028,8 @@ function createMinimalWorkerCtx(
                 // the small structural shape ChildPlayAwait needs; bridge it the
                 // same way the inline implementation did.
                 workflowStep: workflowStep as unknown as
-                  WorkflowStepLike | undefined,
+                  | WorkflowStepLike
+                  | undefined,
                 workflowId,
                 playName: resolvedName,
                 key: normalizedKey,

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

@@ -0,0 +1,26 @@
+export const WORKFLOW_MAP_CHUNK_PREVIEW_MAX_BYTES = 64 * 1024;
+
+const jsonByteLength = (value: unknown): number =>
+  new TextEncoder().encode(JSON.stringify(value)).byteLength;
+
+export function boundedWorkflowPreviewRows<T extends Record<string, unknown>>(
+  rows: readonly T[],
+  input: {
+    maxRows: number;
+    maxBytes: number;
+    serialize?: (row: T) => T;
+  },
+): T[] {
+  const preview: T[] = [];
+  let bytes = 2; // Opening and closing array brackets.
+  for (const row of rows) {
+    if (preview.length >= input.maxRows) break;
+    const serialized = input.serialize ? input.serialize(row) : row;
+    const rowBytes = jsonByteLength(serialized) + (preview.length > 0 ? 1 : 0);
+    if (rowBytes > input.maxBytes) continue;
+    if (bytes + rowBytes > input.maxBytes) break;
+    preview.push(serialized);
+    bytes += rowBytes;
+  }
+  return preview;
+}

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.187',
+  version: '0.1.188',
   apiContract: '2026-06-dataset-handle-results-hard-cutover',
   supportPolicy: {
-    latest: '0.1.187',
+    latest: '0.1.188',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
     commandMinimumSupported: [

package/dist/cli/index.js

@@ -623,10 +623,10 @@ var 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.187",
+  version: "0.1.188",
   apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.187",
+    latest: "0.1.188",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -17587,11 +17587,12 @@ function helperSource() {
 
 // src/cli/commands/enrich.ts
 var ENRICH_EXPORT_PAGE_SIZE = 5e3;
-var ENRICH_AUTO_BATCH_ROWS = 250;
+var ENRICH_AUTO_BATCH_ROWS = 200;
 var ENRICH_HEAVY_PLAY_AUTO_BATCH_ROWS = 25;
 var ENRICH_NESTED_PROVIDER_AUTO_BATCH_ROWS = 50;
 var ENRICH_EXPORT_BACKING_ROWS_WAIT_MS = 6e4;
 var ENRICH_EXPORT_BACKING_ROWS_POLL_MS = 1e3;
+var ENRICH_CUSTOMER_DB_FAILURE_LOOKUP_RETRY_DELAYS_MS = [1e3, 3e3, 7e3];
 var ENRICH_SOURCE_ROW_INDEX_COLUMN = "__deeplineSourceRowIndex";
 var ENRICH_ORIGINAL_SOURCE_ROW_INDEX_COLUMN = "__deeplineOriginalSourceRowIndex";
 var ENRICH_CELL_META_FIELD = "__deeplineCellMeta";
@@ -17742,6 +17743,13 @@ function enrichExportBackingRowsWaitMs() {
   const parsed = Number.parseInt(raw, 10);
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : ENRICH_EXPORT_BACKING_ROWS_WAIT_MS;
 }
+function enrichCustomerDbFailureLookupRetryDelaysMs() {
+  const raw = process.env.DEEPLINE_ENRICH_CUSTOMER_DB_LOOKUP_RETRY_DELAYS_MS?.trim();
+  if (!raw) {
+    return ENRICH_CUSTOMER_DB_FAILURE_LOOKUP_RETRY_DELAYS_MS;
+  }
+  return raw.split(",").map((part) => Number.parseInt(part.trim(), 10)).filter((value) => Number.isFinite(value) && value >= 0);
+}
 function emitEnrichDebugValidationLines(config) {
   for (const line of buildEnrichDebugValidationLines(config)) {
     emitEnrichDebug(line);
@@ -18682,13 +18690,71 @@ function failureAliasFromCellMeta(cellMeta) {
   }
   return null;
 }
+function formatEnrichDiagnosticError(error) {
+  if (error instanceof DeeplineError) {
+    const status = error.statusCode ? `HTTP ${error.statusCode}: ` : "";
+    const code = error.code && error.code !== "API_ERROR" ? ` [${error.code}]` : "";
+    return `${status}${error.message}${code}`;
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+function isRetryableCustomerDbLookupError(error) {
+  if (error instanceof DeeplineError) {
+    const status = error.statusCode;
+    if (status === 408 || status === 425 || status === 429 || status === 503 || typeof status === "number" && status >= 500) {
+      return true;
+    }
+    if (error.code === "NETWORK_TIMEOUT" || error.code === "NETWORK_ABORTED" || error.code === "NETWORK_ERROR" || error.code === "42P01") {
+      return true;
+    }
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return /Internal Server Error|fetch failed|ECONNRESET|ETIMEDOUT|timed out after \d+ms while waiting for a response|Unable to connect|relation .* does not exist|Neon API request failed \(404\)|ingestion plane .*not ready/i.test(
+    message
+  );
+}
+function customerDbLookupUnavailableIssue(input2) {
+  const command = input2.customerDb.command ?? (input2.customerDb.sql ? `deepline db query --sql ${shellSingleQuote2(input2.customerDb.sql)} --json` : void 0);
+  return {
+    issue_id: `customer-db-failure-lookup-${input2.customerDb.runId ?? "run"}`,
+    kind: "customer_db_lookup_unavailable",
+    severity: "needs_attention",
+    message: "Enrich completed, but Deepline could not inspect the Customer DB backing table for failed row details yet.",
+    next_steps: [
+      "Use the Customer DB query command below to inspect the durable rows after the data plane settles.",
+      "If the command keeps failing, inspect the run output and runtime sheet export instead of rerunning provider enrichments blindly."
+    ],
+    follow_up_commands: command ? [
+      {
+        label: "query customer db",
+        command,
+        path: input2.customerDb.datasetPath
+      }
+    ] : [],
+    ...input2.customerDb.runId ? { run_id: input2.customerDb.runId } : {},
+    error: formatEnrichDiagnosticError(input2.error),
+    attempts: input2.attempts
+  };
+}
+function emitCustomerDbLookupUnavailableWarning(issue) {
+  process.stderr.write(`Warning: ${issue.message}
+`);
+  if (issue.error) {
+    process.stderr.write(`Warning detail: ${issue.error}
+`);
+  }
+  for (const command of issue.follow_up_commands) {
+    process.stderr.write(`Command: ${command.label}: ${command.command}
+`);
+  }
+}
 async function collectCustomerDbFailureJobs(input2) {
   const customerDb = enrichCustomerDbJson({
     status: input2.status,
     client: input2.client
   });
   if (!customerDb?.runId || !customerDb.sqlQualifiedTableName) {
-    return [];
+    return { jobs: [], issue: null };
   }
   const fallbackAliases = collectHardFailureAliasSpecs(input2.config);
   const fallbackAlias = fallbackAliases[0]?.alias ?? "enrich";
@@ -18696,16 +18762,49 @@ async function collectCustomerDbFailureJobs(input2) {
     fallbackAliases.map((spec, index) => [normalizeAlias2(spec.alias), index])
   );
   const sql = `select _input_index, _status, _error, _cell_meta from ${customerDb.sqlQualifiedTableName} where _run_id = ${sqlStringLiteral(customerDb.runId)} and (_error is not null or lower(coalesce(_status, '')) in ('failed', 'error')) order by _input_index limit 1000`;
-  const result = await input2.client.queryCustomerDb({
-    sql,
-    maxRows: 1e3
-  });
+  const retryDelays = enrichCustomerDbFailureLookupRetryDelaysMs();
+  let lastError = null;
+  let attempts = 0;
+  let result = null;
+  for (let attempt = 0; attempt <= retryDelays.length; attempt += 1) {
+    try {
+      attempts = attempt + 1;
+      result = await input2.client.queryCustomerDb({
+        sql,
+        maxRows: 1e3
+      });
+      lastError = null;
+      break;
+    } catch (error) {
+      lastError = error;
+      if (attempt >= retryDelays.length || !isRetryableCustomerDbLookupError(error)) {
+        break;
+      }
+      const delayMs = retryDelays[attempt] ?? 0;
+      emitEnrichDebug(
+        `customer_db failure lookup retrying after ${delayMs}ms: ${formatEnrichDiagnosticError(error)}`
+      );
+      if (delayMs > 0) {
+        await sleep6(delayMs);
+      }
+    }
+  }
+  if (!result) {
+    return {
+      jobs: [],
+      issue: customerDbLookupUnavailableIssue({
+        customerDb,
+        error: lastError,
+        attempts
+      })
+    };
+  }
   const rows = Array.isArray(result.rows) ? result.rows : [];
   const failedRows = rows.filter((row) => {
     const status = typeof row._status === "string" ? row._status.trim().toLowerCase() : "";
     return typeof row._error === "string" && row._error.trim() || status === "failed" || status === "error";
   });
-  return failedRows.map((row, index) => {
+  const jobs = failedRows.map((row, index) => {
     const metaFailure = failureAliasFromCellMeta(row._cell_meta);
     const alias = metaFailure?.alias ?? fallbackAlias;
     const normalizedAlias = normalizeAlias2(alias);
@@ -18729,6 +18828,7 @@ async function collectCustomerDbFailureJobs(input2) {
       ...metaFailure?.provider ? { provider: metaFailure.provider } : {}
     };
   });
+  return { jobs, issue: null };
 }
 async function buildEnrichFailureReport(input2) {
   const fallbackRowsInfo = input2.exportResult ? null : extractCanonicalRowsInfo(input2.status);
@@ -19256,9 +19356,7 @@ function collectWaterfallAliasSpecs(config) {
       alias,
       childAliases: activeChildren.map((child) => child.alias).filter(Boolean),
       childRunIfJsByAlias: new Map(
-        activeChildren.map(
-          (child) => [child.alias, child.run_if_js]
-        )
+        activeChildren.map((child) => [child.alias, child.run_if_js])
       ),
       childToolsByAlias: new Map(
         activeChildren.map(
@@ -20034,21 +20132,26 @@ async function maybeEmitEnrichFailureReport(input2) {
     status: input2.status,
     rowRange: input2.statusRowRange ?? input2.rowRange
   });
-  const customerDbJobs = input2.status === void 0 || rowJobs.length > 0 || statusJobs.length > 0 ? [] : await collectCustomerDbFailureJobs({
+  const customerDbDiagnostics = input2.status === void 0 || rowJobs.length > 0 || statusJobs.length > 0 ? { jobs: [], issue: null } : await collectCustomerDbFailureJobs({
     client: input2.client,
     status: input2.status,
     config: input2.config
   });
+  const customerDbJobs = customerDbDiagnostics.jobs;
+  if (customerDbDiagnostics.issue) {
+    emitCustomerDbLookupUnavailableWarning(customerDbDiagnostics.issue);
+  }
+  const allEnrichIssues = enrichIssues;
   const jobs = rowJobs.length > 0 || statusJobs.length > 0 || customerDbJobs.length > 0 || input2.status === void 0 ? mergeEnrichFailureJobs(
     mergeEnrichFailureJobs(rowJobs, statusJobs),
     customerDbJobs
   ) : [];
-  if (jobs.length === 0 && enrichIssues.length === 0) {
+  if (jobs.length === 0 && allEnrichIssues.length === 0) {
     return null;
   }
   const reportPath = await persistEnrichFailureReport({
     jobs,
-    issues: enrichIssues,
+    issues: allEnrichIssues,
     apiUrl: input2.client.baseUrl,
     outputPath: input2.outputPath,
     rows: input2.rowRange
@@ -20068,13 +20171,13 @@ async function maybeEmitEnrichFailureReport(input2) {
 `);
     }
   }
-  if (enrichIssues.length > 0) {
+  if (allEnrichIssues.length > 0) {
     process.stderr.write("Enrichment needs attention.\n");
     process.stderr.write("Issue preview (up to 5 enrichment issues):\n");
     process.stderr.write(
       "issue_id	column	severity	selected_rows	rows_with_value	message\n"
     );
-    for (const issue of enrichIssues.slice(0, 5)) {
+    for (const issue of allEnrichIssues.slice(0, 5)) {
       process.stderr.write(
         `${issue.issue_id}	${issue.column}	${issue.severity}	${issue.selected_rows}	${issue.rows_with_value}	${issue.message}
 `
@@ -20088,9 +20191,9 @@ async function maybeEmitEnrichFailureReport(input2) {
 `);
       }
     }
-    if (enrichIssues.length > 5) {
+    if (allEnrichIssues.length > 5) {
       process.stderr.write(
-        `Showing 5 of ${enrichIssues.length} enrichment issues.
+        `Showing 5 of ${allEnrichIssues.length} enrichment issues.
 `
       );
     }
@@ -20108,12 +20211,12 @@ async function maybeEmitEnrichFailureReport(input2) {
     process.stderr.write(
       jobs.length > 0 ? "Enrichment failed. See report above.\n" : "Enrichment produced no values for at least one requested waterfall. See issue preview above.\n"
     );
-    return { path: reportPath, jobs, issues: enrichIssues };
+    return { path: reportPath, jobs, issues: allEnrichIssues };
   }
   process.stderr.write(
     jobs.length > 0 ? "Enrichment failed.\n" : "Enrichment needs attention.\n"
   );
-  return { path: "", jobs, issues: enrichIssues };
+  return { path: "", jobs, issues: allEnrichIssues };
 }
 function mergePreferredColumns(preferredColumns, rows) {
   const columns = [];

package/dist/cli/index.mjs

@@ -608,10 +608,10 @@ var 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.187",
+  version: "0.1.188",
   apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.187",
+    latest: "0.1.188",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -17614,11 +17614,12 @@ function helperSource() {
 
 // src/cli/commands/enrich.ts
 var ENRICH_EXPORT_PAGE_SIZE = 5e3;
-var ENRICH_AUTO_BATCH_ROWS = 250;
+var ENRICH_AUTO_BATCH_ROWS = 200;
 var ENRICH_HEAVY_PLAY_AUTO_BATCH_ROWS = 25;
 var ENRICH_NESTED_PROVIDER_AUTO_BATCH_ROWS = 50;
 var ENRICH_EXPORT_BACKING_ROWS_WAIT_MS = 6e4;
 var ENRICH_EXPORT_BACKING_ROWS_POLL_MS = 1e3;
+var ENRICH_CUSTOMER_DB_FAILURE_LOOKUP_RETRY_DELAYS_MS = [1e3, 3e3, 7e3];
 var ENRICH_SOURCE_ROW_INDEX_COLUMN = "__deeplineSourceRowIndex";
 var ENRICH_ORIGINAL_SOURCE_ROW_INDEX_COLUMN = "__deeplineOriginalSourceRowIndex";
 var ENRICH_CELL_META_FIELD = "__deeplineCellMeta";
@@ -17769,6 +17770,13 @@ function enrichExportBackingRowsWaitMs() {
   const parsed = Number.parseInt(raw, 10);
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : ENRICH_EXPORT_BACKING_ROWS_WAIT_MS;
 }
+function enrichCustomerDbFailureLookupRetryDelaysMs() {
+  const raw = process.env.DEEPLINE_ENRICH_CUSTOMER_DB_LOOKUP_RETRY_DELAYS_MS?.trim();
+  if (!raw) {
+    return ENRICH_CUSTOMER_DB_FAILURE_LOOKUP_RETRY_DELAYS_MS;
+  }
+  return raw.split(",").map((part) => Number.parseInt(part.trim(), 10)).filter((value) => Number.isFinite(value) && value >= 0);
+}
 function emitEnrichDebugValidationLines(config) {
   for (const line of buildEnrichDebugValidationLines(config)) {
     emitEnrichDebug(line);
@@ -18709,13 +18717,71 @@ function failureAliasFromCellMeta(cellMeta) {
   }
   return null;
 }
+function formatEnrichDiagnosticError(error) {
+  if (error instanceof DeeplineError) {
+    const status = error.statusCode ? `HTTP ${error.statusCode}: ` : "";
+    const code = error.code && error.code !== "API_ERROR" ? ` [${error.code}]` : "";
+    return `${status}${error.message}${code}`;
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+function isRetryableCustomerDbLookupError(error) {
+  if (error instanceof DeeplineError) {
+    const status = error.statusCode;
+    if (status === 408 || status === 425 || status === 429 || status === 503 || typeof status === "number" && status >= 500) {
+      return true;
+    }
+    if (error.code === "NETWORK_TIMEOUT" || error.code === "NETWORK_ABORTED" || error.code === "NETWORK_ERROR" || error.code === "42P01") {
+      return true;
+    }
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return /Internal Server Error|fetch failed|ECONNRESET|ETIMEDOUT|timed out after \d+ms while waiting for a response|Unable to connect|relation .* does not exist|Neon API request failed \(404\)|ingestion plane .*not ready/i.test(
+    message
+  );
+}
+function customerDbLookupUnavailableIssue(input2) {
+  const command = input2.customerDb.command ?? (input2.customerDb.sql ? `deepline db query --sql ${shellSingleQuote2(input2.customerDb.sql)} --json` : void 0);
+  return {
+    issue_id: `customer-db-failure-lookup-${input2.customerDb.runId ?? "run"}`,
+    kind: "customer_db_lookup_unavailable",
+    severity: "needs_attention",
+    message: "Enrich completed, but Deepline could not inspect the Customer DB backing table for failed row details yet.",
+    next_steps: [
+      "Use the Customer DB query command below to inspect the durable rows after the data plane settles.",
+      "If the command keeps failing, inspect the run output and runtime sheet export instead of rerunning provider enrichments blindly."
+    ],
+    follow_up_commands: command ? [
+      {
+        label: "query customer db",
+        command,
+        path: input2.customerDb.datasetPath
+      }
+    ] : [],
+    ...input2.customerDb.runId ? { run_id: input2.customerDb.runId } : {},
+    error: formatEnrichDiagnosticError(input2.error),
+    attempts: input2.attempts
+  };
+}
+function emitCustomerDbLookupUnavailableWarning(issue) {
+  process.stderr.write(`Warning: ${issue.message}
+`);
+  if (issue.error) {
+    process.stderr.write(`Warning detail: ${issue.error}
+`);
+  }
+  for (const command of issue.follow_up_commands) {
+    process.stderr.write(`Command: ${command.label}: ${command.command}
+`);
+  }
+}
 async function collectCustomerDbFailureJobs(input2) {
   const customerDb = enrichCustomerDbJson({
     status: input2.status,
     client: input2.client
   });
   if (!customerDb?.runId || !customerDb.sqlQualifiedTableName) {
-    return [];
+    return { jobs: [], issue: null };
   }
   const fallbackAliases = collectHardFailureAliasSpecs(input2.config);
   const fallbackAlias = fallbackAliases[0]?.alias ?? "enrich";
@@ -18723,16 +18789,49 @@ async function collectCustomerDbFailureJobs(input2) {
     fallbackAliases.map((spec, index) => [normalizeAlias2(spec.alias), index])
   );
   const sql = `select _input_index, _status, _error, _cell_meta from ${customerDb.sqlQualifiedTableName} where _run_id = ${sqlStringLiteral(customerDb.runId)} and (_error is not null or lower(coalesce(_status, '')) in ('failed', 'error')) order by _input_index limit 1000`;
-  const result = await input2.client.queryCustomerDb({
-    sql,
-    maxRows: 1e3
-  });
+  const retryDelays = enrichCustomerDbFailureLookupRetryDelaysMs();
+  let lastError = null;
+  let attempts = 0;
+  let result = null;
+  for (let attempt = 0; attempt <= retryDelays.length; attempt += 1) {
+    try {
+      attempts = attempt + 1;
+      result = await input2.client.queryCustomerDb({
+        sql,
+        maxRows: 1e3
+      });
+      lastError = null;
+      break;
+    } catch (error) {
+      lastError = error;
+      if (attempt >= retryDelays.length || !isRetryableCustomerDbLookupError(error)) {
+        break;
+      }
+      const delayMs = retryDelays[attempt] ?? 0;
+      emitEnrichDebug(
+        `customer_db failure lookup retrying after ${delayMs}ms: ${formatEnrichDiagnosticError(error)}`
+      );
+      if (delayMs > 0) {
+        await sleep6(delayMs);
+      }
+    }
+  }
+  if (!result) {
+    return {
+      jobs: [],
+      issue: customerDbLookupUnavailableIssue({
+        customerDb,
+        error: lastError,
+        attempts
+      })
+    };
+  }
   const rows = Array.isArray(result.rows) ? result.rows : [];
   const failedRows = rows.filter((row) => {
     const status = typeof row._status === "string" ? row._status.trim().toLowerCase() : "";
     return typeof row._error === "string" && row._error.trim() || status === "failed" || status === "error";
   });
-  return failedRows.map((row, index) => {
+  const jobs = failedRows.map((row, index) => {
     const metaFailure = failureAliasFromCellMeta(row._cell_meta);
     const alias = metaFailure?.alias ?? fallbackAlias;
     const normalizedAlias = normalizeAlias2(alias);
@@ -18756,6 +18855,7 @@ async function collectCustomerDbFailureJobs(input2) {
       ...metaFailure?.provider ? { provider: metaFailure.provider } : {}
     };
   });
+  return { jobs, issue: null };
 }
 async function buildEnrichFailureReport(input2) {
   const fallbackRowsInfo = input2.exportResult ? null : extractCanonicalRowsInfo(input2.status);
@@ -19283,9 +19383,7 @@ function collectWaterfallAliasSpecs(config) {
       alias,
       childAliases: activeChildren.map((child) => child.alias).filter(Boolean),
       childRunIfJsByAlias: new Map(
-        activeChildren.map(
-          (child) => [child.alias, child.run_if_js]
-        )
+        activeChildren.map((child) => [child.alias, child.run_if_js])
       ),
       childToolsByAlias: new Map(
         activeChildren.map(
@@ -20061,21 +20159,26 @@ async function maybeEmitEnrichFailureReport(input2) {
     status: input2.status,
     rowRange: input2.statusRowRange ?? input2.rowRange
   });
-  const customerDbJobs = input2.status === void 0 || rowJobs.length > 0 || statusJobs.length > 0 ? [] : await collectCustomerDbFailureJobs({
+  const customerDbDiagnostics = input2.status === void 0 || rowJobs.length > 0 || statusJobs.length > 0 ? { jobs: [], issue: null } : await collectCustomerDbFailureJobs({
     client: input2.client,
     status: input2.status,
     config: input2.config
   });
+  const customerDbJobs = customerDbDiagnostics.jobs;
+  if (customerDbDiagnostics.issue) {
+    emitCustomerDbLookupUnavailableWarning(customerDbDiagnostics.issue);
+  }
+  const allEnrichIssues = enrichIssues;
   const jobs = rowJobs.length > 0 || statusJobs.length > 0 || customerDbJobs.length > 0 || input2.status === void 0 ? mergeEnrichFailureJobs(
     mergeEnrichFailureJobs(rowJobs, statusJobs),
     customerDbJobs
   ) : [];
-  if (jobs.length === 0 && enrichIssues.length === 0) {
+  if (jobs.length === 0 && allEnrichIssues.length === 0) {
     return null;
   }
   const reportPath = await persistEnrichFailureReport({
     jobs,
-    issues: enrichIssues,
+    issues: allEnrichIssues,
     apiUrl: input2.client.baseUrl,
     outputPath: input2.outputPath,
     rows: input2.rowRange
@@ -20095,13 +20198,13 @@ async function maybeEmitEnrichFailureReport(input2) {
 `);
     }
   }
-  if (enrichIssues.length > 0) {
+  if (allEnrichIssues.length > 0) {
     process.stderr.write("Enrichment needs attention.\n");
     process.stderr.write("Issue preview (up to 5 enrichment issues):\n");
     process.stderr.write(
       "issue_id	column	severity	selected_rows	rows_with_value	message\n"
     );
-    for (const issue of enrichIssues.slice(0, 5)) {
+    for (const issue of allEnrichIssues.slice(0, 5)) {
       process.stderr.write(
         `${issue.issue_id}	${issue.column}	${issue.severity}	${issue.selected_rows}	${issue.rows_with_value}	${issue.message}
 `
@@ -20115,9 +20218,9 @@ async function maybeEmitEnrichFailureReport(input2) {
 `);
       }
     }
-    if (enrichIssues.length > 5) {
+    if (allEnrichIssues.length > 5) {
       process.stderr.write(
-        `Showing 5 of ${enrichIssues.length} enrichment issues.
+        `Showing 5 of ${allEnrichIssues.length} enrichment issues.
 `
       );
     }
@@ -20135,12 +20238,12 @@ async function maybeEmitEnrichFailureReport(input2) {
     process.stderr.write(
       jobs.length > 0 ? "Enrichment failed. See report above.\n" : "Enrichment produced no values for at least one requested waterfall. See issue preview above.\n"
     );
-    return { path: reportPath, jobs, issues: enrichIssues };
+    return { path: reportPath, jobs, issues: allEnrichIssues };
   }
   process.stderr.write(
     jobs.length > 0 ? "Enrichment failed.\n" : "Enrichment needs attention.\n"
   );
-  return { path: "", jobs, issues: enrichIssues };
+  return { path: "", jobs, issues: allEnrichIssues };
 }
 function mergePreferredColumns(preferredColumns, rows) {
   const columns = [];

package/dist/index.js

@@ -422,10 +422,10 @@ var 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.187",
+  version: "0.1.188",
   apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.187",
+    latest: "0.1.188",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [

package/dist/index.mjs

@@ -352,10 +352,10 @@ var 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.187",
+  version: "0.1.188",
   apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.187",
+    latest: "0.1.188",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.1.187",
+  "version": "0.1.188",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {