deepline 0.1.238 → 0.1.239

package/dist/index.d.mts

@@ -85,12 +85,17 @@ interface CustomerDbColumn {
     data_type_id: number | null;
 }
 /**
- * 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.
  */
 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. */
@@ -410,6 +415,23 @@ interface PlayProgressStatus {
 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;
@@ -422,6 +444,20 @@ 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';
@@ -431,6 +467,17 @@ 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';
     runId: string;
@@ -442,6 +489,33 @@ type PlayRunActionPackage = {
         path: string;
     };
 };
+type PlayRunDbQueryAction = Extract<PlayRunActionPackage, {
+    kind: 'deepline_db_query';
+}>;
+type PlayRunExportAction = Extract<PlayRunActionPackage, {
+    kind: 'deepline_run_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.
  *
@@ -477,9 +551,15 @@ 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?: {
@@ -491,6 +571,8 @@ 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;
@@ -1363,6 +1445,12 @@ type PlaySheetRow = {
 /** Runtime-sheet rows and aggregate progress for one dataset/table namespace. */
 type PlaySheetRowsResult = {
     rows: PlaySheetRow[];
+    scope?: {
+        kind: 'database';
+    } | {
+        kind: 'run';
+        runId: string;
+    };
     summary?: {
         stats?: {
             total?: number;
@@ -1426,6 +1514,14 @@ type RunsNamespace = {
         reason?: string;
     }) => Promise<StopAllPlayRunsResult>;
 };
+/** Current mutable customer database namespace exposed as `client.db`. */
+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. */
 type BillingCreditPool = {
     pool: string;
@@ -1640,6 +1736,8 @@ declare class DeeplineClient {
     private readonly config;
     /** 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;
     /**
@@ -1746,11 +1844,14 @@ declare class DeeplineClient {
      * envelope remains the same.
      */
     executeToolRaw<TData = unknown, TMeta = Record<string, unknown>>(toolId: string, input: Record<string, unknown>, options?: ExecuteToolRawOptions): Promise<ToolExecution<TData, TMeta>>;
+    private queryDb;
     /**
-     * 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(...)`.
      */
     queryCustomerDb(input: {
         sql: string;
@@ -4412,4 +4513,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FileInput, JOB_CHANGE_STATUS_VALUES, type JobChangeStatus, type LiveEventEnvelope, PHONE_STATUS_VALUES, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PhoneStatus, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PreviousCell, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolExecutionRequest, type ToolMetadata, type ToolSearchOptions, type ToolSearchResult, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FileInput, JOB_CHANGE_STATUS_VALUES, type JobChangeStatus, type LiveEventEnvelope, PHONE_STATUS_VALUES, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PhoneStatus, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunDatasetActions, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PreviousCell, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolExecutionRequest, type ToolMetadata, type ToolSearchOptions, type ToolSearchResult, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };

package/dist/index.d.ts

@@ -85,12 +85,17 @@ interface CustomerDbColumn {
     data_type_id: number | null;
 }
 /**
- * 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.
  */
 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. */
@@ -410,6 +415,23 @@ interface PlayProgressStatus {
 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;
@@ -422,6 +444,20 @@ 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';
@@ -431,6 +467,17 @@ 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';
     runId: string;
@@ -442,6 +489,33 @@ type PlayRunActionPackage = {
         path: string;
     };
 };
+type PlayRunDbQueryAction = Extract<PlayRunActionPackage, {
+    kind: 'deepline_db_query';
+}>;
+type PlayRunExportAction = Extract<PlayRunActionPackage, {
+    kind: 'deepline_run_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.
  *
@@ -477,9 +551,15 @@ 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?: {
@@ -491,6 +571,8 @@ 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;
@@ -1363,6 +1445,12 @@ type PlaySheetRow = {
 /** Runtime-sheet rows and aggregate progress for one dataset/table namespace. */
 type PlaySheetRowsResult = {
     rows: PlaySheetRow[];
+    scope?: {
+        kind: 'database';
+    } | {
+        kind: 'run';
+        runId: string;
+    };
     summary?: {
         stats?: {
             total?: number;
@@ -1426,6 +1514,14 @@ type RunsNamespace = {
         reason?: string;
     }) => Promise<StopAllPlayRunsResult>;
 };
+/** Current mutable customer database namespace exposed as `client.db`. */
+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. */
 type BillingCreditPool = {
     pool: string;
@@ -1640,6 +1736,8 @@ declare class DeeplineClient {
     private readonly config;
     /** 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;
     /**
@@ -1746,11 +1844,14 @@ declare class DeeplineClient {
      * envelope remains the same.
      */
     executeToolRaw<TData = unknown, TMeta = Record<string, unknown>>(toolId: string, input: Record<string, unknown>, options?: ExecuteToolRawOptions): Promise<ToolExecution<TData, TMeta>>;
+    private queryDb;
     /**
-     * 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(...)`.
      */
     queryCustomerDb(input: {
         sql: string;
@@ -4412,4 +4513,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FileInput, JOB_CHANGE_STATUS_VALUES, type JobChangeStatus, type LiveEventEnvelope, PHONE_STATUS_VALUES, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PhoneStatus, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PreviousCell, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolExecutionRequest, type ToolMetadata, type ToolSearchOptions, type ToolSearchResult, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FileInput, JOB_CHANGE_STATUS_VALUES, type JobChangeStatus, type LiveEventEnvelope, PHONE_STATUS_VALUES, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PhoneStatus, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunDatasetActions, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PreviousCell, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolExecutionRequest, type ToolMetadata, type ToolSearchOptions, type ToolSearchResult, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };

package/dist/index.js

@@ -426,10 +426,10 @@ var 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: [
@@ -691,6 +691,7 @@ var HttpClient = class {
       "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();
@@ -2504,6 +2505,8 @@ var DeeplineClient = class {
   config;
   /** Canonical run lifecycle namespace backed by `/api/v2/runs`. */
   runs;
+  /** Current mutable customer database namespace backed by `/api/v2/db/query`. */
+  db;
   /** Billing namespace: subscription status/cancel and invoice history. */
   billing;
   /**
@@ -2527,6 +2530,9 @@ var DeeplineClient = class {
       stop: (runId, options2) => this.stopRun(runId, options2),
       stopAll: (options2) => this.stopAllRuns(options2)
     };
+    this.db = {
+      query: (input) => this.queryDb(input)
+    };
     this.billing = {
       topUp: (options2) => this.topUpBillingBalance(options2),
       plans: () => this.getBillingPlans(),
@@ -2793,17 +2799,29 @@ var DeeplineClient = class {
   async executeToolRaw(toolId, input, options) {
     return this.executeTool(toolId, input, options);
   }
+  async queryDb(input) {
+    const result = await this.http.post(
+      "/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) {
-    return this.http.post("/api/v2/db/query", {
-      sql: input.sql,
-      ...input.maxRows ? { max_rows: input.maxRows } : {}
-    });
+    return this.db.query(input);
   }
   /**
    * Re-establish this workspace's tenant storage contract: role/DB connect
@@ -3934,9 +3952,35 @@ var DeeplineClient = class {
     if (input.rowMode === "all") {
       params.set("rowMode", "all");
     }
-    return await this.http.get(
+    const result = await this.http.get(
       `/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.`,
+          void 0,
+          "RUN_EXPORT_SCOPE_MISMATCH",
+          {
+            requestedRunId,
+            confirmedScope: result.scope ?? null,
+            foreignRowRunIds,
+            playName: input.playName,
+            tableNamespace: input.tableNamespace
+          }
+        );
+      }
+    }
+    return result;
   }
   /**
    * Stop a run by id using the public runs resource model.

package/dist/index.mjs

@@ -356,10 +356,10 @@ var 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: [
@@ -621,6 +621,7 @@ var HttpClient = class {
       "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();
@@ -2434,6 +2435,8 @@ var DeeplineClient = class {
   config;
   /** Canonical run lifecycle namespace backed by `/api/v2/runs`. */
   runs;
+  /** Current mutable customer database namespace backed by `/api/v2/db/query`. */
+  db;
   /** Billing namespace: subscription status/cancel and invoice history. */
   billing;
   /**
@@ -2457,6 +2460,9 @@ var DeeplineClient = class {
       stop: (runId, options2) => this.stopRun(runId, options2),
       stopAll: (options2) => this.stopAllRuns(options2)
     };
+    this.db = {
+      query: (input) => this.queryDb(input)
+    };
     this.billing = {
       topUp: (options2) => this.topUpBillingBalance(options2),
       plans: () => this.getBillingPlans(),
@@ -2723,17 +2729,29 @@ var DeeplineClient = class {
   async executeToolRaw(toolId, input, options) {
     return this.executeTool(toolId, input, options);
   }
+  async queryDb(input) {
+    const result = await this.http.post(
+      "/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) {
-    return this.http.post("/api/v2/db/query", {
-      sql: input.sql,
-      ...input.maxRows ? { max_rows: input.maxRows } : {}
-    });
+    return this.db.query(input);
   }
   /**
    * Re-establish this workspace's tenant storage contract: role/DB connect
@@ -3864,9 +3882,35 @@ var DeeplineClient = class {
     if (input.rowMode === "all") {
       params.set("rowMode", "all");
     }
-    return await this.http.get(
+    const result = await this.http.get(
       `/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.`,
+          void 0,
+          "RUN_EXPORT_SCOPE_MISMATCH",
+          {
+            requestedRunId,
+            confirmedScope: result.scope ?? null,
+            foreignRowRunIds,
+            playName: input.playName,
+            tableNamespace: input.tableNamespace
+          }
+        );
+      }
+    }
+    return result;
   }
   /**
    * Stop a run by id using the public runs resource model.

package/package.json

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