@pipelex/sdk 0.32.0 → 0.33.0

package/dist/error-verdicts.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The verdict an `ApiResponseError` falls back to when the server sent no usable member.
+ *
+ * A problem document may carry `retryable` and `error_domain`, and when it does the error takes
+ * them (see `ApiResponseError`). When it does not — the platform does not classify its own
+ * refusals yet, a gateway answers an HTML page, a bare runner answers Starlette's
+ * `{"detail": "Not Found"}` — each missing member is read off this table instead, so a consumer
+ * never has to choose its own default. The one exception is a `retryable` missing beside a sent
+ * `input` or `config` domain, which is not retryable whatever the status. The table reads only the
+ * HTTP status, the platform's native `code`, and whether the body names what it refused.
+ *
+ * It is also the platform's reference: the verdicts the platform will send on its own refusals
+ * are decided against this table, so a refusal keeps its verdict when the platform starts
+ * sending one. The Python twin, `pipelex-sdk`, must apply the same table. The case file
+ * `tests/fixtures/error-verdicts.json` holds every row, and this package's suite drives the table
+ * through it; the Python suite is to drive its own code through an identical copy, once that copy
+ * is added.
+ */
+import type { ErrorVerdict } from "./errors.js";
+/**
+ * The verdict of a refused request whose problem document carried no usable member.
+ *
+ * - `status` is the HTTP status of the answer.
+ * - `code` is the platform's native code, when the body carried one.
+ * - `named` says whether the body names what it refused: a platform `code` or a runner
+ *   `error_type`. It decides a `404`: a named one is a resource the caller asked for that does not
+ *   exist (`input`), a bare one is a route the deployment does not serve (`config`).
+ *
+ * Every `4xx` the table does not list is the caller's request refused (`input`, not retryable),
+ * every `5xx` it does not list is a fault in the service that may pass (`runtime`, retryable),
+ * and any other status is one no refusal carries, such as the `2xx` of an answer the client could
+ * not read, so nothing says a retry helps (`runtime`, not retryable).
+ */
+export declare function fallbackVerdict(status: number, code: string | undefined, named: boolean): ErrorVerdict;

package/dist/error-verdicts.js

@@ -0,0 +1,69 @@
+/**
+ * The verdict an `ApiResponseError` falls back to when the server sent no usable member.
+ *
+ * A problem document may carry `retryable` and `error_domain`, and when it does the error takes
+ * them (see `ApiResponseError`). When it does not — the platform does not classify its own
+ * refusals yet, a gateway answers an HTML page, a bare runner answers Starlette's
+ * `{"detail": "Not Found"}` — each missing member is read off this table instead, so a consumer
+ * never has to choose its own default. The one exception is a `retryable` missing beside a sent
+ * `input` or `config` domain, which is not retryable whatever the status. The table reads only the
+ * HTTP status, the platform's native `code`, and whether the body names what it refused.
+ *
+ * It is also the platform's reference: the verdicts the platform will send on its own refusals
+ * are decided against this table, so a refusal keeps its verdict when the platform starts
+ * sending one. The Python twin, `pipelex-sdk`, must apply the same table. The case file
+ * `tests/fixtures/error-verdicts.json` holds every row, and this package's suite drives the table
+ * through it; the Python suite is to drive its own code through an identical copy, once that copy
+ * is added.
+ */
+const INPUT = Object.freeze({ errorDomain: "input", retryable: false });
+const CONFIG = Object.freeze({ errorDomain: "config", retryable: false });
+const TRANSIENT = Object.freeze({ errorDomain: "runtime", retryable: true });
+const FAULT = Object.freeze({ errorDomain: "runtime", retryable: false });
+/** The platform code a `409` carries when the organization holds as many API keys as it may. */
+const API_KEY_LIMIT_CODE = "pipelex_api_key_limit_reached";
+/**
+ * The verdict of a refused request whose problem document carried no usable member.
+ *
+ * - `status` is the HTTP status of the answer.
+ * - `code` is the platform's native code, when the body carried one.
+ * - `named` says whether the body names what it refused: a platform `code` or a runner
+ *   `error_type`. It decides a `404`: a named one is a resource the caller asked for that does not
+ *   exist (`input`), a bare one is a route the deployment does not serve (`config`).
+ *
+ * Every `4xx` the table does not list is the caller's request refused (`input`, not retryable),
+ * every `5xx` it does not list is a fault in the service that may pass (`runtime`, retryable),
+ * and any other status is one no refusal carries, such as the `2xx` of an answer the client could
+ * not read, so nothing says a retry helps (`runtime`, not retryable).
+ */
+export function fallbackVerdict(status, code, named) {
+    switch (status) {
+        case 401:
+        case 402:
+        case 403:
+            // The credential, the plan or the access must change.
+            return CONFIG;
+        case 404:
+            return named ? INPUT : CONFIG;
+        case 405:
+            // The deployment does not serve this method on the route.
+            return CONFIG;
+        case 408:
+        case 429:
+            // Refused for its timing, not its content.
+            return TRANSIENT;
+        case 409:
+            // A conflict with the stored state is the caller's, except the key limit, which someone
+            // lifts by removing a key.
+            return code === API_KEY_LIMIT_CODE ? CONFIG : INPUT;
+        case 501:
+            // The deployment does not implement it, and asking again will not change that.
+            return CONFIG;
+    }
+    if (status >= 400 && status < 500)
+        return INPUT;
+    if (status >= 500 && status < 600)
+        return TRANSIENT;
+    return FAULT;
+}
+//# sourceMappingURL=error-verdicts.js.map

package/dist/error-verdicts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-verdicts.js","sourceRoot":"","sources":["../src/error-verdicts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,MAAM,KAAK,GAAiB,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;AACtF,MAAM,MAAM,GAAiB,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;AACxF,MAAM,SAAS,GAAiB,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAC3F,MAAM,KAAK,GAAiB,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;AAExF,gGAAgG;AAChG,MAAM,kBAAkB,GAAG,+BAA+B,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAc,EACd,IAAwB,EACxB,KAAc;IAEd,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,GAAG,CAAC;QACT,KAAK,GAAG,CAAC;QACT,KAAK,GAAG;YACN,sDAAsD;YACtD,OAAO,MAAM,CAAC;QAChB,KAAK,GAAG;YACN,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;QAChC,KAAK,GAAG;YACN,0DAA0D;YAC1D,OAAO,MAAM,CAAC;QAChB,KAAK,GAAG,CAAC;QACT,KAAK,GAAG;YACN,2CAA2C;YAC3C,OAAO,SAAS,CAAC;QACnB,KAAK,GAAG;YACN,wFAAwF;YACxF,2BAA2B;YAC3B,OAAO,IAAI,KAAK,kBAAkB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;QACtD,KAAK,GAAG;YACN,+EAA+E;YAC/E,OAAO,MAAM,CAAC;IAClB,CAAC;IACD,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;QAAE,OAAO,SAAS,CAAC;IACpD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/errors.d.ts

@@ -1,7 +1,9 @@
 /**
- * Pipelex SDK errors — transport and run-lifecycle errors raised by
- * `PipelexApiClient`. All derive from the protocol-base `PipelineRequestError`
- * (re-exported from `mthds/protocol`), except `ClientAuthenticationError`.
+ * Pipelex SDK errors — the argument, transport, run-lifecycle, input-preparation and artifact
+ * errors `PipelexApiClient` raises. Every one derives from `PipelexRequestError`, itself a
+ * `PipelineRequestError` (the protocol base, re-exported from `mthds/protocol`), and so carries
+ * a verdict: `retryable` and `errorDomain`, always decided. The one exported error outside the
+ * family, `CodegenLockError`, declares the same two members itself.
  */
 import { PipelineRequestError } from "mthds/protocol";
 import type { ValidationErrorItem } from "./models.js";
@@ -9,18 +11,97 @@ import type { ArtifactScope, DownloadArtifactsResult } from "./artifacts.js";
 import type { FieldError, MigrationErrorBlock, ProblemDetails, ProviderErrorMetadata, RunErrorReport, UserAction } from "./error-models.js";
 import type { RunStatus } from "./runs.js";
 export { PipelineRequestError };
-export declare class ClientAuthenticationError extends Error {
-    constructor(message: string);
+/**
+ * Who can fix a failure:
+ *
+ * - `input` — the caller, by changing the request: the inputs, the method, a reference, an
+ *   argument.
+ * - `config` — someone changing the environment: the base URL, the credential, the plan, the
+ *   deployment.
+ * - `runtime` — nobody beforehand: a fault during execution or in the service.
+ *
+ * The set is closed: the hosted envelope spec names these three, so a fourth would be a contract
+ * change and would reach the SDK as one.
+ */
+export type ErrorDomain = "input" | "config" | "runtime";
+/** Whether a value is one of the three error domains. */
+export declare function isErrorDomain(value: unknown): value is ErrorDomain;
+/**
+ * The verdict an error carries: whether asking again can plausibly succeed (`retryable`), and who
+ * can fix the failure (`errorDomain`). Both are always decided.
+ *
+ * "Retryable" says a retry can succeed, never that it is safe: it says nothing about whether the
+ * first attempt had an effect. A start answered with a `500` may already have created a run, so a
+ * caller that must not start a run twice decides that for itself.
+ */
+export interface ErrorVerdict {
+    readonly retryable: boolean;
+    readonly errorDomain: ErrorDomain;
+}
+/**
+ * The base of every error this SDK raises over a request, carrying the verdict as two readonly
+ * own properties: `retryable` and `errorDomain`. Each subclass passes its verdict to this
+ * constructor, so a class that forgets one does not compile, and every class says its verdict
+ * where it is defined.
+ *
+ * It refines the standard's `PipelineRequestError`, so `instanceof PipelineRequestError` still
+ * matches every SDK error. To read a verdict from anything a `catch` holds, use
+ * `errorVerdictOf`, which also reads it off an error raised by another copy of this SDK.
+ */
+export declare abstract class PipelexRequestError extends PipelineRequestError implements ErrorVerdict {
+    /** Whether asking again can plausibly succeed. Always decided. */
+    readonly retryable: boolean;
+    /** Who can fix the failure: `input`, `config` or `runtime`. Always decided. */
+    readonly errorDomain: ErrorDomain;
+    constructor(message: string, verdict: ErrorVerdict, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The verdict of anything a `catch` holds: the pair from an `Error` carrying a boolean
+ * `retryable` and a known `errorDomain`, and `undefined` otherwise.
+ *
+ * The check is structural rather than `instanceof`, so it reads every error of this SDK, of
+ * another copy of it installed beside this one, of a consumer's own subclass, and an `mthds`
+ * `ApiResponseError` whose runner sent both members. `undefined` means the error carries no
+ * verdict: the `RangeError` or `TypeError` the SDK raises for an argument of the wrong type or
+ * range before any request is sent (a bug in the calling code), the caller's own abort, which the
+ * client rethrows untouched, or anything else a `try` block threw. An argument the client refuses
+ * for what it asks is a `RequestArgumentError`, which carries one.
+ */
+export declare function errorVerdictOf(err: unknown): ErrorVerdict | undefined;
+/**
+ * The SDK refused a call's arguments before sending any request: no run source given to
+ * `execute()` or `start()`, run sources or method selectors that exclude each other, a selector
+ * rule of `validate()`, an empty `validateFiles()`, a reserved key in `extra`, or a base URL that
+ * is not host-only. Nothing reached the API, so the message says what to change.
+ *
+ * Its verdict is `input`, not retryable — the caller must change the arguments — unless
+ * `options.verdict` declares another: the client declares `config` for a base URL that is not
+ * host-only, since it typically comes from `PIPELEX_BASE_URL`. A refusal the standard's own
+ * check raises (`assertExclusiveRunSources`) is rethrown as this class with the same message, the
+ * standard's error as `cause`.
+ */
+export declare class RequestArgumentError extends PipelexRequestError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        verdict?: ErrorVerdict;
+    });
 }
 /**
  * Base class for every failure raised by input preparation (`uploadFile` /
  * `prepareInputs`). Catch this to handle any preparation failure; catch a
  * subclass to branch on the semantic category. All preparation failures are
  * raised BEFORE any run is created — a run never triggers a hidden upload.
+ *
+ * Its verdict is `input`, not retryable — the asset, the inputs or the method selector must
+ * change — unless `options.verdict` declares another: the SDK's own subclasses do, and so can a
+ * consumer's, such as a form reporting a missing input in its own words.
  */
-export declare class InputPreparationError extends PipelineRequestError {
+export declare class InputPreparationError extends PipelexRequestError {
     constructor(message: string, options?: {
         cause?: unknown;
+        verdict?: ErrorVerdict;
     });
 }
 /**
@@ -59,12 +140,17 @@ export declare class InvalidLocalSourceError extends InputPreparationError {
  * `grant_expired` — the grant's validity window has passed; `signature_mismatch` —
  * the file's size, content type or metadata differ from what the grant signed;
  * `unsigned_header` — the request carried a storage header the grant did not sign;
- * `store_refused` — any other refusal from storage.
+ * `store_refused` — any other refusal from storage. Storage's `408` and `429` are no
+ * refusal of the asset: they refuse the request for its timing, and are an
+ * `UploadTransportError`.
  */
 export type RejectedAssetCode = "too_large" | "grant_used" | "grant_expired" | "signature_mismatch" | "unsigned_header" | "store_refused";
 /**
  * The server or storage refused the asset — most commonly a `413` past the
- * service-defined size cap, or storage refusing an upload with a grant. The SDK
+ * service-defined size cap, or storage refusing an upload with a grant. A storage
+ * `4xx` that says nothing about the file is not among them: a `408` or a `429`, which
+ * time out or throttle the request, a `400 RequestTimeout` and a `409
+ * ConditionalRequestConflict` are an `UploadTransportError`. The SDK
  * does not impose a client-side cap; it surfaces the refusal. `filename` and
  * `status` locate it, and `code` says why: the SDK sets it on every one it raises,
  * so it is undefined only on one a caller constructs without it.
@@ -81,14 +167,18 @@ export declare class RejectedAssetError extends InputPreparationError {
 /**
  * The configured deployment does not support upload (no `/v1/upload` route, seen
  * as a `404`). Upload is a hosted Pipelex-product capability even though the SDK
- * can be pointed at other base URLs.
+ * can be pointed at other base URLs. Its verdict is `config`, not retryable: the base URL
+ * must point at a deployment that serves upload.
  */
 export declare class UnsupportedUploadCapabilityError extends InputPreparationError {
     constructor(message: string, options?: {
         cause?: unknown;
     });
 }
-/** Upload was not authorized — a `401`/`403` from the upload route. */
+/**
+ * Upload was not authorized — a `401`/`403` from the upload route. Its verdict is `config`, not
+ * retryable: the credential must change.
+ */
 export declare class UploadAuthenticationError extends InputPreparationError {
     readonly status: number;
     constructor(message: string, status: number, options?: {
@@ -105,7 +195,8 @@ export declare class UploadAuthenticationError extends InputPreparationError {
  *   `uploadFile`. Whether the file was stored is unknown.
  * - `unreachable` — no response reached the SDK. In a browser, a refused cross-origin
  *   request looks like this.
- * - `server_error` — a `5xx`. Whether the file was stored is unknown.
+ * - `server_error` — a `5xx`. Whether the file was stored is unknown, except after a `501`:
+ *   storage does not implement the request it was sent, and stored nothing.
  * - `storage_timeout` — storage's `400 RequestTimeout`: it stopped waiting for the
  *   file's bytes and stored nothing.
  * - `conflict` — storage's `409 ConditionalRequestConflict`: another `PUT` with the
@@ -113,18 +204,36 @@ export declare class UploadAuthenticationError extends InputPreparationError {
  * - `redirected` — storage redirected the `PUT`, and the redirect was refused.
  * - `invalid_grant_url` — the grant's `url` is not an absolute `http(s)` URL free of
  *   user info, so nothing was sent.
- * - `unexpected` — a status or a failure the SDK has no specific mapping for.
+ * - `unexpected` — a status or a failure the SDK has no specific mapping for. From
+ *   `uploadWithGrant`, storage's `408` or `429`: it timed out or throttled the request,
+ *   which a later attempt can pass.
  */
 export type UploadTransportCode = "timeout" | "unreachable" | "server_error" | "storage_timeout" | "conflict" | "redirected" | "invalid_grant_url" | "unexpected";
 /**
  * A network or server fault reaching the upload route or storage — an unreachable
- * host, a timeout, a `5xx`, a refused redirect, storage timing out on the body, or
- * any other unexpected `upload()` failure. `code` says which: the SDK sets it on
+ * host, a timeout, a `5xx`, a refused redirect, storage timing out on the body,
+ * storage timing out or throttling the request (a `408` or a `429`), or any other
+ * unexpected `upload()` failure. `code` says which: the SDK sets it on
  * every one it raises, so it is undefined only on one a caller constructs without
  * it. `status` is the HTTP status when a response produced it, and undefined when
  * none did. From `uploadFile` the wrapped `ApiResponseError` is also reachable via
  * `cause`; `uploadWithGrant` wraps no response, because storage's error body can
  * echo the grant's credential.
+ *
+ * Its verdict is the wrapped error's when `cause` carries one: `uploadFile` wraps the
+ * `ApiResponseError` or `ApiUnreachableError` the client's `upload()` threw, and `code` is too
+ * coarse to judge it by (a `402` plan limit is `unexpected`, like a malformed answer). Otherwise
+ * — always the case from `uploadWithGrant`, which wraps no response — `code` decides: `timeout`,
+ * `storage_timeout` and `conflict` are `runtime` and retryable, `conflict` because storage
+ * documents its `409 ConditionalRequestConflict` as retryable and the grant is not spent by it (a
+ * spent grant is the `412` of a `RejectedAssetError` with code `grant_used`); `server_error` is
+ * `runtime`, and retryable when the fallback table a refused API request reads would call its
+ * `status` retryable — any `5xx` but a `501`, which storage answers for a request it does not
+ * implement — or when it carries no status; `unexpected` is `runtime`, and retryable when that
+ * table would call its `status` retryable — storage's `408` or `429`, refused for its timing —
+ * and not retryable for any other status or none; `unreachable` is `config` and retryable, like
+ * `ApiUnreachableError`; `redirected` is `config` and not retryable; `invalid_grant_url` and no
+ * code at all are `runtime` and not retryable.
  */
 export declare class UploadTransportError extends InputPreparationError {
     readonly status: number | undefined;
@@ -144,10 +253,16 @@ export declare class UploadTransportError extends InputPreparationError {
  * operation throws only when it can produce no verdict at all. Transport
  * failures on the resolve route (`ApiResponseError`, `ApiUnreachableError`)
  * and the run-lifecycle errors propagate unchanged, so they are not subclasses.
+ *
+ * Its verdict is `runtime`, not retryable, unless `options.verdict` declares another: the SDK
+ * declares `input` where it refuses an argument (a `scope`, a bound, a location) and `config`
+ * where the environment refuses the download (a runtime with no filesystem, a directory that
+ * cannot be created).
  */
-export declare class ArtifactOperationError extends PipelineRequestError {
+export declare class ArtifactOperationError extends PipelexRequestError {
     constructor(message: string, options?: {
         cause?: unknown;
+        verdict?: ErrorVerdict;
     });
 }
 /**
@@ -174,6 +289,14 @@ export declare class ScopeUnavailableError extends ArtifactOperationError {
  * (any other non-2xx), `too_large`, `timeout`, `network`. `status` is the
  * store's HTTP status when one was received. `downloadArtifacts` never lets
  * this escape: it becomes the item's `error`.
+ *
+ * Its verdict follows `code`: `invalid_storage_uri`, `forbidden`, `unsupported_url`, `not_found`
+ * and `too_large` are `input` and not retryable, since the reference or the bound must change;
+ * `plain_http_refused` is `config` and not retryable; `redirect_refused` and `store_refused` are
+ * `runtime` and not retryable; `timeout` and `network` are `runtime` and retryable; `store_error`
+ * is `runtime`, and retryable when the fallback table a refused API request reads would call its
+ * `status` retryable — a `408`, a `429` or a `5xx` other than `501` — and not retryable for any
+ * other status or none. A code this version does not know is `runtime` and not retryable.
  */
 export declare class ArtifactFetchError extends ArtifactOperationError {
     readonly uri: string;
@@ -189,7 +312,9 @@ export declare class ArtifactFetchError extends ArtifactOperationError {
  * the download stops — but the files already saved are real, and `verdict`
  * carries the result as it stood: every item saved before the refusal, and
  * the rest marked `aborted`. `status` is the route's status; the wrapped
- * `ApiResponseError` is reachable via `cause`.
+ * `ApiResponseError` is reachable via `cause`. (`verdict` is the download's result, not the
+ * error's own: that is `retryable` and `errorDomain`, `config` and not retryable, since the
+ * credential must change.)
  */
 export declare class ArtifactAuthenticationError extends ArtifactOperationError {
     readonly status: number;
@@ -206,8 +331,13 @@ export declare class ArtifactAuthenticationError extends ArtifactOperationError
  *
  * `code` is the underlying network error code when available
  * (`ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`, `EAI_AGAIN`, `ABORT_TIMEOUT`).
+ *
+ * Its verdict is `config` and retryable: the address or the network must be checked, and a later
+ * attempt can get through. With the code `ABORT_TIMEOUT`, the SDK's own request timeout, it is
+ * `runtime` and retryable instead: the API took the request and did not answer in time, which is
+ * no fault of the base URL.
  */
-export declare class ApiUnreachableError extends PipelineRequestError {
+export declare class ApiUnreachableError extends PipelexRequestError {
     readonly apiUrl: string;
     readonly code: string | undefined;
     constructor(message: string, apiUrl: string, code: string | undefined, options?: {
@@ -219,8 +349,11 @@ export declare class ApiUnreachableError extends PipelineRequestError {
  * hosted gateway's ~30s synchronous-request limit. The blocking path cannot
  * run methods longer than 30s behind the hosted gateway — use the durable run
  * lifecycle (start + poll) instead.
+ *
+ * Its verdict is `input`, not retryable: asking again meets the same limit, and the caller fixes
+ * it by starting the run and polling.
  */
-export declare class PipelineExecuteTimeoutError extends PipelineRequestError {
+export declare class PipelineExecuteTimeoutError extends PipelexRequestError {
     readonly elapsedMs: number;
     constructor(elapsedMs: number, options?: {
         cause?: unknown;
@@ -247,8 +380,15 @@ export declare class PipelineExecuteTimeoutError extends PipelineRequestError {
  *   report's message (`Run finished with status FAILED: <message>`), so printing the error
  *   already tells the reason.
  * - `runId` locates the run, for a status read or a support request.
+ *
+ * Its verdict comes from the report. `errorDomain` is the report's `error_domain` when it is one
+ * of the three domains, and `runtime` otherwise, including a run with no report. `retryable` is
+ * true only when the report's `retryable` is `true`: a report that says nothing, and a run with
+ * none, read as not retryable, since starting the run again spends credit and nothing says it
+ * would succeed. The report keeps its own `retryable` as written, so a consumer that words the
+ * unknown differently still can.
  */
-export declare class RunFailedError extends PipelineRequestError {
+export declare class RunFailedError extends PipelexRequestError {
     readonly runId: string;
     readonly status: RunStatus;
     readonly error: RunErrorReport | null;
@@ -266,8 +406,10 @@ export declare class RunFailedError extends PipelineRequestError {
  * `execute` response named a `main_stuff_name` whose stuff is absent from the returned working
  * memory. `runId` locates the run. (An empty-but-present main stuff — `{ items: [] }`, `{ text:
  * "" }` — is a valid output and does NOT throw; only a genuinely absent one does.)
+ *
+ * Its verdict is `runtime`, not retryable: the API broke its own contract on a completed run.
  */
-export declare class MissingMainStuffError extends PipelineRequestError {
+export declare class MissingMainStuffError extends PipelexRequestError {
     readonly runId: string;
     constructor(message: string, runId: string);
 }
@@ -275,8 +417,10 @@ export declare class MissingMainStuffError extends PipelineRequestError {
  * Thrown when `waitForResult` exceeds its `timeoutMs` before the run reaches a
  * terminal state. The run is NOT cancelled — it keeps executing server-side and
  * can be resumed later by `runId` (the poll loop just stopped waiting).
+ *
+ * Its verdict is `runtime` and retryable: the run is still going, and waiting again can succeed.
  */
-export declare class RunTimeoutError extends PipelineRequestError {
+export declare class RunTimeoutError extends PipelexRequestError {
     readonly runId: string;
     readonly timeoutMs: number;
     constructor(message: string, runId: string, timeoutMs: number);
@@ -289,8 +433,10 @@ export declare class RunTimeoutError extends PipelineRequestError {
  * when it cannot hold the connection open. The run keeps executing
  * server-side — resume by `runId` (`getRunResult` / `waitForResult` on a
  * hosted deployment, or the `location` status resource when provided).
+ *
+ * Its verdict is `runtime` and retryable: the run is still going, and is resumed by its id.
  */
-export declare class RunStillRunningError extends PipelineRequestError {
+export declare class RunStillRunningError extends PipelexRequestError {
     readonly runId: string;
     readonly retryAfterSeconds: number | null;
     readonly location: string | null;
@@ -307,13 +453,28 @@ export declare class RunStillRunningError extends PipelineRequestError {
  * it 404s those routes; only a deployment that includes the platform block
  * (the Pipelex Hosted API) serves status/results. Distinguished from a genuine
  * run-not-found 404, which carries the server's structured error envelope.
+ *
+ * Its verdict is `config`, not retryable: the base URL points at a bare runner without the run
+ * lifecycle.
  */
-export declare class RunLifecycleUnavailableError extends PipelineRequestError {
+export declare class RunLifecycleUnavailableError extends PipelexRequestError {
     readonly apiUrl: string;
     constructor(message: string, apiUrl: string, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Thrown when a paged-list iterator (`iterateMethods`) refuses to keep following cursors.
+ *
+ * The ceiling, `pageLimit` pages, sits far beyond any real catalog, so reaching it is a
+ * server-side fault — an endpoint minting a fresh cursor forever — not a coverage limit the caller
+ * can raise. Throwing beats returning, because a silently truncated list is exactly the bug
+ * paging was introduced to remove. Its verdict is `runtime`, not retryable.
+ */
+export declare class PagingNotTerminatingError extends PipelexRequestError {
+    readonly pageLimit: number;
+    constructor(message: string, pageLimit: number);
+}
 /**
  * The last constructor argument of `ApiResponseError`: the error's `cause`, the problem
  * document's typed members, and the decoded document whole. The same shape as `mthds`'s
@@ -325,16 +486,32 @@ export interface ApiResponseErrorOptions {
     problemDocument?: Record<string, unknown>;
 }
 /**
- * A non-2xx response that DID come back from the API, with its problem document parsed.
+ * A response that DID come back from the API and that the SDK cannot hand back as a result: a
+ * non-2xx refusal, with its problem document parsed, or a 2xx answer the SDK could not read —
+ * a body that is not JSON, JSON that is not the object the route answers, or a stored method
+ * whose `python` field is not the serialized file list. The second carries the answer's status
+ * and raw text, no problem member, what made it unreadable as `cause` (the parse failure, or
+ * `mthds`'s refusal of the `python` field), and the verdict the fallback gives a 2xx: `runtime`,
+ * not retryable.
  *
  * Every error the hosted API answers is an RFC 9457 `application/problem+json` document, and
  * this error carries its members as typed fields, each `undefined` when the document did not
- * carry it (a member of the wrong type reads as absent rather than as a wrong value):
+ * carry it (a member of the wrong type reads as absent rather than as a wrong value, and the
+ * nested members `providerMetadata`, `migration`, `validationErrors` and `errors` are checked
+ * field by field as a failed run's stored report is) — except the verdict, which is always
+ * decided:
  *
- * - **The branch fields.** `errorDomain` says who can fix the failure — `input` (the caller),
- *   `config` (a configuration change), `runtime` (nobody beforehand) — and `type` is the stable
- *   URI naming the error class. `retryable` says whether a retry can succeed, `undefined`
- *   meaning unknown. Branch on these, never on the HTTP status or on the wording of a message.
+ * - **The verdict.** `errorDomain` says who can fix the failure — `input` (the caller),
+ *   `config` (a configuration change), `runtime` (nobody beforehand) — and `retryable` whether
+ *   asking again can succeed. Each is the document's member when the server sent a valid one,
+ *   and otherwise the SDK's fallback, read from the status, the platform `code` and whether the
+ *   body names what it refused. A runner often sends `error_domain` without `retryable`, and
+ *   then the domain it sent decides `retryable`: `input` and `config` are not retryable, as a
+ *   stored report that says nothing is not, since the caller or the environment must change,
+ *   while `runtime` takes the fallback's. Nothing on the error says which a value came from:
+ *   `problemDocument` keeps what the server sent.
+ * - **The branch fields.** `errorDomain`, and `type`, the stable URI naming the error class.
+ *   Branch on these, never on the HTTP status or on the wording of a message.
  * - **The native codes.** `code` is the platform's own closed code (`conflict`, `not_found`,
  *   `pipelex_api_key_limit_reached`, …) and `errorType` the runner's open exception class
  *   name. Each is finer than `errorDomain` and specific to the surface that emits it; the
@@ -352,11 +529,11 @@ export interface ApiResponseErrorOptions {
  * `problemDocument` is the decoded document whole, so a member this SDK does not name stays
  * reachable without re-parsing `responseBody`, which is the raw text; it is `undefined` when
  * the body was not a JSON object. The members `mthds`'s own `ApiResponseError` carries have the
- * same names and types here, and the rest (`code`, `errorCategory`, `model`, `provider`,
- * `providerMetadata`, `migration`, `errors`) are the Pipelex members the standard's client
- * leaves to this SDK.
+ * same names here, and the same types except the verdict, which this SDK narrows from optional
+ * to decided; the rest (`code`, `errorCategory`, `model`, `provider`, `providerMetadata`,
+ * `migration`, `errors`) are the Pipelex members the standard's client leaves to this SDK.
  */
-export declare class ApiResponseError extends PipelineRequestError {
+export declare class ApiResponseError extends PipelexRequestError {
     readonly apiUrl: string;
     readonly status: number;
     readonly statusText: string;
@@ -385,24 +562,11 @@ export declare class ApiResponseError extends PipelineRequestError {
      * lines for this request.
      */
     readonly requestId: string | undefined;
-    /**
-     * The body's `error_domain`: who can fix the failure. `input` — the caller (a malformed
-     * bundle, a bad argument, a missing input); `config` — a configuration change (a missing
-     * secret, a model the backend does not serve); `runtime` — nobody beforehand (a provider
-     * outage during execution). Typed open, as the server owns the vocabulary; `undefined` when
-     * the server did not classify it.
-     */
-    readonly errorDomain: string | undefined;
     /**
      * The body's `error_category`: the finer classification of an inference failure — known
      * values `transient`, `configuration`, `content`, `capacity`, `ambiguous`, `unknown`.
      */
     readonly errorCategory: string | undefined;
-    /**
-     * The body's `retryable`: whether retrying the same request can plausibly succeed.
-     * `undefined` means unknown, which is not the same as `false`.
-     */
-    readonly retryable: boolean | undefined;
     /** The body's `user_action`: what the caller should do next, when the server can say. */
     readonly userAction: UserAction | undefined;
     /** The body's `model`: the model an inference failure used. */