deepline 0.1.238 → 0.1.239

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

@@ -365,6 +365,9 @@ function datasetAvailableLog(
   dataset: ReturnType<typeof runtimeDatasetIdentity>,
   count: number,
 ): string {
+  if (count === 0) {
+    return `Dataset ${dataset.path} available: 0 persisted rows; export unavailable: empty dataset`;
+  }
   return `Dataset ${dataset.path} available: ${count} persisted rows; export: deepline runs export ${runId} --dataset ${dataset.path} --out ${dataset.tableNamespace}.csv`;
 }
 

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

@@ -405,6 +405,7 @@ export type PlaySheetRow = {
 /** Runtime-sheet rows and aggregate progress for one dataset/table namespace. */
 export type PlaySheetRowsResult = {
   rows: PlaySheetRow[];
+  scope?: { kind: 'database' } | { kind: 'run'; runId: string };
   summary?: {
     stats?: {
       total?: number;
@@ -470,6 +471,15 @@ export type RunsNamespace = {
   stopAll: (options?: { reason?: string }) => Promise<StopAllPlayRunsResult>;
 };
 
+/** Current mutable customer database namespace exposed as `client.db`. */
+export type DbNamespace = {
+  /** Run a bounded SQL query against the current customer data plane. */
+  query: (input: {
+    sql: string;
+    maxRows?: number;
+  }) => Promise<CustomerDbQueryResult>;
+};
+
 /** One credit grant pool reported by the billing subscription status endpoint. */
 export type BillingCreditPool = {
   pool: string;
@@ -1077,6 +1087,8 @@ export class DeeplineClient {
   private readonly config: ResolvedConfig;
   /** Canonical run lifecycle namespace backed by `/api/v2/runs`. */
   readonly runs: RunsNamespace;
+  /** Current mutable customer database namespace backed by `/api/v2/db/query`. */
+  readonly db: DbNamespace;
   /** Billing namespace: subscription status/cancel and invoice history. */
   readonly billing: BillingNamespace;
 
@@ -1101,6 +1113,9 @@ export class DeeplineClient {
       stop: (runId, options) => this.stopRun(runId, options),
       stopAll: (options) => this.stopAllRuns(options),
     };
+    this.db = {
+      query: (input) => this.queryDb(input),
+    };
     this.billing = {
       topUp: (options) => this.topUpBillingBalance(options),
       plans: () => this.getBillingPlans(),
@@ -1460,20 +1475,36 @@ export class DeeplineClient {
     return this.executeTool<TData, TMeta>(toolId, input, options);
   }
 
+  private async queryDb(input: {
+    sql: string;
+    maxRows?: number;
+  }): Promise<CustomerDbQueryResult> {
+    const result = await this.http.post<CustomerDbQueryResult>(
+      '/api/v2/db/query',
+      {
+        sql: input.sql,
+        ...(input.maxRows ? { max_rows: input.maxRows } : {}),
+      },
+    );
+    return {
+      ...result,
+      scope: { kind: 'database', mutability: 'current' },
+    };
+  }
+
   /**
-   * Run a bounded SQL query against the customer data plane.
+   * Run a bounded SQL query against the current mutable customer database.
+   *
+   * This query is not scoped to one play run. Use `client.runs` export actions
+   * when the caller needs the rows produced by a specific run.
    *
-   * Use this from trusted backend or agent contexts only. The API enforces
-   * workspace scoping and row limits.
+   * @deprecated Use {@link DeeplineClient.db} `.query(...)`.
    */
   async queryCustomerDb(input: {
     sql: string;
     maxRows?: number;
   }): Promise<CustomerDbQueryResult> {
-    return this.http.post<CustomerDbQueryResult>('/api/v2/db/query', {
-      sql: input.sql,
-      ...(input.maxRows ? { max_rows: input.maxRows } : {}),
-    });
+    return this.db.query(input);
   }
 
   /**
@@ -3000,9 +3031,42 @@ export class DeeplineClient {
     if (input.rowMode === 'all') {
       params.set('rowMode', 'all');
     }
-    return await this.http.get<PlaySheetRowsResult>(
+    const result = await this.http.get<PlaySheetRowsResult>(
       `/api/v2/plays/${encodeURIComponent(input.playName)}/sheet?${params.toString()}`,
     );
+    const requestedRunId = input.runId?.trim() || '';
+    if (requestedRunId) {
+      const confirmedRunId =
+        result.scope?.kind === 'run' ? result.scope.runId.trim() : '';
+      const foreignRowRunIds = [
+        ...new Set(
+          result.rows
+            .map((row) =>
+              typeof row.runId === 'string' ? row.runId.trim() : '',
+            )
+            .filter((runId) => runId && runId !== requestedRunId),
+        ),
+      ];
+      if (
+        result.scope?.kind !== 'run' ||
+        confirmedRunId !== requestedRunId ||
+        foreignRowRunIds.length > 0
+      ) {
+        throw new DeeplineError(
+          `Run-scoped dataset export was not confirmed for ${requestedRunId}; no rows were returned to the caller. Update Deepline, then retry the same export command. Do not rerun the play.`,
+          undefined,
+          'RUN_EXPORT_SCOPE_MISMATCH',
+          {
+            requestedRunId,
+            confirmedScope: result.scope ?? null,
+            foreignRowRunIds,
+            playName: input.playName,
+            tableNamespace: input.tableNamespace,
+          },
+        );
+      }
+    }
+    return result;
   }
 
   /**

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

@@ -218,6 +218,7 @@ export class HttpClient {
       'X-Deepline-CLI-Version': SDK_VERSION,
       'X-Deepline-SDK-Version': SDK_VERSION,
       'X-Deepline-API-Contract': SDK_API_CONTRACT,
+      'X-Deepline-Run-Result-Shape': 'canonical',
       ...extra,
     };
     const skillsVersion = this.readSkillsVersionHeader();

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

@@ -62,6 +62,7 @@ export type {
   BillingInvoiceEntry,
   BillingInvoicesResult,
   BillingNamespace,
+  DbNamespace,
   BillingPaymentMethodSummary,
   BillingSubscriptionCancelResult,
   BillingSubscriptionStatus,
@@ -141,6 +142,9 @@ export type {
   LiveEventEnvelope,
   PlayLiveEvent,
   PlayRunResult,
+  PlayRunActionPackage,
+  PlayRunDatasetActions,
+  PlayRunPackage,
   PlayRunStart,
   ClearPlayHistoryRequest,
   ClearPlayHistoryResult,

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

@@ -110,10 +110,10 @@ export const SDK_RELEASE = {
   // silently materializing them as unmatched results.
   // 0.1.220 deprecates SDK CLI versions below 0.1.219 and updates them
   // automatically without blocking their current command.
-  version: '0.1.238',
+  version: '0.1.239',
   apiContract: '2026-06-dataset-handle-results-hard-cutover',
   supportPolicy: {
-    latest: '0.1.238',
+    latest: '0.1.239',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.219',
     commandMinimumSupported: [

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

@@ -72,12 +72,14 @@ export interface CustomerDbColumn {
 }
 
 /**
- * Result returned by {@link DeeplineClient.queryCustomerDb}.
+ * Result returned by {@link DeeplineClient.db.query}.
  *
  * Rows are intentionally untyped because the schema depends on the caller's SQL
  * query and selected customer tables.
  */
 export interface CustomerDbQueryResult {
+  /** This query reads the current mutable customer database, not one run snapshot. */
+  scope?: { kind: 'database'; mutability: 'current' };
   /** Database command executed by the query endpoint. */
   command: string;
   /** Total affected row count when reported by the database. */
@@ -443,6 +445,19 @@ export type PlayRunActionPackage =
   | {
       kind: 'deepline_run_inspect';
       runId: string;
+      command?: string;
+      api: { method: 'GET'; path: string };
+    }
+  | {
+      kind: 'deepline_run_full';
+      runId: string;
+      command?: string;
+      api: { method: 'GET'; path: string };
+    }
+  | {
+      kind: 'deepline_run_billing';
+      runId: string;
+      command?: string;
       api: { method: 'GET'; path: string };
     }
   | {
@@ -453,6 +468,16 @@ export type PlayRunActionPackage =
       sqlQualifiedTableName?: string;
       sql: string;
       maxRows: number;
+      command?: string;
+      scope?:
+        | { kind: 'database'; mutability: 'current' }
+        | { kind: 'run'; runId: string };
+      note?: string;
+      deprecated?: {
+        replacement: 'queryCurrentTable';
+        removeAfter: string;
+        reason: string;
+      };
       api: {
         method: 'POST';
         path: '/api/v2/db/query';
@@ -463,6 +488,14 @@ export type PlayRunActionPackage =
       runId: string;
       datasetPath: string;
       format: 'csv';
+      command?: string;
+      scope?: { kind: 'run'; runId: string };
+      note?: string;
+      deprecated?: {
+        replacement: 'datasets[].actions.exportCsv';
+        removeAfter: string;
+        reason: string;
+      };
     }
   | {
       kind: 'deepline_run_logs';
@@ -473,6 +506,26 @@ export type PlayRunActionPackage =
       api: { method: 'GET'; path: string };
     };
 
+type PlayRunDbQueryAction = Extract<
+  PlayRunActionPackage,
+  { kind: 'deepline_db_query' }
+>;
+type PlayRunExportAction = Extract<
+  PlayRunActionPackage,
+  { kind: 'deepline_run_export' }
+>;
+
+export type PlayRunDatasetActions = {
+  /** @deprecated Use queryCurrentTable or exportCsv. Removed after 2026-08-18. */
+  query?: PlayRunDbQueryAction & { scope?: { kind: 'run'; runId: string } };
+  queryCurrentTable?: PlayRunDbQueryAction & {
+    scope?: { kind: 'database'; mutability: 'current' };
+  };
+  exportCsv?: PlayRunExportAction & {
+    scope?: { kind: 'run'; runId: string };
+  };
+};
+
 /**
  * Compact canonical package for an inspected play run.
  *
@@ -508,9 +561,15 @@ export interface PlayRunPackage {
     path: string;
     tableNamespace?: string;
     rowCount?: number;
+    sqlTableName?: string;
+    sqlQualifiedTableName?: string;
     recovered?: true;
+    exportUnavailable?: {
+      reason: 'empty_dataset' | 'shared_table_namespace';
+      message: string;
+    };
     preview?: Record<string, unknown>;
-    actions?: Record<string, PlayRunActionPackage>;
+    actions?: PlayRunDatasetActions;
   }>;
   /** Small retained tail of customer and runtime logs; fetch the full stream through `runs.logs`. */
   logs?: {
@@ -522,6 +581,8 @@ export interface PlayRunPackage {
   /** Follow-up actions a caller can perform against the run. */
   next?: {
     inspect?: PlayRunActionPackage;
+    full?: PlayRunActionPackage;
+    billing?: PlayRunActionPackage;
     export?: PlayRunActionPackage;
     query?: PlayRunActionPackage;
     logs?: PlayRunActionPackage;

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

@@ -1202,7 +1202,6 @@ export class PlayContextImpl {
   }> = [];
   private processedRowCount = 0;
   private sleepBoundaryIndex = 0;
-  private fetchCallIndex = 0;
   private readonly secretRedactor: SecretRedactionContext =
     createSecretRedactionContext();
   private mapInvocationIndex = 0;
@@ -5908,7 +5907,10 @@ export class PlayContextImpl {
       if (!this.toolBatchQueuedAtByKey.has(batchKey)) {
         this.toolBatchQueuedAtByKey.set(batchKey, queuedAt);
       }
-      const deadline = queuedAt + TOOL_BATCH_COALESCE_WINDOW_MS;
+      const coalesceWindowMs =
+        this.#options.toolBatchCoalesceWindowMs ??
+        TOOL_BATCH_COALESCE_WINDOW_MS;
+      const deadline = queuedAt + coalesceWindowMs;
       const maxBatchSize = batchMaxSizes.get(batchKey) ?? 1;
       if (count >= maxBatchSize || deadline <= nowMs) {
         readyBatchKeys.add(batchKey);
@@ -6818,11 +6820,15 @@ export class PlayContextImpl {
     options?: FetchOptions,
   ): Promise<PlayFetchResponse> {
     const normalizedKey = this.normalizeContextKey(key, 'fetch');
-    if (rowContext.getStore()) {
-      throw new Error(
-        'ctx.fetch() must run outside ctx.dataset(); use ctx.tools.execute(...) for row-level external requests so Deepline can batch and checkpoint them.',
-      );
-    }
+    const rowStore = rowContext.getStore();
+    const rowFetchScope = rowStore
+      ? {
+          tableNamespace: rowStore.tableNamespace ?? null,
+          rowKey: rowStore.rowKey ?? null,
+          rowId: rowStore.rowKey ? null : rowStore.rowId,
+          fieldName: rowStore.fieldName ?? null,
+        }
+      : null;
 
     if (valueContainsSecret(input) || valueContainsSecret(init.body)) {
       throw new Error(
@@ -6858,6 +6864,7 @@ export class PlayContextImpl {
               ...normalizeFetchHeaders(init.headers),
               ...secretHeaderMarkers,
             },
+            row: rowFetchScope,
           }),
         ),
         staleAfterSeconds: options?.staleAfterSeconds,
@@ -6872,7 +6879,7 @@ export class PlayContextImpl {
           const fetchInit = { ...init, headers };
           delete fetchInit.auth;
           const boundaryId = this.durableBoundaryId(
-            `fetch-${this.fetchCallIndex}-${stableDigest(
+            `fetch-${stableDigest(
               stableStringify({
                 url,
                 method,
@@ -6881,10 +6888,10 @@ export class PlayContextImpl {
                   ...secretHeaderMarkers,
                 },
                 body: typeof init.body === 'string' ? init.body : null,
+                row: rowFetchScope,
               }),
             )}`,
           );
-          this.fetchCallIndex += 1;
 
           const existing = this.checkpoint.resolvedBoundaries?.[boundaryId];
           if (existing?.kind === 'fetch' && 'output' in existing) {

package/dist/bundling-sources/shared_libs/play-runtime/ctx-types.ts

@@ -680,6 +680,11 @@ export interface ContextOptions {
   getBatchOperationStrategy?: (
     operation: string,
   ) => AnyBatchOperationStrategy | null;
+  // How long batchable calls wait for same-key row continuations before
+  // dispatching, measured from the first queued item. Defaults to 5ms in
+  // production; tests override it to a large value to make coalescing
+  // deterministic instead of racing wall-clock milliseconds on slow CI.
+  toolBatchCoalesceWindowMs?: number;
   queryCustomerDb?: CustomerDbQueryHandler;
   executeStructuredPlayDefinition?: (input: {
     definition: PlayStructuredDefinition;

package/dist/bundling-sources/shared_libs/play-runtime/play-latency-trace.ts

@@ -127,14 +127,13 @@ export const PLAY_LATENCY_SUMMARY_COLUMNS: PlayLatencyPhaseDefinition[] = [
     phase: 'server.start_route_runtime_data_plane_ready',
     source: 'server',
     description:
-      'Start route Runtime Sheet Data Plane readiness check; active tenants use the cached or record fast path, new tenants may provision here.',
+      'Start route read-only Runtime Sheet Data Plane readiness check.',
   },
   {
     header: 'ready_plane',
-    phase: 'server.runtime_data_plane_ensure_plane',
+    phase: 'server.runtime_data_plane_read_plane',
     source: 'server',
-    description:
-      'Runtime Sheet readiness control-plane record lookup or first-workspace provisioning.',
+    description: 'Runtime Sheet readiness control-plane record lookup.',
   },
   {
     header: 'ready_markers',
@@ -143,20 +142,6 @@ export const PLAY_LATENCY_SUMMARY_COLUMNS: PlayLatencyPhaseDefinition[] = [
     description:
       'Single pooled tenant-Postgres read of the storage-contract fingerprint and runtime migration version.',
   },
-  {
-    header: 'ready_repair',
-    phase: 'server.runtime_data_plane_repair_contract',
-    source: 'server',
-    description:
-      'Exceptional stale storage-contract repair; absent from the healthy path.',
-  },
-  {
-    header: 'ready_migrate',
-    phase: 'server.runtime_data_plane_migrate',
-    source: 'server',
-    description:
-      'Exceptional stale Runtime Sheet migration; absent from the healthy path.',
-  },
   {
     header: 'route_wait',
     phase: 'server.start_route_wait_completion',

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

@@ -224,6 +224,20 @@ export type PlayRunnerRuntimeTiming = {
   daytonaExecuteMs?: number;
 };
 
+/**
+ * Why replay checkpoint state is present or absent on the detached-runner
+ * terminal wire. This describes checkpoint transport only; it never classifies
+ * the customer's returned output as oversized.
+ */
+export const RUNNER_TERMINAL_CHECKPOINT_DISPOSITION = {
+  OMITTED_TERMINAL_REPLAY: 'omitted_terminal_replay',
+  INCLUDED_RESUME_REQUIRED: 'included_resume_required',
+  ABSENT: 'absent',
+} as const;
+
+export type RunnerTerminalCheckpointDisposition =
+  (typeof RUNNER_TERMINAL_CHECKPOINT_DISPOSITION)[keyof typeof RUNNER_TERMINAL_CHECKPOINT_DISPOSITION];
+
 export type PlayRunnerResult =
   | {
       status: 'completed';

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona-payload-transport.ts

@@ -1,7 +1,10 @@
 import { randomUUID } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { gzipSync } from 'node:zlib';
-import type { PlayRunnerExecutionConfig } from '@shared_libs/play-runtime/protocol';
+import {
+  RUNNER_TERMINAL_CHECKPOINT_DISPOSITION,
+  type PlayRunnerExecutionConfig,
+} from '@shared_libs/play-runtime/protocol';
 import {
   PLAY_RUNTIME_CONTRACT,
   PLAY_RUNTIME_CONTRACT_HEADER,
@@ -126,6 +129,39 @@ function readResultFromOutput() {
   return null;
 }
 
+function terminalResultForTransport(result) {
+  if (
+    result &&
+    ${JSON.stringify(Object.values(RUNNER_TERMINAL_CHECKPOINT_DISPOSITION))}.includes(
+      result.checkpointDisposition,
+    )
+  ) {
+    return result;
+  }
+  if (result && result.status === 'suspended') {
+    return {
+      ...result,
+      checkpointDisposition: '${RUNNER_TERMINAL_CHECKPOINT_DISPOSITION.INCLUDED_RESUME_REQUIRED}',
+      checkpointBytes: Buffer.byteLength(JSON.stringify(result.checkpoint)),
+    };
+  }
+  const checkpoint = result && result.checkpoint;
+  const terminal = { ...(result || {}) };
+  delete terminal.checkpoint;
+  if (checkpoint === null || checkpoint === undefined) {
+    return {
+      ...terminal,
+      checkpointDisposition: '${RUNNER_TERMINAL_CHECKPOINT_DISPOSITION.ABSENT}',
+      checkpointBytes: 0,
+    };
+  }
+  return {
+    ...terminal,
+    checkpointDisposition: '${RUNNER_TERMINAL_CHECKPOINT_DISPOSITION.OMITTED_TERMINAL_REPLAY}',
+    checkpointBytes: Buffer.byteLength(JSON.stringify(checkpoint)),
+  };
+}
+
 async function main() {
   const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
   const context = (config && config.context) || {};
@@ -136,7 +172,8 @@ async function main() {
     console.log('[crash-terminal] no push config; skipping');
     return;
   }
-  const result = readResultFromOutput() || {
+  const parsedResult = readResultFromOutput();
+  const result = terminalResultForTransport(parsedResult || {
     status: 'failed',
     error:
       'Daytona play runner exited with code ' +
@@ -146,9 +183,10 @@ async function main() {
     logs: [],
     stats: {},
     steps: [],
-    checkpoint: null,
+    checkpointDisposition: '${RUNNER_TERMINAL_CHECKPOINT_DISPOSITION.ABSENT}',
+    checkpointBytes: 0,
     tableNamespace: null,
-  };
+  });
   for (let attempt = 1; attempt <= 3; attempt += 1) {
     try {
       const controller = new AbortController();

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona-session-execution.ts

@@ -112,7 +112,10 @@ export type DetachedDaytonaCommandStart = {
   cmdId: string;
 };
 
-const DAYTONA_RUNNER_READY_TIMEOUT_MS = 3_000;
+// The marker now proves artifact materialization plus an accepted gateway
+// heartbeat. Keep the handoff bounded, while allowing a cold Fly gateway and
+// one timed-out heartbeat request to recover before the worker rejects it.
+export const DAYTONA_RUNNER_READY_TIMEOUT_MS = 60_000;
 const DAYTONA_RUNNER_READY_POLL_MS = 250;
 
 export class DaytonaRunnerInitializationError extends Error {
@@ -150,9 +153,10 @@ export async function startDetachedDaytonaCommand(input: {
 
 /**
  * A detached command id only proves that Daytona accepted the request. Before
- * the worker parks, require a marker written by the initialized runner process.
- * This closes the unobservable handoff where a sandbox or command disappears
- * after executeSessionCommand but before the first gateway heartbeat.
+ * the worker parks, require a marker written only after the initialized runner
+ * materializes its artifact and the receipt gateway accepts its first
+ * heartbeat. This closes the unobservable handoff where a sandbox or command
+ * disappears after executeSessionCommand but before durable runner liveness.
  */
 export async function confirmDetachedDaytonaRunnerReady(input: {
   sandbox: DaytonaSandbox;
@@ -200,6 +204,6 @@ export async function confirmDetachedDaytonaRunnerReady(input: {
   const oomIndicated =
     diagnostic.exitCode === 137 || diagnostic.exitCodeFile === 137;
   throw new DaytonaRunnerInitializationError(
-    `RUNTIME_SANDBOX_START_FAILED: Daytona accepted detached command ${input.cmdId} in sandbox ${input.sandbox.id}, but the play runner did not initialize within ${timeoutMs}ms. Marker diagnosis: ${markerDiagnosis}. Daytona diagnosis: ${JSON.stringify(diagnostic)}. OOM is ${oomIndicated ? 'indicated by exit code 137' : 'not confirmed by the available Daytona evidence'}. The play was stopped and was not retried.`,
+    `RUNTIME_SANDBOX_START_FAILED: Daytona accepted detached command ${input.cmdId} in sandbox ${input.sandbox.id}, but the play runner did not materialize and establish receipt-gateway liveness within ${timeoutMs}ms. Marker diagnosis: ${markerDiagnosis}. Daytona diagnosis: ${JSON.stringify(diagnostic)}. OOM is ${oomIndicated ? 'indicated by exit code 137' : 'not confirmed by the available Daytona evidence'}. The play was stopped and was not retried.`,
   );
 }

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona.ts

@@ -785,11 +785,11 @@ export const daytonaPlayRunnerBackend: PlayRunnerBackend = {
           });
           // Push execution (B2-final, park-and-wake): start the runner command
           // DETACHED via a Daytona session and return a `detached_runner`
-          // suspension after the runner writes its one-time ready marker. The
-          // marker is the handoff proof: a Daytona cmdId alone does not prove
-          // the sandbox process initialized. After that bounded startup check,
-          // the worker parks (releasing its claim and slot) and wakes only on
-          // the runner's pushed terminal or the ceiling timeout.
+          // suspension only after the runner writes its one-time ready marker.
+          // The marker proves artifact materialization and an accepted gateway
+          // heartbeat: a Daytona cmdId alone does not prove durable liveness.
+          // After that bounded startup check, the worker parks (releasing its
+          // claim and slot) and wakes on terminal push or the ceiling timeout.
           const sessionId = `deepline-play-${randomUUID()}`;
           let start: Awaited<ReturnType<typeof startDetachedDaytonaCommand>>;
           try {