deepline 0.1.302 → 0.1.304

package/dist/cli/index.js

@@ -222,33 +222,68 @@ function applyBrand(value, brand) {
   });
 }
 var DeeplineError = class _DeeplineError extends Error {
+  /** HTTP status when the failure crossed an HTTP boundary. */
+  statusCode;
+  /** Stable machine-readable error code when one exists. */
+  code;
+  /** Local diagnostic context; not a portable error contract. */
+  details;
+  /**
+   * Construct a Deepline error.
+   *
+   * SDK and runtime code construct these errors. Application and Play code
+   * normally catches the public subclasses instead.
+   *
+   * @param message Human-readable failure summary.
+   * @param statusCode HTTP status when one exists.
+   * @param code Stable machine-readable code when one exists.
+   * @param details Local diagnostic context; never a portable error contract.
+   */
   constructor(message, statusCode, code, details) {
     super(message);
+    this.name = "DeeplineError";
     this.statusCode = statusCode;
     this.code = code;
     this.details = details;
-    this.name = "DeeplineError";
     applyBrand(this, DEEPLINE_ERROR_BRAND);
   }
-  statusCode;
-  code;
-  details;
   static [Symbol.hasInstance](value) {
     if (this !== _DeeplineError) return nativeInstanceOf(this, value);
     return hasBrand(value, DEEPLINE_ERROR_BRAND);
   }
 };
 var ToolExecutionError = class _ToolExecutionError extends DeeplineError {
+  /** Public tool id passed to `tools.execute`. */
   toolId;
+  /** Provider responsible for the operation, or `null` when unattributed. */
   provider;
+  /** Provider operation name, or `null` when unavailable. */
   operation;
+  /** Boundary responsible for the failure. */
   origin;
+  /** Stable reason family for policy and diagnostics. */
   category;
+  /**
+   * Whether repeating the same semantic call is delivery-safe.
+   *
+   * This does not mean the error may be ignored. Waterfall fallthrough is
+   * represented by `ProviderTransientError`.
+   */
   retryable;
+  /** Provider or Deepline request id, or `null` when unavailable. */
   requestId;
+  /** Suggested same-call retry delay in milliseconds, or `null`. */
   retryAfterMs;
+  /** Network failure kind, or `null` for non-network failures. */
   networkKind;
+  /** Network boundary that failed, or `null` for non-network failures. */
   networkScope;
+  /**
+   * Construct a structured tool error.
+   *
+   * Deepline constructs this from the versioned `tool_error` payload.
+   * Application and Play code should catch it rather than create it.
+   */
   constructor(message, options) {
     super(
       message,
@@ -284,7 +319,9 @@ function isProviderTransientFailure(input2) {
   return input2.origin === "provider" && (input2.category === "rate_limit" || input2.category === "network" || input2.category === "upstream");
 }
 var ProviderTransientError = class _ProviderTransientError extends ToolExecutionError {
+  /** Provider attribution is guaranteed for this subtype. */
   origin = "provider";
+  /** Constructed by Deepline when a provider-owned transient failure arrives. */
   constructor(message, options) {
     super(message, {
       ...options,
@@ -438,6 +475,7 @@ function deserializeToolExecutionFailure(message, value, acceptedSchemaVersion)
 
 // src/errors.ts
 var AuthError = class extends DeeplineError {
+  /** Constructed by the SDK when Deepline rejects the caller's credentials. */
   constructor(message = "Authentication failed. Check your DEEPLINE_API_KEY.") {
     super(message, 401, "AUTH_ERROR");
     this.name = "AuthError";
@@ -446,6 +484,7 @@ var AuthError = class extends DeeplineError {
 var RateLimitError = class extends DeeplineError {
   /** Milliseconds to wait before retrying, from the `Retry-After` response header. Defaults to 5000. */
   retryAfterMs;
+  /** Constructed by the SDK after exhausting HTTP-level rate-limit retries. */
   constructor(retryAfterMs = 5e3, message) {
     super(
       message ?? `Rate limited. Retry after ${retryAfterMs}ms.`,
@@ -457,16 +496,27 @@ var RateLimitError = class extends DeeplineError {
   }
 };
 var ToolRateLimitError = class extends RateLimitError {
+  /** Public tool id passed to `tools.execute`. */
   toolId;
+  /** Provider responsible for the operation, or `null`. */
   provider;
+  /** Provider operation name, or `null`. */
   operation;
+  /** Stable machine-readable failure code when one exists. */
   code;
+  /** Boundary responsible for the failure. */
   origin;
+  /** Stable reason family for policy and diagnostics. */
   category;
+  /** Whether repeating the same semantic call is delivery-safe. */
   retryable;
+  /** Provider or Deepline request id, or `null`. */
   requestId;
+  /** Network failure kind, or `null` for non-network failures. */
   networkKind;
+  /** Network boundary that failed, or `null` for non-network failures. */
   networkScope;
+  /** Constructed by the SDK after a structured tool HTTP 429. */
   constructor(message, options) {
     super(options.retryAfterMs ?? 5e3, message);
     this.name = "ToolRateLimitError";
@@ -489,6 +539,7 @@ var ToolRateLimitError = class extends RateLimitError {
   }
 };
 var ConfigError = class extends DeeplineError {
+  /** Construct a local SDK configuration failure. */
   constructor(message) {
     super(message, void 0, "CONFIG_ERROR");
     this.name = "ConfigError";
@@ -986,7 +1037,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.302",
+  version: "0.1.304",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -9699,14 +9750,14 @@ function formatDbQueryError(sql, error) {
   if (referencesStorage && relationMissing) {
     return [
       "Customer DB query failed: the referenced storage table does not exist.",
-      "Play map tables are created only when the corresponding ctx.map(...).run(...) call executes. Pilot branches, early returns, and runs that fail before the map do not create that table.",
+      "Play dataset tables are created only when the corresponding ctx.dataset(...).run(...) call executes. Pilot branches, early returns, and runs that fail before the dataset do not create that table.",
       "Use `deepline runs get <run-id> --full --json` to inspect returned dataset handles, then export them with `deepline runs export <run-id> --dataset result.rows --out rows.csv`.",
       `Original error: ${errorMessage(error)}`
     ].join("\n");
   }
   if (referencesStorage && runIdColumnMissing) {
     return [
-      "Customer DB query failed: storage map tables use `_run_id`, not `run_id`.",
+      "Customer DB query failed: storage dataset tables use `_run_id`, not `run_id`.",
       "Prefer `deepline runs export <run-id> --dataset result.rows --out rows.csv` unless you are doing deep table debugging.",
       `Original error: ${errorMessage(error)}`
     ].join("\n");
@@ -11160,7 +11211,7 @@ function assertComposablePlayRoute(input2) {
   if (!input2.playRef || !playUsesMapBackedRuntime(input2.play)) return;
   const runCommand2 = input2.play?.runCommand?.trim() || `deepline plays run ${input2.playRef} --input '{...}' --watch`;
   throw new PlayBootstrapValidationError(
-    `Cannot use ${input2.stageLabel} play:${input2.playRef} in plays bootstrap composition: the selected play is map-backed/direct-run-only. Child plays that use ctx.map() own durable table state and must be run directly, exported, or validated as their own play instead of wrapped with ctx.runPlay. Run it directly first: ${runCommand2}`
+    `Cannot use ${input2.stageLabel} play:${input2.playRef} in plays bootstrap composition: the selected play is dataset-backed/direct-run-only. Child plays that use ctx.dataset() own durable table state and must be run directly, exported, or validated as their own play instead of wrapped with ctx.runPlay. Run it directly first: ${runCommand2}`
   );
 }
 function sourcePlayNeedsExportFirst(input2) {
@@ -11201,7 +11252,7 @@ function generatePlaySourceRowsBlock(input2) {
   })) {
     const sourcePlay = input2.sourcePlay;
     const runCommand2 = sourcePlay?.runCommand?.trim() || `deepline plays run ${input2.source.value} --input '{...}' --watch`;
-    return `// Source play ${input2.source.value} is map-backed/direct-run-only, so this generated play is stage 2.
+    return `// Source play ${input2.source.value} is dataset-backed/direct-run-only, so this generated play is stage 2.
   // Stage 1:
   //   ${runCommand2}
   // Stage 2:
@@ -11932,8 +11983,8 @@ var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists
 var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy and durable. Use `.peek(n)` for a small preview or `.materialize()` when you intentionally need rows in memory; do not use `.rows`, `.toArray()`, or array methods directly on the dataset handle.";
 var ROW_PROPERTY_HINT = "Deepline hint: this row type only contains fields produced by the CSV/schema and previous map steps. Check source column casing and the exact output field names from earlier steps before scaling.";
 var TOOLS_EXECUTE_SIGNATURE_HINT = "Deepline hint: ctx.tools.execute requires a request object: `ctx.tools.execute({ id, tool, input, description })`. The stable `id` is required for logs, metadata, and receipt attachment; provider-call reuse is based on play, tool, semantic input, auth scope, provider action version, and cache policy.";
-var RUN_PLAY_SIGNATURE_HINT = "Deepline hint: ctx.runPlay uses a stable key plus a composable child play reference. Direct-run-only or map-backed batch plays must be run directly, exported, then consumed by a separate play.";
-var MAP_BACKED_CHILD_HINT = "Deepline hint: map-backed child plays own durable table state and cannot be called from another play. Run that play directly, export its dataset, then pass the CSV to the next play.";
+var RUN_PLAY_SIGNATURE_HINT = "Deepline hint: ctx.runPlay uses a stable key plus a composable child play reference. Direct-run-only or dataset-backed batch plays must be run directly, exported, then consumed by a separate play.";
+var MAP_BACKED_CHILD_HINT = "Deepline hint: dataset-backed child plays own durable table state and cannot be called from another play. Run that play directly, export its dataset, then pass the CSV to the next play.";
 function sourceLineForError(sourceCode, error) {
   const match = error.match(/:(\d+):(\d+)\s/);
   const lineNumber = match?.[1] ? Number(match[1]) : NaN;
@@ -11963,7 +12014,7 @@ function looksLikeRunPlaySignature(error, sourceLine) {
   return /ctx\.runPlay/i.test(error) || /(?:Expected|Argument of type|No overload matches)/.test(error) && /\brunPlay\(/.test(sourceLine);
 }
 function looksLikeMapBackedChild(error) {
-  return /map-backed child play|direct-run-only|cannot call a map-backed|own durable table/i.test(
+  return /(?:map|dataset)-backed child play|direct-run-only|cannot call a (?:map|dataset)-backed|own durable table/i.test(
     error
   );
 }
@@ -13433,7 +13484,7 @@ function emitLiveDebugTableHints(input2) {
   }
   input2.state.emittedDebugKeys.add(tableKey);
   input2.progress.writeLine(
-    `Possible map table ${tableNamespace}: created only after this ctx.map(...).run(...) executes. Inspect returned datasets with ${buildRunInspectCommand(input2.runId)}`,
+    `Possible dataset table ${tableNamespace}: created only after this ctx.dataset(...).run(...) executes. Inspect returned datasets with ${buildRunInspectCommand(input2.runId)}`,
     process.stdout
   );
 }

package/dist/cli/index.mjs

@@ -207,33 +207,68 @@ function applyBrand(value, brand) {
   });
 }
 var DeeplineError = class _DeeplineError extends Error {
+  /** HTTP status when the failure crossed an HTTP boundary. */
+  statusCode;
+  /** Stable machine-readable error code when one exists. */
+  code;
+  /** Local diagnostic context; not a portable error contract. */
+  details;
+  /**
+   * Construct a Deepline error.
+   *
+   * SDK and runtime code construct these errors. Application and Play code
+   * normally catches the public subclasses instead.
+   *
+   * @param message Human-readable failure summary.
+   * @param statusCode HTTP status when one exists.
+   * @param code Stable machine-readable code when one exists.
+   * @param details Local diagnostic context; never a portable error contract.
+   */
   constructor(message, statusCode, code, details) {
     super(message);
+    this.name = "DeeplineError";
     this.statusCode = statusCode;
     this.code = code;
     this.details = details;
-    this.name = "DeeplineError";
     applyBrand(this, DEEPLINE_ERROR_BRAND);
   }
-  statusCode;
-  code;
-  details;
   static [Symbol.hasInstance](value) {
     if (this !== _DeeplineError) return nativeInstanceOf(this, value);
     return hasBrand(value, DEEPLINE_ERROR_BRAND);
   }
 };
 var ToolExecutionError = class _ToolExecutionError extends DeeplineError {
+  /** Public tool id passed to `tools.execute`. */
   toolId;
+  /** Provider responsible for the operation, or `null` when unattributed. */
   provider;
+  /** Provider operation name, or `null` when unavailable. */
   operation;
+  /** Boundary responsible for the failure. */
   origin;
+  /** Stable reason family for policy and diagnostics. */
   category;
+  /**
+   * Whether repeating the same semantic call is delivery-safe.
+   *
+   * This does not mean the error may be ignored. Waterfall fallthrough is
+   * represented by `ProviderTransientError`.
+   */
   retryable;
+  /** Provider or Deepline request id, or `null` when unavailable. */
   requestId;
+  /** Suggested same-call retry delay in milliseconds, or `null`. */
   retryAfterMs;
+  /** Network failure kind, or `null` for non-network failures. */
   networkKind;
+  /** Network boundary that failed, or `null` for non-network failures. */
   networkScope;
+  /**
+   * Construct a structured tool error.
+   *
+   * Deepline constructs this from the versioned `tool_error` payload.
+   * Application and Play code should catch it rather than create it.
+   */
   constructor(message, options) {
     super(
       message,
@@ -269,7 +304,9 @@ function isProviderTransientFailure(input2) {
   return input2.origin === "provider" && (input2.category === "rate_limit" || input2.category === "network" || input2.category === "upstream");
 }
 var ProviderTransientError = class _ProviderTransientError extends ToolExecutionError {
+  /** Provider attribution is guaranteed for this subtype. */
   origin = "provider";
+  /** Constructed by Deepline when a provider-owned transient failure arrives. */
   constructor(message, options) {
     super(message, {
       ...options,
@@ -423,6 +460,7 @@ function deserializeToolExecutionFailure(message, value, acceptedSchemaVersion)
 
 // src/errors.ts
 var AuthError = class extends DeeplineError {
+  /** Constructed by the SDK when Deepline rejects the caller's credentials. */
   constructor(message = "Authentication failed. Check your DEEPLINE_API_KEY.") {
     super(message, 401, "AUTH_ERROR");
     this.name = "AuthError";
@@ -431,6 +469,7 @@ var AuthError = class extends DeeplineError {
 var RateLimitError = class extends DeeplineError {
   /** Milliseconds to wait before retrying, from the `Retry-After` response header. Defaults to 5000. */
   retryAfterMs;
+  /** Constructed by the SDK after exhausting HTTP-level rate-limit retries. */
   constructor(retryAfterMs = 5e3, message) {
     super(
       message ?? `Rate limited. Retry after ${retryAfterMs}ms.`,
@@ -442,16 +481,27 @@ var RateLimitError = class extends DeeplineError {
   }
 };
 var ToolRateLimitError = class extends RateLimitError {
+  /** Public tool id passed to `tools.execute`. */
   toolId;
+  /** Provider responsible for the operation, or `null`. */
   provider;
+  /** Provider operation name, or `null`. */
   operation;
+  /** Stable machine-readable failure code when one exists. */
   code;
+  /** Boundary responsible for the failure. */
   origin;
+  /** Stable reason family for policy and diagnostics. */
   category;
+  /** Whether repeating the same semantic call is delivery-safe. */
   retryable;
+  /** Provider or Deepline request id, or `null`. */
   requestId;
+  /** Network failure kind, or `null` for non-network failures. */
   networkKind;
+  /** Network boundary that failed, or `null` for non-network failures. */
   networkScope;
+  /** Constructed by the SDK after a structured tool HTTP 429. */
   constructor(message, options) {
     super(options.retryAfterMs ?? 5e3, message);
     this.name = "ToolRateLimitError";
@@ -474,6 +524,7 @@ var ToolRateLimitError = class extends RateLimitError {
   }
 };
 var ConfigError = class extends DeeplineError {
+  /** Construct a local SDK configuration failure. */
   constructor(message) {
     super(message, void 0, "CONFIG_ERROR");
     this.name = "ConfigError";
@@ -971,7 +1022,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.302",
+  version: "0.1.304",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -9704,14 +9755,14 @@ function formatDbQueryError(sql, error) {
   if (referencesStorage && relationMissing) {
     return [
       "Customer DB query failed: the referenced storage table does not exist.",
-      "Play map tables are created only when the corresponding ctx.map(...).run(...) call executes. Pilot branches, early returns, and runs that fail before the map do not create that table.",
+      "Play dataset tables are created only when the corresponding ctx.dataset(...).run(...) call executes. Pilot branches, early returns, and runs that fail before the dataset do not create that table.",
       "Use `deepline runs get <run-id> --full --json` to inspect returned dataset handles, then export them with `deepline runs export <run-id> --dataset result.rows --out rows.csv`.",
       `Original error: ${errorMessage(error)}`
     ].join("\n");
   }
   if (referencesStorage && runIdColumnMissing) {
     return [
-      "Customer DB query failed: storage map tables use `_run_id`, not `run_id`.",
+      "Customer DB query failed: storage dataset tables use `_run_id`, not `run_id`.",
       "Prefer `deepline runs export <run-id> --dataset result.rows --out rows.csv` unless you are doing deep table debugging.",
       `Original error: ${errorMessage(error)}`
     ].join("\n");
@@ -11189,7 +11240,7 @@ function assertComposablePlayRoute(input2) {
   if (!input2.playRef || !playUsesMapBackedRuntime(input2.play)) return;
   const runCommand2 = input2.play?.runCommand?.trim() || `deepline plays run ${input2.playRef} --input '{...}' --watch`;
   throw new PlayBootstrapValidationError(
-    `Cannot use ${input2.stageLabel} play:${input2.playRef} in plays bootstrap composition: the selected play is map-backed/direct-run-only. Child plays that use ctx.map() own durable table state and must be run directly, exported, or validated as their own play instead of wrapped with ctx.runPlay. Run it directly first: ${runCommand2}`
+    `Cannot use ${input2.stageLabel} play:${input2.playRef} in plays bootstrap composition: the selected play is dataset-backed/direct-run-only. Child plays that use ctx.dataset() own durable table state and must be run directly, exported, or validated as their own play instead of wrapped with ctx.runPlay. Run it directly first: ${runCommand2}`
   );
 }
 function sourcePlayNeedsExportFirst(input2) {
@@ -11230,7 +11281,7 @@ function generatePlaySourceRowsBlock(input2) {
   })) {
     const sourcePlay = input2.sourcePlay;
     const runCommand2 = sourcePlay?.runCommand?.trim() || `deepline plays run ${input2.source.value} --input '{...}' --watch`;
-    return `// Source play ${input2.source.value} is map-backed/direct-run-only, so this generated play is stage 2.
+    return `// Source play ${input2.source.value} is dataset-backed/direct-run-only, so this generated play is stage 2.
   // Stage 1:
   //   ${runCommand2}
   // Stage 2:
@@ -11961,8 +12012,8 @@ var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists
 var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy and durable. Use `.peek(n)` for a small preview or `.materialize()` when you intentionally need rows in memory; do not use `.rows`, `.toArray()`, or array methods directly on the dataset handle.";
 var ROW_PROPERTY_HINT = "Deepline hint: this row type only contains fields produced by the CSV/schema and previous map steps. Check source column casing and the exact output field names from earlier steps before scaling.";
 var TOOLS_EXECUTE_SIGNATURE_HINT = "Deepline hint: ctx.tools.execute requires a request object: `ctx.tools.execute({ id, tool, input, description })`. The stable `id` is required for logs, metadata, and receipt attachment; provider-call reuse is based on play, tool, semantic input, auth scope, provider action version, and cache policy.";
-var RUN_PLAY_SIGNATURE_HINT = "Deepline hint: ctx.runPlay uses a stable key plus a composable child play reference. Direct-run-only or map-backed batch plays must be run directly, exported, then consumed by a separate play.";
-var MAP_BACKED_CHILD_HINT = "Deepline hint: map-backed child plays own durable table state and cannot be called from another play. Run that play directly, export its dataset, then pass the CSV to the next play.";
+var RUN_PLAY_SIGNATURE_HINT = "Deepline hint: ctx.runPlay uses a stable key plus a composable child play reference. Direct-run-only or dataset-backed batch plays must be run directly, exported, then consumed by a separate play.";
+var MAP_BACKED_CHILD_HINT = "Deepline hint: dataset-backed child plays own durable table state and cannot be called from another play. Run that play directly, export its dataset, then pass the CSV to the next play.";
 function sourceLineForError(sourceCode, error) {
   const match = error.match(/:(\d+):(\d+)\s/);
   const lineNumber = match?.[1] ? Number(match[1]) : NaN;
@@ -11992,7 +12043,7 @@ function looksLikeRunPlaySignature(error, sourceLine) {
   return /ctx\.runPlay/i.test(error) || /(?:Expected|Argument of type|No overload matches)/.test(error) && /\brunPlay\(/.test(sourceLine);
 }
 function looksLikeMapBackedChild(error) {
-  return /map-backed child play|direct-run-only|cannot call a map-backed|own durable table/i.test(
+  return /(?:map|dataset)-backed child play|direct-run-only|cannot call a (?:map|dataset)-backed|own durable table/i.test(
     error
   );
 }
@@ -13462,7 +13513,7 @@ function emitLiveDebugTableHints(input2) {
   }
   input2.state.emittedDebugKeys.add(tableKey);
   input2.progress.writeLine(
-    `Possible map table ${tableNamespace}: created only after this ctx.map(...).run(...) executes. Inspect returned datasets with ${buildRunInspectCommand(input2.runId)}`,
+    `Possible dataset table ${tableNamespace}: created only after this ctx.dataset(...).run(...) executes. Inspect returned datasets with ${buildRunInspectCommand(input2.runId)}`,
     process.stdout
   );
 }

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { a as PlayCompilerManifest, D as DeeplineError, c as ToolExecutionError, d as ToolExecutionErrorOptions, T as ToolExecutionErrorSchemaVersion } from './tool-execution-error-9mH4i-mJ.mjs';
-export { e as ProviderTransientError } from './tool-execution-error-9mH4i-mJ.mjs';
+import { a as PlayCompilerManifest, D as DeeplineError, c as ToolExecutionError, d as ToolExecutionErrorOptions, T as ToolExecutionErrorSchemaVersion } from './tool-execution-error-YDz7UMl-.mjs';
+export { e as ProviderTransientError, f as ProviderTransientErrorCategory, g as ToolExecutionErrorCategory, h as ToolExecutionErrorOrigin, i as ToolExecutionFailureV1, j as ToolExecutionNetworkKind, k as ToolExecutionNetworkScope } from './tool-execution-error-YDz7UMl-.mjs';
 
 type PlayRuntimeSelection = {
     environment: 'preview';
@@ -3168,28 +3168,6 @@ declare const SDK_VERSION: string;
 /** @deprecated Transitional wire id for pre-major-header SDKs only. */
 declare const SDK_API_CONTRACT: string;
 
-/**
- * Base error class for all Deepline SDK errors.
- *
- * Every error thrown by the SDK extends this class, so you can catch all
- * Deepline-specific errors with a single `catch (e) { if (e instanceof DeeplineError) }`.
- *
- * @example
- * ```typescript
- * import { DeeplineClient, DeeplineError, AuthError } from 'deepline';
- *
- * const client = new DeeplineClient();
- * try {
- *   await client.executeTool('dropleads_search_people', { query: 'cto' });
- * } catch (err) {
- *   if (err instanceof AuthError) {
- *     console.error('Bad API key — run: deepline auth register');
- *   } else if (err instanceof DeeplineError) {
- *     console.error(`API error ${err.statusCode}: ${err.message}`);
- *   }
- * }
- * ```
- */
 /**
  * Thrown when the API rejects the request due to an invalid or missing API key.
  *
@@ -3211,8 +3189,11 @@ declare const SDK_API_CONTRACT: string;
  *   }
  * }
  * ```
+ *
+ * @sdkReference errors 090
  */
 declare class AuthError extends DeeplineError {
+    /** Constructed by the SDK when Deepline rejects the caller's credentials. */
     constructor(message?: string);
 }
 /**
@@ -3237,10 +3218,13 @@ declare class AuthError extends DeeplineError {
  *   }
  * }
  * ```
+ *
+ * @sdkReference errors 100
  */
 declare class RateLimitError extends DeeplineError {
     /** Milliseconds to wait before retrying, from the `Retry-After` response header. Defaults to 5000. */
     retryAfterMs: number;
+    /** Constructed by the SDK after exhausting HTTP-level rate-limit retries. */
     constructor(retryAfterMs?: number, message?: string);
 }
 /**
@@ -3248,18 +3232,37 @@ declare class RateLimitError extends DeeplineError {
  * structured ToolExecutionError ontology. JavaScript has one prototype chain,
  * so this class extends RateLimitError and carries ToolExecutionError's stable
  * cross-bundle brand.
+ *
+ * This class appears in external SDK calls after HTTP 429 retries are
+ * exhausted. It also satisfies `instanceof ToolExecutionError` and, for a
+ * provider-owned rate limit, `instanceof ProviderTransientError`. Authored
+ * Plays should use `ProviderTransientError`; they do not need this
+ * compatibility class.
+ *
+ * @sdkReference errors 110
  */
 declare class ToolRateLimitError extends RateLimitError {
+    /** Public tool id passed to `tools.execute`. */
     readonly toolId: string;
+    /** Provider responsible for the operation, or `null`. */
     readonly provider: string | null;
+    /** Provider operation name, or `null`. */
     readonly operation: string | null;
+    /** Stable machine-readable failure code when one exists. */
     readonly code: string | undefined;
+    /** Boundary responsible for the failure. */
     readonly origin: ToolExecutionError['origin'];
+    /** Stable reason family for policy and diagnostics. */
     readonly category: ToolExecutionError['category'];
+    /** Whether repeating the same semantic call is delivery-safe. */
     readonly retryable: boolean;
+    /** Provider or Deepline request id, or `null`. */
     readonly requestId: string | null;
+    /** Network failure kind, or `null` for non-network failures. */
     readonly networkKind: ToolExecutionError['networkKind'];
+    /** Network boundary that failed, or `null` for non-network failures. */
     readonly networkScope: ToolExecutionError['networkScope'];
+    /** Constructed by the SDK after a structured tool HTTP 429. */
     constructor(message: string, options: ToolExecutionErrorOptions);
 }
 /**
@@ -3280,8 +3283,11 @@ declare class ToolRateLimitError extends RateLimitError {
  *   }
  * }
  * ```
+ *
+ * @sdkReference errors 120
  */
 declare class ConfigError extends DeeplineError {
+    /** Construct a local SDK configuration failure. */
     constructor(message: string);
 }
 
@@ -3672,6 +3678,8 @@ type ToolExecuteResultBase<TResult = unknown, TMeta = Record<string, unknown>> =
             count: number | null;
             keys: Record<string, string>;
         }>;
+        /** Original declarations preserve semantic accessor names across replay. */
+        listExtractorPaths?: readonly string[];
     };
 };
 type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as PlayCompilerManifest, D as DeeplineError, c as ToolExecutionError, d as ToolExecutionErrorOptions, T as ToolExecutionErrorSchemaVersion } from './tool-execution-error-9mH4i-mJ.js';
-export { e as ProviderTransientError } from './tool-execution-error-9mH4i-mJ.js';
+import { a as PlayCompilerManifest, D as DeeplineError, c as ToolExecutionError, d as ToolExecutionErrorOptions, T as ToolExecutionErrorSchemaVersion } from './tool-execution-error-YDz7UMl-.js';
+export { e as ProviderTransientError, f as ProviderTransientErrorCategory, g as ToolExecutionErrorCategory, h as ToolExecutionErrorOrigin, i as ToolExecutionFailureV1, j as ToolExecutionNetworkKind, k as ToolExecutionNetworkScope } from './tool-execution-error-YDz7UMl-.js';
 
 type PlayRuntimeSelection = {
     environment: 'preview';
@@ -3168,28 +3168,6 @@ declare const SDK_VERSION: string;
 /** @deprecated Transitional wire id for pre-major-header SDKs only. */
 declare const SDK_API_CONTRACT: string;
 
-/**
- * Base error class for all Deepline SDK errors.
- *
- * Every error thrown by the SDK extends this class, so you can catch all
- * Deepline-specific errors with a single `catch (e) { if (e instanceof DeeplineError) }`.
- *
- * @example
- * ```typescript
- * import { DeeplineClient, DeeplineError, AuthError } from 'deepline';
- *
- * const client = new DeeplineClient();
- * try {
- *   await client.executeTool('dropleads_search_people', { query: 'cto' });
- * } catch (err) {
- *   if (err instanceof AuthError) {
- *     console.error('Bad API key — run: deepline auth register');
- *   } else if (err instanceof DeeplineError) {
- *     console.error(`API error ${err.statusCode}: ${err.message}`);
- *   }
- * }
- * ```
- */
 /**
  * Thrown when the API rejects the request due to an invalid or missing API key.
  *
@@ -3211,8 +3189,11 @@ declare const SDK_API_CONTRACT: string;
  *   }
  * }
  * ```
+ *
+ * @sdkReference errors 090
  */
 declare class AuthError extends DeeplineError {
+    /** Constructed by the SDK when Deepline rejects the caller's credentials. */
     constructor(message?: string);
 }
 /**
@@ -3237,10 +3218,13 @@ declare class AuthError extends DeeplineError {
  *   }
  * }
  * ```
+ *
+ * @sdkReference errors 100
  */
 declare class RateLimitError extends DeeplineError {
     /** Milliseconds to wait before retrying, from the `Retry-After` response header. Defaults to 5000. */
     retryAfterMs: number;
+    /** Constructed by the SDK after exhausting HTTP-level rate-limit retries. */
     constructor(retryAfterMs?: number, message?: string);
 }
 /**
@@ -3248,18 +3232,37 @@ declare class RateLimitError extends DeeplineError {
  * structured ToolExecutionError ontology. JavaScript has one prototype chain,
  * so this class extends RateLimitError and carries ToolExecutionError's stable
  * cross-bundle brand.
+ *
+ * This class appears in external SDK calls after HTTP 429 retries are
+ * exhausted. It also satisfies `instanceof ToolExecutionError` and, for a
+ * provider-owned rate limit, `instanceof ProviderTransientError`. Authored
+ * Plays should use `ProviderTransientError`; they do not need this
+ * compatibility class.
+ *
+ * @sdkReference errors 110
  */
 declare class ToolRateLimitError extends RateLimitError {
+    /** Public tool id passed to `tools.execute`. */
     readonly toolId: string;
+    /** Provider responsible for the operation, or `null`. */
     readonly provider: string | null;
+    /** Provider operation name, or `null`. */
     readonly operation: string | null;
+    /** Stable machine-readable failure code when one exists. */
     readonly code: string | undefined;
+    /** Boundary responsible for the failure. */
     readonly origin: ToolExecutionError['origin'];
+    /** Stable reason family for policy and diagnostics. */
     readonly category: ToolExecutionError['category'];
+    /** Whether repeating the same semantic call is delivery-safe. */
     readonly retryable: boolean;
+    /** Provider or Deepline request id, or `null`. */
     readonly requestId: string | null;
+    /** Network failure kind, or `null` for non-network failures. */
     readonly networkKind: ToolExecutionError['networkKind'];
+    /** Network boundary that failed, or `null` for non-network failures. */
     readonly networkScope: ToolExecutionError['networkScope'];
+    /** Constructed by the SDK after a structured tool HTTP 429. */
     constructor(message: string, options: ToolExecutionErrorOptions);
 }
 /**
@@ -3280,8 +3283,11 @@ declare class ToolRateLimitError extends RateLimitError {
  *   }
  * }
  * ```
+ *
+ * @sdkReference errors 120
  */
 declare class ConfigError extends DeeplineError {
+    /** Construct a local SDK configuration failure. */
     constructor(message: string);
 }
 
@@ -3672,6 +3678,8 @@ type ToolExecuteResultBase<TResult = unknown, TMeta = Record<string, unknown>> =
             count: number | null;
             keys: Record<string, string>;
         }>;
+        /** Original declarations preserve semantic accessor names across replay. */
+        listExtractorPaths?: readonly string[];
     };
 };
 type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = {