deepline 0.3.180 → 0.3.182

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

@@ -200,7 +200,7 @@ export const 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.180',
+  version: '0.3.182',
   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: {

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

@@ -763,7 +763,10 @@ export interface PlayRunPackage {
     sqlQualifiedTableName?: string;
     recovered?: true;
     exportUnavailable?: {
-      reason: 'empty_dataset' | 'shared_table_namespace';
+      reason:
+        | 'empty_dataset'
+        | 'shared_table_namespace'
+        | 'returned_dataset_not_persisted';
       message: string;
     };
     preview?: Record<string, unknown>;

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

@@ -1073,6 +1073,7 @@ function getDbSessionCacheKey(input: {
   limits?: DbSessionLimits;
   sheetContract?: PlaySheetContract | null;
   userEmail?: string | null;
+  preloadedSessionId?: string | null;
 }): string {
   // Worker processes are long-lived. Include a hash of the executor token plus
   // the full requested access shape so a pooled runtime cannot reuse a scoped
@@ -1092,12 +1093,15 @@ function getDbSessionCacheKey(input: {
     JSON.stringify(input.limits ?? {}),
     JSON.stringify(input.sheetContract ?? null),
     input.userEmail?.trim() ?? '',
+    input.preloadedSessionId?.trim() ?? '',
   ].join('::');
 }
 
 function getRuntimeSheetEnsureCacheKey(input: {
   baseUrl?: string | null;
   orgId?: string | null;
+  postgresUrl?: string | null;
+  preloadedSessionId?: string | null;
   playName: string;
   runId?: string | null;
   tableNamespace: string;
@@ -1108,9 +1112,20 @@ function getRuntimeSheetEnsureCacheKey(input: {
     .update(JSON.stringify(input.sheetContract))
     .digest('hex')
     .slice(0, 24);
+  // A preloaded session can be replaced while the logical play/run/table
+  // identity stays the same. Do not reuse schema readiness from a different
+  // Neon database or role session. Keep both the raw credential and session
+  // identity out of the cache key and logs by hashing them together.
+  const sessionIdentityHash = createHash('sha256')
+    .update(input.postgresUrl?.trim() ?? '')
+    .update('\0')
+    .update(input.preloadedSessionId?.trim() ?? '')
+    .digest('hex')
+    .slice(0, 24);
   return [
     input.baseUrl?.trim() ?? '',
     input.orgId?.trim() ?? '',
+    sessionIdentityHash,
     input.playName,
     input.runId?.trim() ?? '',
     normalizeTableNamespace(input.tableNamespace),
@@ -1337,6 +1352,8 @@ async function ensureRuntimeSheetForPreloadedSession(
   const cacheKey = getRuntimeSheetEnsureCacheKey({
     baseUrl: context.baseUrl,
     orgId: input.session.target.orgId,
+    postgresUrl: input.session.postgresUrl,
+    preloadedSessionId: input.session.sessionId,
     playName: context.playName,
     runId: context.runId,
     tableNamespace: input.tableNamespace,
@@ -1461,6 +1478,22 @@ async function ensureRuntimeSheetForPreloadedSession(
   }
 }
 
+/**
+ * Test-only reset for the isolate-scoped runtime caches.
+ *
+ * Production workers intentionally retain these maps between requests. Tests
+ * that replace the Postgres driver or session fixtures must clear them so a
+ * prior case cannot satisfy a later case with a stale session or readiness
+ * promise.
+ */
+export function __resetRuntimeApiCachesForTests(): void {
+  dbSessionCache.clear();
+  dbSessionInFlight.clear();
+  postgresPools.clear();
+  runtimePostgresAdmissions.clear();
+  runtimeSheetEnsureCache.clear();
+}
+
 function operationsSatisfyRequest(
   candidate: readonly DbSessionOperation[],
   requested: readonly DbSessionOperation[],
@@ -1661,6 +1694,11 @@ async function getRuntimeDbSession(
   },
 ): Promise<CreateDbSessionResponse> {
   const userEmail = normalizeRuntimeUserEmail(context.userEmail);
+  // Preloaded sessions are supplied by the caller and can change while the
+  // logical request shape remains identical. Include the matched session
+  // identity so a long-lived worker never returns a stale scoped database
+  // session after a refresh or test/preview reset.
+  const matchedPreloadedSession = findPreloadedRuntimeDbSession(context, input);
   const cacheKey = getDbSessionCacheKey({
     baseUrl: context.baseUrl,
     executorToken: context.executorToken,
@@ -1672,6 +1710,7 @@ async function getRuntimeDbSession(
     limits: input.limits,
     sheetContract: input.sheetContract,
     userEmail,
+    preloadedSessionId: matchedPreloadedSession?.sessionId,
   });
   const cached = dbSessionCache.get(cacheKey)?.session;
   if (cached) {
@@ -1687,7 +1726,7 @@ async function getRuntimeDbSession(
   }
 
   const sessionPromise = (async (): Promise<CreateDbSessionResponse> => {
-    const preloaded = findPreloadedRuntimeDbSession(context, input);
+    const preloaded = matchedPreloadedSession;
     if (preloaded) {
       const unwrappedPreloaded = await unwrapRuntimeDbSession(
         context,

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

@@ -13126,6 +13126,22 @@ function postgresSchedulerReceiptLeaseId(input: {
     : null;
 }
 
+function postgresSchedulerReceiptOwnerIsTerminalSql(
+  receiptTableReference: string,
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): string {
+  return `EXISTS (
+            SELECT 1
+              FROM ${tableName('runs', options)} AS receipt_owner_run
+             WHERE receipt_owner_run.run_id = COALESCE(
+                     ${receiptTableReference}.lease_owner_run_id,
+                     ${receiptTableReference}.run_id
+                   )
+               AND receipt_owner_run.org_id = ${receiptTableReference}.org_id
+               AND receipt_owner_run.status IN ('completed', 'failed', 'cancelled')
+          )`;
+}
+
 function mapReceiptRow(row: ReceiptRow): RuntimeStepReceipt {
   const leaseExpiresAt = row.lease_expires_at;
   const outputRef = isRuntimeReceiptValueReference(row.output_ref)
@@ -13429,6 +13445,11 @@ export async function claimPostgresSchedulerReceipt(
   );
   const leaseId =
     input.leaseId?.trim() || postgresSchedulerReceiptLeaseId(input);
+  const receiptTable = tableName('receipts', options);
+  const ownerIsTerminal = postgresSchedulerReceiptOwnerIsTerminalSql(
+    receiptTable,
+    options,
+  );
   const result = await client.query<ReceiptRow & { claim_state: string }>(
     `
       WITH terminal AS (
@@ -13436,14 +13457,14 @@ export async function claimPostgresSchedulerReceipt(
         -- explicitly forces refresh. Read them before the UPSERT so popular
         -- prebuilt keys do not take a conflicting-row lock or create WAL.
         SELECT k, status, output_json, output_ref, error, error_payload, failure_kind, run_id, lease_id, lease_owner_run_id, lease_owner_attempt, lease_expires_at
-          FROM ${tableName('receipts', options)}
+          FROM ${receiptTable}
          WHERE org_id = $9
            AND k = $1
            AND status IN ('completed', 'skipped')
            AND ($7::boolean IS NOT TRUE OR run_id = $2)
       ),
       claimed AS (
-        INSERT INTO ${tableName('receipts', options)} (
+        INSERT INTO ${receiptTable} (
           org_id,
           k,
           status,
@@ -13484,33 +13505,45 @@ export async function claimPostgresSchedulerReceipt(
             error_payload = NULL,
             failure_kind = 0,
             updated_at = now()
-        WHERE ${tableName('receipts', options)}.status = ANY($3::text[])
-          AND ${tableName('receipts', options)}.org_id = $9
+        WHERE ${receiptTable}.status = ANY($3::text[])
+          AND ${receiptTable}.org_id = $9
           AND (
-            ${tableName('receipts', options)}.status <> 'failed'
+            ${receiptTable}.status <> 'failed'
             OR $7::boolean
             OR $8::boolean
-            OR ${tableName('receipts', options)}.run_id IS DISTINCT FROM $2
+            OR ${receiptTable}.run_id IS DISTINCT FROM $2
           )
           AND (
-            ${tableName('receipts', options)}.status = 'failed'
-            OR ${tableName('receipts', options)}.lease_id IS NULL
-              AND ${tableName('receipts', options)}.lease_expires_at IS NULL
-            OR ${tableName('receipts', options)}.lease_expires_at <= now()
+            (
+              ${receiptTable}.status IN ('queued', 'running')
+              AND ${ownerIsTerminal}
+            )
             OR (
-              -- Billed-implies-durable: a higher scheduler invocation must never
-              -- steal a live work-receipt lease while the prior invocation may
-              -- still be inside a provider call. Same-run reclaims are allowed
-              -- only after the lease TTL proves the prior attempt is dead.
-              ${tableName('receipts', options)}.lease_id IS NOT NULL
-              AND ${tableName('receipts', options)}.lease_expires_at IS NOT NULL
-              AND ${tableName('receipts', options)}.lease_expires_at <= now()
-              AND
-              COALESCE(
-                ${tableName('receipts', options)}.lease_owner_run_id,
-                ${tableName('receipts', options)}.run_id
-              ) = $2
-              AND COALESCE(${tableName('receipts', options)}.lease_owner_attempt, 0) < $5::integer
+              (
+                ${receiptTable}.status NOT IN ('queued', 'running')
+                OR $10::boolean
+              )
+              AND (
+                ${receiptTable}.status = 'failed'
+                OR ${receiptTable}.lease_id IS NULL
+                  AND ${receiptTable}.lease_expires_at IS NULL
+                OR ${receiptTable}.lease_expires_at <= now()
+                OR (
+                  -- Billed-implies-durable: a higher scheduler invocation must never
+                  -- steal a live work-receipt lease while the prior invocation may
+                  -- still be inside a provider call. Same-run reclaims are allowed
+                  -- only after the lease TTL proves the prior attempt is dead.
+                  ${receiptTable}.lease_id IS NOT NULL
+                  AND ${receiptTable}.lease_expires_at IS NOT NULL
+                  AND ${receiptTable}.lease_expires_at <= now()
+                  AND
+                  COALESCE(
+                    ${receiptTable}.lease_owner_run_id,
+                    ${receiptTable}.run_id
+                  ) = $2
+                  AND COALESCE(${receiptTable}.lease_owner_attempt, 0) < $5::integer
+                )
+              )
             )
           )
         RETURNING k, status, output_json, output_ref, error, error_payload, failure_kind, run_id, lease_id, lease_owner_run_id, lease_owner_attempt, lease_expires_at
@@ -13530,13 +13563,14 @@ export async function claimPostgresSchedulerReceipt(
         ? ['pending', 'failed', 'running', 'completed', 'skipped']
         : input.reclaimRunning
           ? ['pending', 'failed', 'running']
-          : ['pending', 'failed'],
+          : ['pending', 'failed', 'queued', 'running'],
       leaseId,
       runAttempt,
       PLAY_RUNTIME_WORK_RECEIPT_LEASE_TTL_MS,
       input.forceRefresh === true,
       input.forceFailedRefresh === true,
       receiptOrgId(options),
+      input.forceRefresh === true || input.reclaimRunning === true,
     ],
   );
   if (result.rows[0]) {
@@ -13581,6 +13615,11 @@ export async function claimPostgresSchedulerReceipts(
     const providedLeaseId = input.leaseIds?.[index]?.trim();
     return providedLeaseId || postgresSchedulerReceiptLeaseId(input);
   });
+  const receiptTable = tableName('receipts', options);
+  const ownerIsTerminal = postgresSchedulerReceiptOwnerIsTerminalSql(
+    receiptTable,
+    options,
+  );
   const result = await client.query<ReceiptRow & { claim_state?: string }>(
     `
       WITH inputs AS (
@@ -13608,7 +13647,7 @@ export async function claimPostgresSchedulerReceipts(
                receipt.lease_expires_at,
                inputs.ord
           FROM inputs
-          JOIN ${tableName('receipts', options)} AS receipt
+          JOIN ${receiptTable} AS receipt
             ON receipt.org_id = $10
            AND receipt.k = inputs.k
          WHERE receipt.status IN ('completed', 'skipped')
@@ -13628,7 +13667,7 @@ export async function claimPostgresSchedulerReceipts(
          ORDER BY inputs.k, inputs.ord
       ),
       claimed AS (
-        INSERT INTO ${tableName('receipts', options)} (
+        INSERT INTO ${receiptTable} (
           org_id,
           k,
           status,
@@ -13668,19 +13707,31 @@ export async function claimPostgresSchedulerReceipts(
             error_payload = NULL,
             failure_kind = 0,
             updated_at = now()
-        WHERE ${tableName('receipts', options)}.status = ANY($3::text[])
-          AND ${tableName('receipts', options)}.org_id = $10
+        WHERE ${receiptTable}.status = ANY($3::text[])
+          AND ${receiptTable}.org_id = $10
           AND (
-            ${tableName('receipts', options)}.status <> 'failed'
+            ${receiptTable}.status <> 'failed'
             OR $7::boolean
             OR $8::boolean
-            OR ${tableName('receipts', options)}.run_id IS DISTINCT FROM $2
+            OR ${receiptTable}.run_id IS DISTINCT FROM $2
           )
           AND (
-            ${tableName('receipts', options)}.status = 'failed'
-            OR ${tableName('receipts', options)}.lease_id IS NULL
-              AND ${tableName('receipts', options)}.lease_expires_at IS NULL
-            OR ${tableName('receipts', options)}.lease_expires_at <= now()
+            (
+              ${receiptTable}.status IN ('queued', 'running')
+              AND ${ownerIsTerminal}
+            )
+            OR (
+              (
+                ${receiptTable}.status NOT IN ('queued', 'running')
+                OR $11::boolean
+              )
+              AND (
+                ${receiptTable}.status = 'failed'
+                OR ${receiptTable}.lease_id IS NULL
+                  AND ${receiptTable}.lease_expires_at IS NULL
+                OR ${receiptTable}.lease_expires_at <= now()
+              )
+            )
           )
         RETURNING k, status, output_json, output_ref, error, error_payload, failure_kind, run_id, lease_id, lease_owner_run_id, lease_owner_attempt, lease_expires_at
       ),
@@ -13703,7 +13754,7 @@ export async function claimPostgresSchedulerReceipts(
                  AS replayed_claim,
                inputs.ord
           FROM inputs
-          JOIN ${tableName('receipts', options)} AS receipt
+          JOIN ${receiptTable} AS receipt
             ON receipt.org_id = $10
            AND receipt.k = inputs.k
          WHERE (
@@ -13801,7 +13852,7 @@ export async function claimPostgresSchedulerReceipts(
         ? ['pending', 'failed', 'running', 'completed', 'skipped']
         : input.reclaimRunning
           ? ['pending', 'failed', 'running']
-          : ['pending', 'failed'],
+          : ['pending', 'failed', 'queued', 'running'],
       leaseIds,
       runAttempt,
       PLAY_RUNTIME_WORK_RECEIPT_LEASE_TTL_MS,
@@ -13809,6 +13860,7 @@ export async function claimPostgresSchedulerReceipts(
       input.forceFailedRefresh === true,
       input.forceRefresh === true,
       receiptOrgId(options),
+      input.forceRefresh === true || input.reclaimRunning === true,
     ],
   );
   return result.rows.map((row) =>
@@ -14511,9 +14563,9 @@ export async function releasePostgresSchedulerReceipt(
 
 /**
  * The write that returns a claimed receipt to the free pool. Every release
- * path shares it so a successor's non-forced claim — whose status set is
- * `('pending','failed')` and whose lease guard requires no live lease — always
- * matches what a dead owner left behind.
+ * path shares it so a successor's non-forced claim always matches what a dead
+ * owner left behind. Claimers also understand terminal ownership directly so
+ * a later writer release can stop rewriting every receipt synchronously.
  */
 const RELEASE_RECEIPT_TO_PENDING_SET_CLAUSE = `status = 'pending',
           output_json = NULL,

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

@@ -1786,14 +1786,13 @@ function applySerializedListDatasets(
     });
     if (Object.prototype.hasOwnProperty.call(result.toolResponse, 'rawV2')) {
       const view = result.toolResponse.view ?? 'rawV2';
-      if (view === 'data' && isRecord(result.toolResponse.rawV2)) {
-        result.toolResponse.rawV2 = {
-          ...result.toolResponse.rawV2,
-          data: result.toolResponse.raw,
-        };
-      } else {
-        result.toolResponse.rawV2 = result.toolResponse.raw;
-      }
+      result.toolResponse.rawV2 = rawV2WithSerializedListRows({
+        rawV2: result.toolResponse.rawV2,
+        view,
+        lists: result._metadata.lists,
+        listDatasets,
+        listRows,
+      });
     }
     Object.defineProperty(result, SERIALIZED_TOOL_LIST_ROWS, {
       value: listRows,
@@ -1886,15 +1885,32 @@ function responseMetaOutsideRawV2(input: {
   return Object.keys(responseMeta).length > 0 ? responseMeta : undefined;
 }
 
-function rawV2WithSerializedRawPreview(input: {
+function rawV2WithSerializedListRows(input: {
   rawV2: unknown;
   view: 'data' | 'rawV2';
-  raw: unknown;
+  lists: Record<string, ToolResultListMetadata>;
+  listDatasets:
+    | Record<string, SerializedPlayDataset<Record<string, unknown>>>
+    | undefined;
+  listRows: Record<string, Array<Record<string, unknown>>> | undefined;
 }): unknown {
   if (input.view === 'data' && isRecord(input.rawV2)) {
-    return { ...input.rawV2, data: input.raw };
+    return {
+      ...input.rawV2,
+      data: rawWithSerializedListRows({
+        raw: input.rawV2.data,
+        lists: input.lists,
+        listDatasets: input.listDatasets,
+        listRows: input.listRows,
+      }),
+    };
   }
-  return input.raw;
+  return rawWithSerializedListRows({
+    raw: input.rawV2,
+    lists: input.lists,
+    listDatasets: input.listDatasets,
+    listRows: input.listRows,
+  });
 }
 
 export function serializeToolExecuteResult(
@@ -1915,18 +1931,6 @@ export function serializeToolExecuteResult(
   });
   if (Object.prototype.hasOwnProperty.call(value.toolResponse, 'rawV2')) {
     const view = value.toolResponse.view ?? 'rawV2';
-    const rawV2 = rawV2WithSerializedRawPreview({
-      rawV2: value.toolResponse.rawV2,
-      view,
-      raw:
-        view === 'data'
-          ? serializedRaw
-          : serializedRawWithListPreviews({
-              raw: value.toolResponse.rawV2,
-              metadata,
-              listDatasets,
-            }),
-    });
     const responseMeta = responseMetaOutsideRawV2({
       rawV2: value.toolResponse.rawV2,
       view,
@@ -1939,8 +1943,20 @@ export function serializeToolExecuteResult(
       ...(isRecord(value.meta) ? { meta: value.meta } : {}),
       ...(isRecord(value.billing) ? { billing: value.billing } : {}),
       toolResponse: {
-        rawV2,
+        // rawV2 is the canonical complete provider response. Only the legacy
+        // compatibility projection is allowed to use bounded list previews.
+        rawV2: value.toolResponse.rawV2,
         view,
+        ...(sameJsonValue(
+          serializedRaw,
+          legacyRawFromToolResponseRawV2(
+            value.toolResponse.rawV2,
+            view,
+            responseMeta,
+          ),
+        )
+          ? {}
+          : { legacyRaw: serializedRaw }),
         ...(responseMeta ? { responseMeta } : {}),
       },
       ...(listDatasets ? { listDatasets } : {}),
@@ -2001,13 +2017,19 @@ export function deserializeToolExecuteResult(
       view,
       value.toolResponse.responseMeta,
     );
+    const legacyRaw = Object.prototype.hasOwnProperty.call(
+      value.toolResponse,
+      'legacyRaw',
+    )
+      ? value.toolResponse.legacyRaw
+      : raw;
     return applySerializedListDatasets(
       applySerializedTargetValues(
         createToolExecuteResult({
           status: value.status,
           jobId: value.job_id,
           result: {
-            data: raw,
+            data: legacyRaw,
             ...(Object.keys(meta).length > 0 ? { meta } : {}),
           },
           response: {

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

@@ -139,6 +139,8 @@ export type SerializedToolExecuteResultV2 = Omit<
   toolResponse: {
     rawV2: unknown;
     view: 'data' | 'rawV2';
+    /** Bounded legacy compatibility projection; canonical data stays in rawV2. */
+    legacyRaw?: unknown;
     /** Deepline-owned additions not already represented in `rawV2.meta`. */
     responseMeta?: Record<string, unknown>;
   };

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.180",
+  version: "0.3.182",
   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
@@ -14321,7 +14321,7 @@ function canonicalRowsInfoFromCandidate(input2) {
           candidate.value.recoveredReturnPaths
         )
       } : {},
-      ...isRecord8(candidate.value.exportUnavailable) && (candidate.value.exportUnavailable.reason === "empty_dataset" || candidate.value.exportUnavailable.reason === "shared_table_namespace") ? {
+      ...isRecord8(candidate.value.exportUnavailable) && (candidate.value.exportUnavailable.reason === "empty_dataset" || candidate.value.exportUnavailable.reason === "shared_table_namespace" || candidate.value.exportUnavailable.reason === "returned_dataset_not_persisted") ? {
         exportUnavailableReason: candidate.value.exportUnavailable.reason,
         ...typeof candidate.value.exportUnavailable.message === "string" ? {
           exportUnavailableMessage: candidate.value.exportUnavailable.message
@@ -26362,15 +26362,37 @@ function assertDatasetHasExportableRows(input2) {
   const datasetLabel = input2.datasetPath ?? input2.rowsInfo.tableNamespace ?? input2.rowsInfo.source ?? "result.rows";
   const available = input2.availableRows.map((info) => info.tableNamespace ?? info.source).filter((name) => typeof name === "string");
   const runStatus = String(input2.status.status ?? "").toLowerCase();
+  const advertisedRows = Math.max(
+    input2.rowsInfo.totalRows,
+    input2.rowsInfo.rows.length
+  );
+  const terminalRunWithMissingAdvertisedRows = advertisedRows > 0 && (runStatus === "completed" || runStatus === "failed" || runStatus === "cancelled");
+  const inspectCommand = `deepline runs get ${input2.status.runId} --full --json`;
+  const retryCommand = runExportRetryCommand(
+    input2.status.runId,
+    "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.`;
   throw new DeeplineError(
-    `Run ${input2.status.runId} has zero rows to export from dataset '${datasetLabel}'. The run status is '${runStatus || "unknown"}', so it likely failed before persisting rows to this dataset \u2014 provider calls may have been billed without a durable row. Fix the run's failure cause and re-run to resume.` + (available.length > 0 ? ` Available datasets: ${available.join(", ")}.` : " No datasets were materialized for this run."),
+    `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,
     "RUN_EXPORT_EMPTY",
     {
       runId: input2.status.runId,
       dataset: datasetLabel,
       available,
-      runStatus: runStatus || null
+      runStatus: runStatus || null,
+      guidance: terminalRunWithMissingAdvertisedRows ? {
+        inspect_command: inspectCommand,
+        retry_command: retryCommand,
+        do_not_rerun: true,
+        reason: "Run output is terminal but its rows are not attributed to this run; export refuses to guess another writer."
+      } : {
+        inspect_command: inspectCommand,
+        do_not_rerun: false,
+        reason: "The run did not prove that any rows were durably persisted for this dataset."
+      }
     }
   );
 }
@@ -26452,6 +26474,24 @@ ${commands.join("\n")}`,
       `Run ${status.runId} did not expose a row-shaped final output to export.`
     );
   }
+  if (rowsInfo.exportUnavailableReason === "returned_dataset_not_persisted") {
+    const datasetLabel = options.datasetPath ?? rowsInfo.source ?? rowsInfo.datasetId ?? "result.rows";
+    throw new DeeplineError(
+      rowsInfo.exportUnavailableMessage ?? `Run ${status.runId} returned rows for '${datasetLabel}' without a run-scoped durable dataset. Persist the rows with ctx.dataset("rows", rows).run() before returning them.`,
+      void 0,
+      "RUN_EXPORT_NOT_AVAILABLE",
+      {
+        runId: status.runId,
+        dataset: datasetLabel,
+        reason: rowsInfo.exportUnavailableReason,
+        guidance: {
+          do_not_rerun: false,
+          reason: "The returned rows exist only in the in-memory tool result.",
+          persist_rows: 'ctx.dataset("rows", rows).run()'
+        }
+      }
+    );
+  }
   const attempts = Math.max(1, Math.trunc(options.attempts ?? 1));
   const retryDelayMs = Math.max(0, Math.trunc(options.retryDelayMs ?? 0));
   for (let attempt = 1; attempt <= attempts; attempt += 1) {

package/dist/cli/index.mjs

@@ -3046,7 +3046,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.180",
+  version: "0.3.182",
   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
@@ -14336,7 +14336,7 @@ function canonicalRowsInfoFromCandidate(input2) {
           candidate.value.recoveredReturnPaths
         )
       } : {},
-      ...isRecord8(candidate.value.exportUnavailable) && (candidate.value.exportUnavailable.reason === "empty_dataset" || candidate.value.exportUnavailable.reason === "shared_table_namespace") ? {
+      ...isRecord8(candidate.value.exportUnavailable) && (candidate.value.exportUnavailable.reason === "empty_dataset" || candidate.value.exportUnavailable.reason === "shared_table_namespace" || candidate.value.exportUnavailable.reason === "returned_dataset_not_persisted") ? {
         exportUnavailableReason: candidate.value.exportUnavailable.reason,
         ...typeof candidate.value.exportUnavailable.message === "string" ? {
           exportUnavailableMessage: candidate.value.exportUnavailable.message
@@ -26434,15 +26434,37 @@ function assertDatasetHasExportableRows(input2) {
   const datasetLabel = input2.datasetPath ?? input2.rowsInfo.tableNamespace ?? input2.rowsInfo.source ?? "result.rows";
   const available = input2.availableRows.map((info) => info.tableNamespace ?? info.source).filter((name) => typeof name === "string");
   const runStatus = String(input2.status.status ?? "").toLowerCase();
+  const advertisedRows = Math.max(
+    input2.rowsInfo.totalRows,
+    input2.rowsInfo.rows.length
+  );
+  const terminalRunWithMissingAdvertisedRows = advertisedRows > 0 && (runStatus === "completed" || runStatus === "failed" || runStatus === "cancelled");
+  const inspectCommand = `deepline runs get ${input2.status.runId} --full --json`;
+  const retryCommand = runExportRetryCommand(
+    input2.status.runId,
+    "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.`;
   throw new DeeplineError(
-    `Run ${input2.status.runId} has zero rows to export from dataset '${datasetLabel}'. The run status is '${runStatus || "unknown"}', so it likely failed before persisting rows to this dataset \u2014 provider calls may have been billed without a durable row. Fix the run's failure cause and re-run to resume.` + (available.length > 0 ? ` Available datasets: ${available.join(", ")}.` : " No datasets were materialized for this run."),
+    `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,
     "RUN_EXPORT_EMPTY",
     {
       runId: input2.status.runId,
       dataset: datasetLabel,
       available,
-      runStatus: runStatus || null
+      runStatus: runStatus || null,
+      guidance: terminalRunWithMissingAdvertisedRows ? {
+        inspect_command: inspectCommand,
+        retry_command: retryCommand,
+        do_not_rerun: true,
+        reason: "Run output is terminal but its rows are not attributed to this run; export refuses to guess another writer."
+      } : {
+        inspect_command: inspectCommand,
+        do_not_rerun: false,
+        reason: "The run did not prove that any rows were durably persisted for this dataset."
+      }
     }
   );
 }
@@ -26524,6 +26546,24 @@ ${commands.join("\n")}`,
       `Run ${status.runId} did not expose a row-shaped final output to export.`
     );
   }
+  if (rowsInfo.exportUnavailableReason === "returned_dataset_not_persisted") {
+    const datasetLabel = options.datasetPath ?? rowsInfo.source ?? rowsInfo.datasetId ?? "result.rows";
+    throw new DeeplineError(
+      rowsInfo.exportUnavailableMessage ?? `Run ${status.runId} returned rows for '${datasetLabel}' without a run-scoped durable dataset. Persist the rows with ctx.dataset("rows", rows).run() before returning them.`,
+      void 0,
+      "RUN_EXPORT_NOT_AVAILABLE",
+      {
+        runId: status.runId,
+        dataset: datasetLabel,
+        reason: rowsInfo.exportUnavailableReason,
+        guidance: {
+          do_not_rerun: false,
+          reason: "The returned rows exist only in the in-memory tool result.",
+          persist_rows: 'ctx.dataset("rows", rows).run()'
+        }
+      }
+    );
+  }
   const attempts = Math.max(1, Math.trunc(options.attempts ?? 1));
   const retryDelayMs = Math.max(0, Math.trunc(options.retryDelayMs ?? 0));
   for (let attempt = 1; attempt <= attempts; attempt += 1) {

package/dist/index.d.mts

@@ -1680,7 +1680,7 @@ interface PlayRunPackage {
         sqlQualifiedTableName?: string;
         recovered?: true;
         exportUnavailable?: {
-            reason: 'empty_dataset' | 'shared_table_namespace';
+            reason: 'empty_dataset' | 'shared_table_namespace' | 'returned_dataset_not_persisted';
             message: string;
         };
         preview?: Record<string, unknown>;

package/dist/index.d.ts

@@ -1680,7 +1680,7 @@ interface PlayRunPackage {
         sqlQualifiedTableName?: string;
         recovered?: true;
         exportUnavailable?: {
-            reason: 'empty_dataset' | 'shared_table_namespace';
+            reason: 'empty_dataset' | 'shared_table_namespace' | 'returned_dataset_not_persisted';
             message: string;
         };
         preview?: Record<string, unknown>;

package/dist/index.js

@@ -864,7 +864,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.180",
+  version: "0.3.182",
   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

package/dist/index.mjs

@@ -768,7 +768,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.180",
+  version: "0.3.182",
   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

package/dist/release.d.mts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.180";
+    readonly version: "0.3.182";
     readonly 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.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.d.ts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.180";
+    readonly version: "0.3.182";
     readonly 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.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.js

@@ -74,7 +74,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.180",
+  version: "0.3.182",
   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

package/dist/release.mjs

@@ -48,7 +48,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.180",
+  version: "0.3.182",
   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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.3.180",
+  "version": "0.3.182",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",