deepline 0.1.302 → 0.1.303

package/dist/index.mjs

@@ -42,33 +42,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,
@@ -104,7 +139,9 @@ function isProviderTransientFailure(input) {
   return input.origin === "provider" && (input.category === "rate_limit" || input.category === "network" || input.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,
@@ -258,6 +295,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";
@@ -266,6 +304,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.`,
@@ -277,16 +316,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";
@@ -309,6 +359,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";
@@ -635,7 +686,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.303",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -6080,6 +6131,11 @@ function normalizeTableNamespace(value) {
   );
 }
 
+// ../shared_libs/play-runtime/tool-result-paths.ts
+function listNameFromDeclaredPath(path) {
+  return String(path || "").split(".").filter(Boolean).at(-1)?.replace(/[^A-Za-z0-9_$]/g, "") || null;
+}
+
 // ../shared_libs/play-runtime/tool-result.ts
 var TARGET_FALLBACK_KEYS = {
   email: [/^email$/i, /^address$/i, /email/i],
@@ -6420,38 +6476,33 @@ function coerceToEnum(value, descriptor) {
 function resolveListRows(result, listExtractorPaths) {
   const lists = {};
   for (const rawPath of listExtractorPaths ?? []) {
+    const listName = listNameFromDeclaredPath(rawPath);
+    if (!listName) continue;
     const path = normalizeResultPath(rawPath);
     if (!path) continue;
     const candidates = [...candidateResultPaths(rawPath)].filter(
       (candidate, index, all) => candidate && all.indexOf(candidate) === index
     );
-    let resolvedPath = null;
-    let rows = null;
+    let resolved = null;
     let emptyMatch = null;
     for (const candidate of candidates) {
-      rows = normalizeRows(getAtPath(result, candidate));
-      if (!rows) {
+      const candidateRows = normalizeRows(getAtPath(result, candidate));
+      if (!candidateRows) {
         continue;
       }
-      if (rows.length > 0) {
-        resolvedPath = candidate;
+      if (candidateRows.length > 0) {
+        resolved = { path: candidate, rows: candidateRows };
         break;
       }
-      emptyMatch ??= { path: candidate, rows };
-    }
-    if (!rows && emptyMatch) {
-      resolvedPath = emptyMatch.path;
-      rows = emptyMatch.rows;
+      emptyMatch ??= { path: candidate, rows: candidateRows };
     }
-    if (!rows) continue;
-    const storedPath = resolvedPath ?? path;
-    const name = storedPath.split(".").filter(Boolean).at(-1)?.replace(/\[\d+\]$/, "");
-    const listName = name || storedPath;
+    resolved ??= emptyMatch;
+    if (!resolved) continue;
     const existing = lists[listName];
-    if (existing?.rows.length && rows.length === 0) {
+    if (existing?.rows.length && resolved.rows.length === 0) {
       continue;
     }
-    lists[listName] = { path: storedPath, rows };
+    lists[listName] = resolved;
   }
   return lists;
 }
@@ -6685,6 +6736,7 @@ function createToolExecuteResult(input) {
     toolId: input.metadata.toolId,
     execution: input.execution,
     targets,
+    listExtractorPaths: [...input.metadata.listExtractorPaths ?? []],
     ...input.metadata.extractors ? { extractors: input.metadata.extractors } : {},
     lists
   };
@@ -6726,6 +6778,19 @@ function attachToolResultListDataset(result, input) {
     count: input.count,
     keys: input.keys ?? existing?.keys ?? {}
   };
+  const declaredPaths = result._metadata.listExtractorPaths ?? [];
+  const inputCandidates = new Set(candidateResultPaths(input.path));
+  const equivalentDeclaration = declaredPaths.find(
+    (path) => candidateResultPaths(path).some(
+      (candidate) => inputCandidates.has(candidate)
+    )
+  );
+  result._metadata.listExtractorPaths = equivalentDeclaration ? [...declaredPaths] : [
+    ...declaredPaths.filter(
+      (path) => listNameFromDeclaredPath(path) !== input.name
+    ),
+    input.path
+  ];
   const accessor = {
     path: input.path,
     count: input.count,

package/dist/plays/bundle-play-file.d.mts

@@ -1,5 +1,5 @@
-import { T as ToolExecutionErrorSchemaVersion, P as PlayArtifactKind$1, a as PlayCompilerManifest } from '../tool-execution-error-9mH4i-mJ.mjs';
-export { b as PLAY_ARTIFACT_KINDS } from '../tool-execution-error-9mH4i-mJ.mjs';
+import { T as ToolExecutionErrorSchemaVersion, P as PlayArtifactKind$1, a as PlayCompilerManifest } from '../tool-execution-error-YDz7UMl-.mjs';
+export { b as PLAY_ARTIFACT_KINDS } from '../tool-execution-error-YDz7UMl-.mjs';
 
 type PlayPackageImport = {
     name: string;

package/dist/plays/bundle-play-file.d.ts

@@ -1,5 +1,5 @@
-import { T as ToolExecutionErrorSchemaVersion, P as PlayArtifactKind$1, a as PlayCompilerManifest } from '../tool-execution-error-9mH4i-mJ.js';
-export { b as PLAY_ARTIFACT_KINDS } from '../tool-execution-error-9mH4i-mJ.js';
+import { T as ToolExecutionErrorSchemaVersion, P as PlayArtifactKind$1, a as PlayCompilerManifest } from '../tool-execution-error-YDz7UMl-.js';
+export { b as PLAY_ARTIFACT_KINDS } from '../tool-execution-error-YDz7UMl-.js';
 
 type PlayPackageImport = {
     name: string;

package/dist/{tool-execution-error-9mH4i-mJ.d.mts → tool-execution-error-YDz7UMl-.d.mts}

@@ -240,25 +240,89 @@ type PlayCompilerManifest = {
 declare const TOOL_EXECUTION_ERROR_SCHEMA_VERSION: 1;
 declare const SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS: readonly [0, 1];
 type ToolExecutionErrorSchemaVersion = (typeof SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS)[number];
+/**
+ * The boundary responsible for a failed tool call.
+ *
+ * Use `provider` to distinguish a provider answer from caller input and
+ * Deepline infrastructure. `unknown` fails closed and must not trigger a
+ * waterfall fallback.
+ *
+ * @sdkReference errors 020
+ */
 type ToolExecutionErrorOrigin = 'caller' | 'provider' | 'deepline' | 'unknown';
+/**
+ * The stable reason family for a failed tool call.
+ *
+ * Branch on this field only after narrowing to `ToolExecutionError`. Catch
+ * `ProviderTransientError` when the policy is simply “try the next read
+ * provider”; it is the safer and shorter waterfall contract.
+ *
+ * @sdkReference errors 030
+ */
 type ToolExecutionErrorCategory = 'validation' | 'authentication' | 'authorization' | 'rate_limit' | 'network' | 'upstream' | 'billing' | 'conflict' | 'internal' | 'unknown';
+/**
+ * The transport failure observed when `category` is `network`.
+ *
+ * This is `null` for failures that are not network failures.
+ *
+ * @sdkReference errors 040
+ */
 type ToolExecutionNetworkKind = 'timeout' | 'dns' | 'connect' | 'reset' | 'unavailable' | 'unknown';
+/**
+ * The request boundary on which a network failure occurred.
+ *
+ * `deepline_to_provider` is provider-side. Client and runtime scopes are
+ * Deepline transport failures and never qualify as provider fallthrough.
+ *
+ * @sdkReference errors 050
+ */
 type ToolExecutionNetworkScope = 'client_to_deepline' | 'runtime_to_deepline' | 'deepline_to_provider';
+/**
+ * Portable version-1 `tool_error` payload.
+ *
+ * This allowlisted shape crosses the API, runtime, and SDK boundaries.
+ * `message` remains on the Error object and is deliberately not a policy
+ * field.
+ *
+ * @sdkReference errors 064
+ */
 type ToolExecutionFailureV1 = {
+    /** Payload version. */
     schemaVersion: typeof TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
+    /** Public tool id passed to `tools.execute`. */
     toolId: string;
+    /** Provider responsible for the operation, or `null`. */
     provider: string | null;
+    /** Provider operation name, or `null`. */
     operation: string | null;
+    /** Stable machine-readable failure code, or `null`. */
     code: string | null;
+    /** Boundary responsible for the failure. */
     origin: ToolExecutionErrorOrigin;
+    /** Stable reason family. */
     category: ToolExecutionErrorCategory;
+    /** Whether repeating the same semantic call is delivery-safe. */
     retryable: boolean;
+    /** HTTP status when one exists, or `null`. */
     statusCode: number | null;
+    /** Provider or Deepline request id, or `null`. */
     requestId: string | null;
+    /** Suggested same-call retry delay in milliseconds, or `null`. */
     retryAfterMs: number | null;
+    /** Network failure kind, or `null`. */
     networkKind: ToolExecutionNetworkKind | null;
+    /** Network boundary that failed, or `null`. */
     networkScope: ToolExecutionNetworkScope | null;
 };
+/**
+ * Constructor input for a structured tool failure.
+ *
+ * Deepline creates these values while decoding the versioned wire payload.
+ * Customer code normally reads `ToolExecutionError` fields instead of
+ * constructing an error.
+ *
+ * @sdkReference errors 065
+ */
 type ToolExecutionErrorOptions = Omit<ToolExecutionFailureV1, 'schemaVersion'> & {
     /**
      * Local diagnostic context inherited from DeeplineError. This is not part of
@@ -266,18 +330,40 @@ type ToolExecutionErrorOptions = Omit<ToolExecutionFailureV1, 'schemaVersion'> &
      */
     details?: Record<string, unknown>;
 };
+/**
+ * Provider-owned failure categories that may fall through to another read
+ * provider.
+ *
+ * @sdkReference errors 060
+ */
 type ProviderTransientErrorCategory = 'rate_limit' | 'network' | 'upstream';
 /**
  * Base error class shared by the SDK and play runtime.
  *
  * The global brand preserves `instanceof DeeplineError` when a bundled play
  * and the runtime load separate physical copies of this module.
+ *
+ * @sdkReference errors 010
  */
 declare class DeeplineError extends Error {
-    statusCode?: number | undefined;
-    code?: string | undefined;
-    details?: Record<string, unknown> | undefined;
-    constructor(message: string, statusCode?: number | undefined, code?: string | undefined, details?: Record<string, unknown> | undefined);
+    /** HTTP status when the failure crossed an HTTP boundary. */
+    statusCode?: number;
+    /** Stable machine-readable error code when one exists. */
+    code?: string;
+    /** Local diagnostic context; not a portable error contract. */
+    details?: Record<string, unknown>;
+    /**
+     * 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: string, statusCode?: number, code?: string, details?: Record<string, unknown>);
     static [Symbol.hasInstance](value: unknown): boolean;
 }
 /**
@@ -286,18 +372,45 @@ declare class DeeplineError extends Error {
  * `retryable` means Deepline's delivery/idempotency contract says it is safe
  * to repeat the same semantic call. It does not describe durable receipt
  * repairability and does not make arbitrary side-effecting fallbacks safe.
+ *
+ * In a Play, catch `ProviderTransientError` to continue a read waterfall and
+ * let every other `ToolExecutionError` remain loud. In an SDK client, catch
+ * this base class when you need structured diagnostics for every tool failure.
+ *
+ * @sdkReference errors 070
  */
 declare class ToolExecutionError extends DeeplineError {
+    /** Public tool id passed to `tools.execute`. */
     readonly toolId: string;
+    /** Provider responsible for the operation, or `null` when unattributed. */
     readonly provider: string | null;
+    /** Provider operation name, or `null` when unavailable. */
     readonly operation: string | null;
+    /** Boundary responsible for the failure. */
     readonly origin: ToolExecutionErrorOrigin;
+    /** Stable reason family for policy and diagnostics. */
     readonly category: ToolExecutionErrorCategory;
+    /**
+     * Whether repeating the same semantic call is delivery-safe.
+     *
+     * This does not mean the error may be ignored. Waterfall fallthrough is
+     * represented by `ProviderTransientError`.
+     */
     readonly retryable: boolean;
+    /** Provider or Deepline request id, or `null` when unavailable. */
     readonly requestId: string | null;
+    /** Suggested same-call retry delay in milliseconds, or `null`. */
     readonly retryAfterMs: number | null;
+    /** Network failure kind, or `null` for non-network failures. */
     readonly networkKind: ToolExecutionNetworkKind | null;
+    /** Network boundary that failed, or `null` for non-network failures. */
     readonly networkScope: ToolExecutionNetworkScope | null;
+    /**
+     * 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: string, options: ToolExecutionErrorOptions);
     static [Symbol.hasInstance](value: unknown): boolean;
 }
@@ -305,14 +418,23 @@ declare class ToolExecutionError extends DeeplineError {
  * A provider-owned transient failure that is safe to handle as an empty
  * waterfall leg. Validation, auth, billing, Deepline, and unknown failures
  * never satisfy this type.
+ *
+ * `retryable` remains independent: it says whether the same semantic call may
+ * be repeated safely. Falling through to a different read provider depends on
+ * this class, not on `retryable`.
+ *
+ * @sdkReference errors 080
  */
 declare class ProviderTransientError extends ToolExecutionError {
+    /** Provider attribution is guaranteed for this subtype. */
     readonly origin: "provider";
+    /** Provider failure category that made this error eligible for fallthrough. */
     readonly category: ProviderTransientErrorCategory;
+    /** Constructed by Deepline when a provider-owned transient failure arrives. */
     constructor(message: string, options: Omit<ToolExecutionErrorOptions, 'origin' | 'category'> & {
         category: ProviderTransientErrorCategory;
     });
     static [Symbol.hasInstance](value: unknown): boolean;
 }
 
-export { DeeplineError as D, type PlayArtifactKind as P, type ToolExecutionErrorSchemaVersion as T, type PlayCompilerManifest as a, PLAY_ARTIFACT_KINDS as b, ToolExecutionError as c, type ToolExecutionErrorOptions as d, ProviderTransientError as e };
+export { DeeplineError as D, type PlayArtifactKind as P, type ToolExecutionErrorSchemaVersion as T, type PlayCompilerManifest as a, PLAY_ARTIFACT_KINDS as b, ToolExecutionError as c, type ToolExecutionErrorOptions as d, ProviderTransientError as e, type ProviderTransientErrorCategory as f, type ToolExecutionErrorCategory as g, type ToolExecutionErrorOrigin as h, type ToolExecutionFailureV1 as i, type ToolExecutionNetworkKind as j, type ToolExecutionNetworkScope as k };

package/dist/{tool-execution-error-9mH4i-mJ.d.ts → tool-execution-error-YDz7UMl-.d.ts}

@@ -240,25 +240,89 @@ type PlayCompilerManifest = {
 declare const TOOL_EXECUTION_ERROR_SCHEMA_VERSION: 1;
 declare const SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS: readonly [0, 1];
 type ToolExecutionErrorSchemaVersion = (typeof SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS)[number];
+/**
+ * The boundary responsible for a failed tool call.
+ *
+ * Use `provider` to distinguish a provider answer from caller input and
+ * Deepline infrastructure. `unknown` fails closed and must not trigger a
+ * waterfall fallback.
+ *
+ * @sdkReference errors 020
+ */
 type ToolExecutionErrorOrigin = 'caller' | 'provider' | 'deepline' | 'unknown';
+/**
+ * The stable reason family for a failed tool call.
+ *
+ * Branch on this field only after narrowing to `ToolExecutionError`. Catch
+ * `ProviderTransientError` when the policy is simply “try the next read
+ * provider”; it is the safer and shorter waterfall contract.
+ *
+ * @sdkReference errors 030
+ */
 type ToolExecutionErrorCategory = 'validation' | 'authentication' | 'authorization' | 'rate_limit' | 'network' | 'upstream' | 'billing' | 'conflict' | 'internal' | 'unknown';
+/**
+ * The transport failure observed when `category` is `network`.
+ *
+ * This is `null` for failures that are not network failures.
+ *
+ * @sdkReference errors 040
+ */
 type ToolExecutionNetworkKind = 'timeout' | 'dns' | 'connect' | 'reset' | 'unavailable' | 'unknown';
+/**
+ * The request boundary on which a network failure occurred.
+ *
+ * `deepline_to_provider` is provider-side. Client and runtime scopes are
+ * Deepline transport failures and never qualify as provider fallthrough.
+ *
+ * @sdkReference errors 050
+ */
 type ToolExecutionNetworkScope = 'client_to_deepline' | 'runtime_to_deepline' | 'deepline_to_provider';
+/**
+ * Portable version-1 `tool_error` payload.
+ *
+ * This allowlisted shape crosses the API, runtime, and SDK boundaries.
+ * `message` remains on the Error object and is deliberately not a policy
+ * field.
+ *
+ * @sdkReference errors 064
+ */
 type ToolExecutionFailureV1 = {
+    /** Payload version. */
     schemaVersion: typeof TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
+    /** Public tool id passed to `tools.execute`. */
     toolId: string;
+    /** Provider responsible for the operation, or `null`. */
     provider: string | null;
+    /** Provider operation name, or `null`. */
     operation: string | null;
+    /** Stable machine-readable failure code, or `null`. */
     code: string | null;
+    /** Boundary responsible for the failure. */
     origin: ToolExecutionErrorOrigin;
+    /** Stable reason family. */
     category: ToolExecutionErrorCategory;
+    /** Whether repeating the same semantic call is delivery-safe. */
     retryable: boolean;
+    /** HTTP status when one exists, or `null`. */
     statusCode: number | null;
+    /** Provider or Deepline request id, or `null`. */
     requestId: string | null;
+    /** Suggested same-call retry delay in milliseconds, or `null`. */
     retryAfterMs: number | null;
+    /** Network failure kind, or `null`. */
     networkKind: ToolExecutionNetworkKind | null;
+    /** Network boundary that failed, or `null`. */
     networkScope: ToolExecutionNetworkScope | null;
 };
+/**
+ * Constructor input for a structured tool failure.
+ *
+ * Deepline creates these values while decoding the versioned wire payload.
+ * Customer code normally reads `ToolExecutionError` fields instead of
+ * constructing an error.
+ *
+ * @sdkReference errors 065
+ */
 type ToolExecutionErrorOptions = Omit<ToolExecutionFailureV1, 'schemaVersion'> & {
     /**
      * Local diagnostic context inherited from DeeplineError. This is not part of
@@ -266,18 +330,40 @@ type ToolExecutionErrorOptions = Omit<ToolExecutionFailureV1, 'schemaVersion'> &
      */
     details?: Record<string, unknown>;
 };
+/**
+ * Provider-owned failure categories that may fall through to another read
+ * provider.
+ *
+ * @sdkReference errors 060
+ */
 type ProviderTransientErrorCategory = 'rate_limit' | 'network' | 'upstream';
 /**
  * Base error class shared by the SDK and play runtime.
  *
  * The global brand preserves `instanceof DeeplineError` when a bundled play
  * and the runtime load separate physical copies of this module.
+ *
+ * @sdkReference errors 010
  */
 declare class DeeplineError extends Error {
-    statusCode?: number | undefined;
-    code?: string | undefined;
-    details?: Record<string, unknown> | undefined;
-    constructor(message: string, statusCode?: number | undefined, code?: string | undefined, details?: Record<string, unknown> | undefined);
+    /** HTTP status when the failure crossed an HTTP boundary. */
+    statusCode?: number;
+    /** Stable machine-readable error code when one exists. */
+    code?: string;
+    /** Local diagnostic context; not a portable error contract. */
+    details?: Record<string, unknown>;
+    /**
+     * 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: string, statusCode?: number, code?: string, details?: Record<string, unknown>);
     static [Symbol.hasInstance](value: unknown): boolean;
 }
 /**
@@ -286,18 +372,45 @@ declare class DeeplineError extends Error {
  * `retryable` means Deepline's delivery/idempotency contract says it is safe
  * to repeat the same semantic call. It does not describe durable receipt
  * repairability and does not make arbitrary side-effecting fallbacks safe.
+ *
+ * In a Play, catch `ProviderTransientError` to continue a read waterfall and
+ * let every other `ToolExecutionError` remain loud. In an SDK client, catch
+ * this base class when you need structured diagnostics for every tool failure.
+ *
+ * @sdkReference errors 070
  */
 declare class ToolExecutionError extends DeeplineError {
+    /** Public tool id passed to `tools.execute`. */
     readonly toolId: string;
+    /** Provider responsible for the operation, or `null` when unattributed. */
     readonly provider: string | null;
+    /** Provider operation name, or `null` when unavailable. */
     readonly operation: string | null;
+    /** Boundary responsible for the failure. */
     readonly origin: ToolExecutionErrorOrigin;
+    /** Stable reason family for policy and diagnostics. */
     readonly category: ToolExecutionErrorCategory;
+    /**
+     * Whether repeating the same semantic call is delivery-safe.
+     *
+     * This does not mean the error may be ignored. Waterfall fallthrough is
+     * represented by `ProviderTransientError`.
+     */
     readonly retryable: boolean;
+    /** Provider or Deepline request id, or `null` when unavailable. */
     readonly requestId: string | null;
+    /** Suggested same-call retry delay in milliseconds, or `null`. */
     readonly retryAfterMs: number | null;
+    /** Network failure kind, or `null` for non-network failures. */
     readonly networkKind: ToolExecutionNetworkKind | null;
+    /** Network boundary that failed, or `null` for non-network failures. */
     readonly networkScope: ToolExecutionNetworkScope | null;
+    /**
+     * 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: string, options: ToolExecutionErrorOptions);
     static [Symbol.hasInstance](value: unknown): boolean;
 }
@@ -305,14 +418,23 @@ declare class ToolExecutionError extends DeeplineError {
  * A provider-owned transient failure that is safe to handle as an empty
  * waterfall leg. Validation, auth, billing, Deepline, and unknown failures
  * never satisfy this type.
+ *
+ * `retryable` remains independent: it says whether the same semantic call may
+ * be repeated safely. Falling through to a different read provider depends on
+ * this class, not on `retryable`.
+ *
+ * @sdkReference errors 080
  */
 declare class ProviderTransientError extends ToolExecutionError {
+    /** Provider attribution is guaranteed for this subtype. */
     readonly origin: "provider";
+    /** Provider failure category that made this error eligible for fallthrough. */
     readonly category: ProviderTransientErrorCategory;
+    /** Constructed by Deepline when a provider-owned transient failure arrives. */
     constructor(message: string, options: Omit<ToolExecutionErrorOptions, 'origin' | 'category'> & {
         category: ProviderTransientErrorCategory;
     });
     static [Symbol.hasInstance](value: unknown): boolean;
 }
 
-export { DeeplineError as D, type PlayArtifactKind as P, type ToolExecutionErrorSchemaVersion as T, type PlayCompilerManifest as a, PLAY_ARTIFACT_KINDS as b, ToolExecutionError as c, type ToolExecutionErrorOptions as d, ProviderTransientError as e };
+export { DeeplineError as D, type PlayArtifactKind as P, type ToolExecutionErrorSchemaVersion as T, type PlayCompilerManifest as a, PLAY_ARTIFACT_KINDS as b, ToolExecutionError as c, type ToolExecutionErrorOptions as d, ProviderTransientError as e, type ProviderTransientErrorCategory as f, type ToolExecutionErrorCategory as g, type ToolExecutionErrorOrigin as h, type ToolExecutionFailureV1 as i, type ToolExecutionNetworkKind as j, type ToolExecutionNetworkScope as k };

package/package.json

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