@pipelex/sdk 0.51.0 → 0.53.0

package/dist/client.d.ts

@@ -60,8 +60,8 @@ export interface PipelexHostedRunExtensions {
      *
      * - **Alone** — the platform resolves the version the id names and runs its
      *   files, with the method's Python files beside them. A bare `mt_…` runs the
-     *   latest published version, a `409` `method_not_published` for a method never
-     *   published; `mt_…@<n>` runs version `n`, a `404` `method_version_not_found`
+     *   latest published version, a `409` `pipelex.catalog.not_published` for a method never
+     *   published; `mt_…@<n>` runs version `n`, a `404` `pipelex.catalog.not_found`
      *   for a version never published; `mt_…@draft` runs the draft. The suffix
      *   rides the string untouched, any other suffix is a `422`, and the answer's
      *   `method_version` says which version runs.
@@ -110,11 +110,11 @@ export interface PipelexStartRequestOptions {
      * The hosted API binds the key to the run the first request starts, before it dispatches it, so
      * the same start sent again under the same key is answered with that run's acknowledgement and
      * starts nothing, whatever became of the first attempt, for 24 hours. A failed start whose
-     * `runMayHaveStarted` is true can therefore be sent again unchanged, and recovers the run instead
-     * of paying for a second one. The same key with a different body is refused (`409` `conflict`),
-     * as is a key whose earlier request is still being handled (`409` `idempotency_key_in_use`,
-     * retryable: send it again under the same key in a few seconds); see `docs/errors.md`. A bare
-     * runner ignores the header.
+     * problem's `retry` is `outcome_unknown` can therefore be sent again unchanged, and recovers the
+     * run instead of paying for a second one. The same key with a different body is refused (`409`
+     * `request.idempotency_conflict`), as is a key whose earlier request is still being handled
+     * (`409` `request.idempotency_key_in_use`, whose `retry` is `yes`: send it again under the same
+     * key after its `retry_after`); see `docs/errors.md`. A bare runner ignores the header.
      *
      * A key is 1 to 255 visible ASCII characters (`!` to `~`, so no space); anything else, an empty
      * string included, is a `RequestArgumentError` before any request is sent, since a start sent
@@ -139,11 +139,12 @@ export interface MethodCopyRequestOptions {
      * can be sent again unchanged and makes one copy, not two. A verdict and a `4xx` refusal of the
      * copy are stored alike, so the same copy under the same key is answered the same again; a `5xx`
      * and a refusal for its timing (a `408`, `425` or `429`) are not stored, and a copy that failed
-     * with one left nothing visible, so the same key sends it afresh.
-     * The same key with a different body is refused (`409` `conflict`), as is a key whose earlier
-     * request is still being handled (`409` `idempotency_key_in_use`, retryable: send it again
-     * under the same key in a few seconds); a changed copy, such as one with a fresh draft token,
-     * goes under a new key. See `docs/method-copy.md`.
+     * with one left nothing visible, but for the `503` whose `detail` names the copy (see
+     * `copyMethod`), so the same key sends it afresh. The same key with a different body is refused
+     * (`409` `request.idempotency_conflict`, whose `retry` is `no`), as is a key whose earlier
+     * request is still being handled (`409` `request.idempotency_key_in_use`, whose `retry` is
+     * `yes`: send it again under the same key in a few seconds); a changed copy, such as one with a
+     * fresh draft token, goes under a new key. See `docs/method-copy.md`.
      *
      * A key is held to the rule a start's is (`PipelexStartRequestOptions.idempotencyKey`): 1 to
      * 255 visible ASCII characters, anything else a `RequestArgumentError` before any request.
@@ -216,8 +217,8 @@ export interface PipelexApiClientOptions {
 export declare const DEFAULT_API_BASE_URL = "https://api.pipelex.com";
 /**
  * The protocol surface `PipelexApiClient` implements as the standard types it: every route but
- * `validate`, whose verdict is Pipelex's own (`PipelexValidationResult`) while the hosted plane
- * answers the verdict that predates the protocol's problem items.
+ * `validate`, whose verdict is Pipelex's own (`PipelexValidationResult`): the protocol's problem
+ * items beside members of the hosted plane's own.
  */
 type HostedProtocolSurface = Omit<MTHDSProtocol<DictPipeOutput>, "validate">;
 export declare class PipelexApiClient implements HostedProtocolSurface {
@@ -255,17 +256,27 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * Issue one HTTP request and return the raw status/headers/body. Wraps
      * DNS/connect/TLS/timeout failures as `ApiUnreachableError`; a caller-driven
      * abort (Ctrl-C / agent walk-away) propagates as-is so the poll loop can stop
-     * cleanly. Non-2xx interpretation is left to the caller. `url` is a fully
-     * resolved absolute URL. `mayStartRun` marks a request that may create a run,
-     * whose `ApiUnreachableError` then says whether it may have (see `RunCreation`).
+     * cleanly. A body that arrived and could not be decoded, such as a `gzip` body that is not
+     * gzip, is an answer, so it throws the `ApiResponseError` of that answer, read as an answer
+     * with an empty body (see `isUndecodableBody`). Non-2xx interpretation is left to the caller.
+     * `url` is a fully resolved absolute URL. `mayStartRun` marks a request that may create a run,
+     * whose errors then say whether it may have (see `RunCreation`).
      * `idempotencyKey`, already checked by `idempotencyKeyOf`, is sent as the
      * `Idempotency-Key` header; only `start` and `copyMethod` pass one.
      */
     private requestRaw;
+    /**
+     * The `ApiResponseError` of an answer whose body arrived and could not be decoded: the answer's
+     * status and headers, read as an answer with an empty body (`readHostedAnswer`), so a `2xx` is
+     * `client.response_unreadable` naming its status, or `client.outcome_unknown` on a request that
+     * may create a run, which the server accepted. `code` is the decompressor's, named in the
+     * message, and the decoding failure is its `cause`.
+     */
+    private undecodableAnswer;
     /**
      * Issue a Pipelex-product request (`/v1/me`, `/v1/methods`, `/v1/billing/*`,
      * …) and parse its JSON body, mapping a non-2xx response to the typed
-     * `ApiResponseError` so callers branch on its `errorDomain` and `type`, not the
+     * `ApiResponseError` so callers branch on its problem's `code`, not the
      * HTTP status. Empty-body tolerant — DELETE / onboarding / updateRun
      * answer 2xx with no body, returned as `undefined`. Uses the management-call
      * timeout, not the blocking-execute ceiling.
@@ -309,8 +320,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * One page of a cursor-paged product route (`listMethods`, `listMethodVersions`,
      * `listMethodExamples`, `listRuns`, `listFiles`), read as the platform always serializes it: `items` an
      * array, `next_cursor` a string or `null`. A page breaking either is an answer the SDK cannot
-     * read, so it throws the `ApiResponseError` `unreadableAnswer` builds, `runtime` and not
-     * retryable, rather than handing the iterators a page they cannot walk: `items` that is not
+     * read, so it throws the `ApiResponseError` `unreadableAnswer` builds,
+     * `client.response_unreadable`, rather than handing the iterators a page they cannot walk: `items` that is not
      * iterable, or a missing cursor that is neither the end nor a next page, which `iterateRuns`
      * would follow forever. A route reading its rows itself passes `rows`: `parse` reads the page's
      * text, and `item` reads each row, throwing as `unreadableAnswer` does for one it cannot read.
@@ -367,23 +378,29 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
     /**
      * The `ApiResponseError` of a 2xx answer the SDK cannot read, its message
      * `API <method> <path> answered <status> with <what>`: the answer's status, its raw text as
-     * `responseBody`, no hosted problem member but the `X-Request-ID` header, the failure that made it
-     * unreadable as `cause`, and the verdict the fallback gives a 2xx, `runtime` and not retryable.
-     * An answer that carries signed links (`RawResponse.carriesLinks`) is held with every link
-     * hidden, and with no `cause`, which could quote one. On a request that may create a run, the run may have started: the server accepted it.
+     * `responseBody`, the failure that made it unreadable as `cause`, and the problem
+     * `client.response_unreadable` naming the status. On a request that may create a run, the run
+     * may exist, since the server accepted the request, so the problem is `client.outcome_unknown`
+     * instead, naming the run when the body names one. An answer that carries signed links
+     * (`RawResponse.carriesLinks`) is held with every link hidden, and with no `cause`, which could
+     * quote one.
      */
     private unreadableAnswer;
     /**
      * Throw the `ApiResponseError` of a non-2xx answer, naming the route by its `path` from the
-     * origin (`/v1/...`, or `/health` for the liveness probe).
+     * origin (`/v1/...`, or `/health` for the liveness probe). The answer is read as its problem
+     * (`readHostedAnswer`): the body as received when it is a problem document, whose `detail` the
+     * message quotes, and otherwise the problem the edge's bare answer reads as, the message
+     * quoting the body as it came, or the status text for an empty one.
      */
     private throwApiResponseErrorAt;
     /**
      * Translate a "route absent" 404 (a bare pipelex-api with no platform block)
-     * into a clear `RunLifecycleUnavailableError`. The platform's own 404s (run
-     * not found / cross-org) carry a structured error envelope (a `code` field)
-     * and are left for normal handling. `explanation` replaces the sentence saying
-     * why the route is missing, for a route a hosted API may also lack.
+     * into a clear `RunLifecycleUnavailableError`. A 404 a route answered on purpose (a run
+     * not found, cross-org included, or a method that does not exist) names its own `code`
+     * and is left for normal handling as `ApiResponseError` (`isMissingRoute404`).
+     * `explanation` replaces the sentence saying why the route is missing, for a route a
+     * hosted API may also lack.
      */
     private throwIfLifecycleUnavailable;
     /**
@@ -404,9 +421,9 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * there this throws.
      *
      * It goes through the same transport as every route: an unreachable origin is an
-     * `ApiUnreachableError`, and a non-2xx answer an `ApiResponseError` whose verdict the SDK's
-     * fallback reads from the status, since the probe answers no problem document. So is a 2xx
-     * whose body is not a JSON object, such as a gateway's HTML page: `runtime`, not retryable.
+     * `ApiUnreachableError`, and a non-2xx answer an `ApiResponseError` whose problem is read from
+     * the status when the probe answers no problem document. So is a 2xx whose body is not a JSON
+     * object, such as a gateway's HTML page: `client.response_unreadable`.
      */
     health(): Promise<Record<string, unknown>>;
     /**
@@ -454,15 +471,15 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      *
      * `options.idempotencyKey` is sent as the `Idempotency-Key` header, and nothing
      * is sent without it: the hosted API answers the same start sent again under the
-     * same key with the run the first one started, so a failure whose
-     * `runMayHaveStarted` is true can be retried unchanged (see
+     * same key with the run the first one started, so a failure whose problem's
+     * `retry` is `outcome_unknown` can be retried unchanged (see
      * `PipelexStartRequestOptions`). A malformed key is a `RequestArgumentError`
      * before anything is sent.
      *
      * The method's tree is prepared before the request as `execute` prepares it. The prepared body
      * is the same for the same tree, so a start retried under its idempotency key sends the body the
      * key was bound to. A start whose hash entries name a blob the API does not hold yet is refused
-     * with a `422` `missing_blobs`, which releases its key: send it again unchanged, which asks the
+     * with a `422` `request.blobs_missing`, which releases its key: send it again unchanged, which asks the
      * blob route and uploads what is missing first.
      */
     start(options: PipelexStartOptions): Promise<PipelexRunResultStart>;
@@ -476,7 +493,9 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `/validate` is a diagnostic endpoint: every produced verdict rides a **200**,
      * discriminated on `is_valid`. This returns the `PipelexValidationResult` union
      * verbatim — `is_valid: true` ⇒ the typed `PipelexValidationReport` (structural
-     * artifacts), `is_valid: false` ⇒ a `PipelexInvalidReport` (`validation_errors[]`).
+     * artifacts), `is_valid: false` ⇒ a `PipelexInvalidReport`, whose `errors[]` are problem
+     * items. Both arms' items, the invalid arm's `errors[]` and the valid arm's `warnings[]`, are
+     * read member by member (`readProblemItems`).
      * An invalid method is NOT thrown — the caller pattern-matches `is_valid`. Only a
      * *no-verdict* condition (a malformed request, a tree the route refuses, auth, a
      * server fault) is non-2xx and surfaces as `ApiResponseError`.
@@ -506,8 +525,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      *
      * A selector-resolution failure (fetch failure, no package at the address, an
      * unknown or foreign-org id, a bare id of a method never published, `409`
-     * `method_not_published`, a version never published, `404`
-     * `method_version_not_found`, or a malformed suffix, `422`) is a non-2xx
+     * `pipelex.catalog.not_published`, a version never published, `404`
+     * `pipelex.catalog.not_found`, or a malformed suffix, `422`) is a non-2xx
      * `ApiResponseError` — never an `is_valid: false` verdict, which is reserved
      * for actual MTHDS content.
      *
@@ -629,10 +648,9 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * Returns a **200 verdict** whatever the resolution: a reference that resolves nowhere is
      * `resolution: "not_found"` with the names it may have meant, never a thrown error. Narrow
      * on `kind` to read the shape of `matches`. A request that cannot produce a verdict throws
-     * the typed `ApiResponseError`, a `422` whose `errorType` says why: `InvalidModelReference`
-     * (a blank reference, a sigil or a namespace alone, or one past the runner's length limit),
-     * `InvalidModelCategory` (an unknown `type`) or `ValidationError`. None of that is checked
-     * here, so the runner's rule is the only one.
+     * the typed `ApiResponseError`, a `422` problem whose `code` says why: a blank reference, a
+     * sigil or a namespace alone, one past the runner's length limit, or an unknown `type`. None of
+     * that is checked here, so the runner's rule is the only one.
      */
     checkModelReference(reference: string, category?: ModelCheckCategory): Promise<ModelReferenceVerdict>;
     /**
@@ -654,7 +672,7 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      *
      * Returns a **200 verdict**: pattern-match `is_valid` before reading the arm — a
      * closure that does not parse/load/validate comes back as `is_valid: false` with
-     * `validation_errors[]`, not as a thrown error. Only a no-verdict condition throws
+     * problem items in `errors[]`, not as a thrown error. Only a no-verdict condition throws
      * `ApiResponseError`: a malformed selector (none, or more than one, of
      * `files` / `method_ref` / `method_id`) is a 422; a selector-resolution failure
      * (fetch failure, no package at the address, an unknown or foreign-org id) is
@@ -718,11 +736,11 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * {@link resolve} (the request's members are posted as given, its `directory`, `tree` or
      * `contents` as the `files` map, and the selector XOR is the server's to enforce).
      * Only a no-verdict condition throws `ApiResponseError`: a malformed selector and an
-     * over-limit file are `ValidationError` `422`s; a selection the route refuses is a
-     * `422` whose `errorType` is `EntryPipeNotFoundError` (an unknown `pipe_ref`, no entry
-     * pipe) or `EntryPipeAmbiguousError` (an ambiguous code, several entry pipes), the
-     * candidates in its `serverMessage`; a registry-form `method_ref` is a `501`; a pipe
-     * whose artifacts cannot be derived is a `500`.
+     * over-limit file are `422` problems; a selection the route refuses is a `422` whose
+     * `code` is `request.pipe_not_found` (an unknown `pipe_ref`), `request.pipe_unspecified`
+     * (no entry pipe) or `request.pipe_ambiguous` (an ambiguous code, several entry pipes), the
+     * candidates in its `params`; a registry-form `method_ref` is a `501`; a pipe whose
+     * artifacts cannot be derived is a `500`.
      *
      * A `method_ref` gets the fetch-sized budget, as on the other crate routes. On the
      * hosted API the gateway caps a request at about 30 seconds whatever the client allows,
@@ -764,9 +782,9 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * is live and the run is stuck, its workflow task failing until the platform
      * ends it at `degradation.ends_at`. `retry_after_seconds` carries the server's
      * `Retry-After` hint when present, and `request_id` the id to quote to support.
-     * A failed run's stored report, `error`, and the `degradation` are each
-     * checked field by field (see `RunErrorReport` and `RunDegradation`), so
-     * neither ever fails the read. Throws `RunLifecycleUnavailableError` when the
+     * A failed run's problem, `error`, is kept when it is a problem document and
+     * read as `null` otherwise, and the `degradation` is checked field by field
+     * (see `RunDegradation`), so neither ever fails the read. Throws `RunLifecycleUnavailableError` when the
      * lifecycle routes are absent (a bare runner).
      */
     getRunStatus(runId: string, options?: {
@@ -800,10 +818,10 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * Maps the server's poll semantics to a discriminated union:
      * - HTTP 202 → `running` (with the `Retry-After` hint)
      * - HTTP 200 → `completed` (with the result artifacts)
-     * - HTTP 409 → `failed` (terminal non-`COMPLETED`), carrying the problem's `detail` as
-     *   `message`, its `run_status` member as `status` (recovered from `detail` on a platform
-     *   that predates the member) and its `error` member, the run's stored error report, typed
-     *   as `error`
+     * - HTTP 409 `run.failed` → `failed` (terminal non-`COMPLETED`), carrying the problem as
+     *   `problem`, its `detail` as `message`, the terminal status its `run_status` parameter names
+     *   as `status`, and the run's own problem, which it nests as `run_error`, as `error`; a `409`
+     *   `run.not_finished` → `running`, and any other `409` throws `ApiResponseError`
      * - HTTP 503 → `running` (Temporal degraded — retry, never fail a poller)
      *
      * `options.artifacts` narrows the read to the named artifacts, sent as one
@@ -840,8 +858,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * real error; no answer at all propagates, uncached. An answer is anything the
      * server sent back: a non-2xx status, a body that is not JSON, not UTF-8 or no
      * version, and a body that arrived but could not be decoded, such as a broken
-     * gzip stream, which `requestRaw` reports as an `ApiUnreachableError` carrying
-     * the decompressor's code (see `isUndecodableBody`).
+     * gzip stream, which `requestRaw` reports as an `ApiResponseError` (see
+     * `isUndecodableBody`).
      *
      * `signal` stops the handshake: its abort is thrown as is and nothing is cached.
      *
@@ -876,11 +894,13 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * rather than listing, reading and hashing the tree again.
      *
      * An error from the start, or from the blocking execute, says whether that request may still
-     * have started a run whose id never reached the caller (`runMayHaveStarted`); when it may have,
-     * it is not retryable, since calling this method again could pay for the run twice: look the run
-     * up in the run history first. An error from the wait, once `onStarted` has named the run,
-     * started nothing, so its `runMayHaveStarted` is false, and its `retryable` is about waiting
-     * again on that id with `waitForResult`, never about calling this method again.
+     * have started a run whose id never reached the caller: its problem's `retry` is then
+     * `outcome_unknown`, since calling this method again could pay for the run twice, unless it is
+     * made with the same `idempotencyKey`: look the run up in the run history first. An error from
+     * the wait, once `onStarted` has named the run, started nothing, and its problem is about that
+     * run: `client.follow_failed` for a wait that ran out of time, whose step is to read the run
+     * again with `waitForResult`, or `run.failed` for a run that ended without success, never a
+     * reason to call this method again.
      *
      * `options.idempotencyKey` rides the durable start, so a call that failed while its start may
      * have created a run can be made again with the same options and the same key: the hosted API
@@ -959,16 +979,17 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * and for an id that is empty, `.` or `..`, which the URL would resolve into another route's
      * path.
      *
-     * Throws `ApiResponseError`: `404` `not_found` for an unknown or foreign-org method, `409`
-     * `method_being_deleted` while its erasure runs, and a `409` whose verdict is `runtime` for a
-     * method whose draft names a tree the platform holds no record of. An answer whose `files` is
-     * not a listing is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
+     * Throws `ApiResponseError`: `404` `pipelex.catalog.not_found` for an unknown or foreign-org
+     * method, `409` `pipelex.catalog.being_deleted` while its erasure runs, and a `500`
+     * `runtime.unexpected` for a method whose draft names a tree the platform holds no record of. An
+     * answer whose `files` is not a listing is an answer the SDK cannot read, thrown as an
+     * `ApiResponseError` too.
      */
     getMethod(methodId: string): Promise<MethodDetail>;
     /**
      * Create a method — `POST /v1/methods`. The new method holds its tree as its draft and has no
-     * published version, so its bare id answers `409 method_not_published` on the run and tooling
-     * routes until its first `publishMethod`; its draft runs as `mt_…@draft` at once.
+     * published version, so its bare id answers `409` `pipelex.catalog.not_published` on the run and
+     * tooling routes until its first `publishMethod`; its draft runs as `mt_…@draft` at once.
      *
      * The tree is `files`, sent as given, or `tree` or `contents`, which the client sends inline
      * when its inline map weighs 256 KiB or less, or when the platform keeps no blob store, and
@@ -978,12 +999,12 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      *
      * Throws `RequestArgumentError` for two forms of the tree, or `contents` holding no file, before
      * any request; `MethodFileTransferError` when a file the organization lacks could not be
-     * uploaded, and nothing is saved. Throws `ApiResponseError`: `422` `invalid_method_files` for a
-     * map the standard refuses, with its `tree_refusal`; `422` `method_tree_too_large` for a tree
-     * past one of the deployment's limits, named in its `limit`; `422` `blob_mismatch` for a hash
-     * stated at another size than the one held; `422` `missing_blobs` for a hash entry whose bytes
-     * the organization does not hold; `413` `payload_too_large` for a method that would leave no
-     * room for a publish.
+     * uploaded, and nothing is saved. Throws `ApiResponseError`: `422` `method.package_invalid` for
+     * a map the standard refuses, naming the path in its `params`, and for a tree past one of the
+     * deployment's limits, its `params` carrying `reason` `too_large` and the integer `limit`;
+     * `422` `request.invalid` for a hash stated at another size than the one held; `422`
+     * `request.blobs_missing` for a hash entry whose bytes the organization does not hold; `413`
+     * `request.too_large` for a method that would leave no room for a publish.
      */
     createMethod(input: MethodWriteInput): Promise<MethodData>;
     /**
@@ -996,16 +1017,16 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `files: null` emptying the draft, or `tree` or `contents`, sent inline or by hash as
      * `createMethod` sends them. `input_data` is three-way (see `MethodDraftInput`). With
      * `expected_updated_at`, the write is a compare-and-swap on the draft token: a draft that
-     * moved since is refused with a `409` whose `code` is `method_update_conflict`, and nothing is
+     * moved since is refused with a `409` whose `code` is `pipelex.catalog.update_conflict`, and nothing is
      * written. Without it, last writer wins.
      *
      * Takes a bare catalog id, as `getMethod` does. Throws `RequestArgumentError` for a draft that
      * gives its tree in no form or in two, or `contents` holding no file, before any request;
      * `MethodFileTransferError` when a file the organization lacks could not be uploaded. Throws
-     * `ApiResponseError`: `404` `not_found` for an unknown or foreign-org method, `409`
-     * `method_being_deleted` while its erasure runs, the `422` refusals of a tree `createMethod`
-     * lists, `413` `payload_too_large` for a draft that would grow the method past the room a
-     * publish needs, `403` for a read-only key, and a `503` that wrote nothing, safe to retry,
+     * `ApiResponseError`: `404` `pipelex.catalog.not_found` for an unknown or foreign-org method,
+     * `409` `pipelex.catalog.being_deleted` while its erasure runs, the `422` refusals of a tree
+     * `createMethod` lists, `413` `request.too_large` for a draft that would grow the method past the
+     * room a publish needs, `403` for a read-only key, and a `503` that wrote nothing, safe to retry,
      * when the method kept changing under the write.
      */
     writeDraft(methodId: string, input: MethodDraftInput): Promise<MethodData>;
@@ -1177,11 +1198,11 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * draft, so the `updated_at` a caller holds stays valid for its next `writeDraft` or
      * `publishMethod`.
      *
-     * Takes a bare catalog id, as `getMethod` does. Throws `ApiResponseError`: `404` `not_found`,
-     * `409` `method_being_deleted`, `403` for a read-only key, `422` for an empty name or one
-     * holding a lone surrogate, `413` `payload_too_large` for a name so long it would leave the
-     * method too large to publish, and a `503` that wrote nothing, safe to retry, when draft
-     * writes kept landing under the rename.
+     * Takes a bare catalog id, as `getMethod` does. Throws `ApiResponseError`: `404`
+     * `pipelex.catalog.not_found`, `409` `pipelex.catalog.being_deleted`, `403` for a read-only key,
+     * `422` for an empty name or one holding a lone surrogate, `413` `request.too_large` for a name
+     * so long it would leave the method too large to publish, and a `503` that wrote nothing, safe
+     * to retry, when draft writes kept landing under the rename.
      */
     renameMethod(methodId: string, input: MethodRenameInput): Promise<MethodData>;
     /**
@@ -1195,16 +1216,17 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * The answer is a `MethodPublishResult` discriminated on `outcome` — branch on it:
      * `published` with the new `version`; `unchanged` with the existing latest `version`;
      * `refused` with a `reason` (`invalid`, or `not_runnable` for a draft that validates with
-     * pending signatures), a `message` and the runner's `validation` verdict. Every arm carries the
-     * `method`. A publish moves no token.
+     * pending signatures), a `message` and the runner's `validation` verdict, whose problem items
+     * are read member by member as `validate` reads them. Every arm carries the `method`. A publish
+     * moves no token.
      *
      * Takes a bare catalog id, as `getMethod` does. Throws `RequestArgumentError` when
      * `expected_draft_updated_at` is not a string, before any request. Throws `ApiResponseError`
-     * when no verdict was produced: `409` `method_update_conflict` for a draft that moved since
-     * the token, `409` `method_being_deleted`, `404` `not_found`, `422` for a draft with no
-     * `.mthds` file or whose file names a run could not assemble (one name used by a `.mthds` and
-     * a Python file), `413` `payload_too_large` for a draft too large to publish, and `403` for a
-     * read-only key.
+     * when no verdict was produced: `409` `pipelex.catalog.update_conflict` for a draft that moved since
+     * the token, `409` `pipelex.catalog.being_deleted`, `404` `pipelex.catalog.not_found`, `422` for
+     * a draft with no `.mthds` file or whose file names a run could not assemble (one name used by a
+     * `.mthds` and a Python file), `413` `request.too_large` for a draft too large to publish, and
+     * `403` for a read-only key.
      *
      * Only a draft that differs from the latest version reaches the runner, and a runner that
      * cannot be reached, answers unusably or does not finish within the platform's deadline is a
@@ -1212,8 +1234,9 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * itself is relayed under its own status. A retry of a publish that landed while its answer was
      * lost, as on a client timeout, answers `unchanged` with the version it wrote.
      *
-     * An answer whose `outcome` is not one of the outcomes above, or that carries no `method`
-     * object, is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
+     * An answer whose `outcome` is not one of the outcomes above, that carries no `method` object,
+     * or a refusal whose `validation` is not a verdict object with a boolean `is_valid`, is an answer
+     * the SDK cannot read, thrown as an `ApiResponseError` too.
      */
     publishMethod(methodId: string, input: MethodPublishInput): Promise<MethodPublishResult>;
     /**
@@ -1224,10 +1247,11 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * may be short while `nextCursor` is set, because the platform reads versions whole. A method
      * never published answers an empty page.
      *
-     * Takes a bare catalog id, as `getMethod` does. Throws `ApiResponseError`: `404` `not_found`
-     * for an unknown method, `409` `method_being_deleted`, `400` `malformed_request` for a cursor
-     * the listing did not issue for this method, `422` for a `limit` outside 1 to 100. A page whose `items` is not an array or whose `next_cursor` is neither a string nor `null`
-     * is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
+     * Takes a bare catalog id, as `getMethod` does. Throws `ApiResponseError`: `404`
+     * `pipelex.catalog.not_found` for an unknown method, `409` `pipelex.catalog.being_deleted`, and
+     * `422` `request.invalid` for a cursor the listing did not issue for this method or a `limit`
+     * outside 1 to 100. A page whose `items` is not an array or whose `next_cursor` is neither a
+     * string nor `null` is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
      */
     listMethodVersions(methodId: string, query?: ListMethodVersionsQuery): Promise<MethodVersionPage>;
     /**
@@ -1237,10 +1261,10 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      *
      * Takes a bare catalog id, as `getMethod` does, and the version number. Throws
      * `RequestArgumentError` for a `version` that is not a positive integer, before any request.
-     * Throws `ApiResponseError`: `404` `method_version_not_found` for a version the method never
-     * published, `404` `not_found` for an unknown method, `409` `method_being_deleted`, and `409`
-     * `conflict`, whose verdict is `runtime`, for a version stored before methods were trees and
-     * never rewritten as one, which names no tree to serve.
+     * Throws `ApiResponseError`: `404` `pipelex.catalog.not_found` for a version the method never
+     * published and for an unknown method, `409` `pipelex.catalog.being_deleted`, and `500`
+     * `runtime.unexpected` for a version stored before methods were trees and never rewritten as
+     * one, which names no tree to serve.
      */
     getMethodVersion(methodId: string, version: number): Promise<MethodVersion>;
     /**
@@ -1258,7 +1282,9 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * The answer is a `MethodCopyResult` discriminated on `outcome` — branch on it: `copied` with
      * the copy as `method`, `examples_copied` and `stored_files_copied`; `refused` with the
      * `reason` `bundle_names_other_storage`, a `message` and every `references` entry (`{ path, uri
-     * }`) a `.mthds` file of the draft holds that the destination cannot read, nothing written.
+     * }`) a `.mthds` file of the draft holds that the destination cannot read and, in a duplicate,
+     * that names a file under the original's run files, which erasing the original would remove,
+     * nothing written.
      *
      * The route serves web sessions only: a Pipelex API key belongs to one organization and cannot
      * speak for another. `options.idempotencyKey` is sent as the `Idempotency-Key` header, so a copy
@@ -1271,21 +1297,31 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `destination_org_id` that is not a non-empty string, a `name` or an
      * `expected_draft_updated_at` given that is not a string, and a malformed idempotency key.
      * Throws `ApiResponseError` when no verdict was produced, each refusal writing nothing a reader
-     * sees: `403` `forbidden` for a request that is not from a web session; `403`
-     * `role_not_permitted` for a role that may not change methods, in the method's organization or
-     * in the destination; `404` `organization_not_found` for a destination the caller does not
-     * belong to, still being set up or unknown, alike; `404` `not_found` for an unknown method;
-     * `409` `method_being_deleted`; `409` `method_update_conflict` for a draft that moved since
-     * `expected_draft_updated_at`; `409` `conflict`, `runtime`, for a draft whose tree the
-     * organization holds no full record of; `413` `payload_too_large` for an example or a copy too
-     * large for one stored item; `422` `validation_failed` for a body that does not validate, such
-     * as a name holding a lone surrogate; `422` `method_copy_too_large` past one of the copy's
-     * bounds on the stored files it copies, named by `problemDocument.limit` (`MethodCopyLimit`);
-     * and, each retryable, a `502` when the platform could not read the caller's memberships, a
-     * `500` `storage_backend_failed` and a `503` past the copy's deadline. An answer whose
-     * `outcome` is neither arm's, a `copied` one whose `method` is not an object or a `refused` one
-     * whose `references` is not an array, is an answer the SDK cannot read, thrown as an
-     * `ApiResponseError` too.
+     * sees but for the `503` whose `detail` names the copy: `403` `auth.forbidden` for a request
+     * that is not from a web session, or for a role that may not change methods, in the method's
+     * organization or in the destination; `404` `pipelex.org.not_found` for a destination the
+     * caller does not belong to, still being set up or unknown, alike; `404`
+     * `pipelex.catalog.not_found` for an unknown method; `409` `pipelex.catalog.being_deleted`;
+     * `409` `pipelex.catalog.update_conflict` for a draft that moved since
+     * `expected_draft_updated_at`; a `409` whose `domain` is `runtime` and `retry` `no`, for a
+     * draft whose tree the method's organization holds no record of or no longer holds every file
+     * of; `413`
+     * `request.too_large` for a copied example, or the copy's row, too large for one stored item,
+     * the row keeping room for the summary a publish adds, so a `name` that would leave none is
+     * refused; `422` `request.invalid` for a body that does not validate, such as a name holding a
+     * lone surrogate; `422` `pipelex.catalog.copy_too_large` past one of the copy's bounds on the
+     * stored files it copies, named by the problem's `limit` member (`MethodCopyLimit`); a `502`
+     * `runtime.unavailable`, with `retry` `yes`, when the platform could not read the caller's
+     * memberships; a `503` `pipelex.storage.unavailable`, with `retry` `yes`, when storage failed,
+     * and a `500` `pipelex.storage.not_configured`, with `retry` `no`, when the platform has no
+     * usable credentials for storage; and a `503` `runtime.unavailable`, with `retry` `yes`, past
+     * the copy's deadline, when a stored file it copies is written over meanwhile, or when DynamoDB
+     * fails. When DynamoDB failed both the copy's row write and the read that would confirm it,
+     * that `503`'s `detail` names the copy's method id: the copy may stand in the destination, so
+     * look for that id there before copying again, since a retry may make a second copy. An answer
+     * whose `outcome` is neither arm's, a `copied` one whose `method` is not an object or a
+     * `refused` one whose `references` is not an array, is an answer the SDK cannot read, thrown as
+     * an `ApiResponseError` too.
      */
     copyMethod(methodId: string, input: MethodCopyInput, options?: MethodCopyRequestOptions): Promise<MethodCopyResult>;
     /**
@@ -1301,11 +1337,11 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * and a copy itself, answer an empty page. The listing is open to every member of the method's
      * organization, a runner included, as every read of a method is.
      *
-     * Takes a bare catalog id, as `getMethod` does. Throws `ApiResponseError`: `404` `not_found` for
-     * an unknown method, `409` `method_being_deleted`, `400` `malformed_request` for a cursor the
-     * listing did not issue for this method, `422` for a `limit` outside 1 to 100. A page whose
-     * `items` is not an array or whose `next_cursor` is neither a string nor `null` is an answer the
-     * SDK cannot read, thrown as an `ApiResponseError` too.
+     * Takes a bare catalog id, as `getMethod` does. Throws `ApiResponseError`: `404`
+     * `pipelex.catalog.not_found` for an unknown method, `409` `pipelex.catalog.being_deleted`, and
+     * `422` `request.invalid` for a cursor the listing did not issue for this method or a `limit`
+     * outside 1 to 100. A page whose `items` is not an array or whose `next_cursor` is neither a
+     * string nor `null` is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
      */
     listMethodCopies(methodId: string, query?: ListMethodCopiesQuery): Promise<MethodCopyPage>;
     /**
@@ -1321,7 +1357,7 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * it with a `409`.
      *
      * A double-clicked delete is safe: the claim is a conditional write, so the
-     * second call is an `ApiResponseError` (`409 method_being_deleted`) rather than a
+     * second call is an `ApiResponseError` (`409` `pipelex.catalog.being_deleted`) rather than a
      * second cascade over the same runs. An unknown or foreign-org id is a `404`. The
      * erasure deletes the method's published versions with the rest. Takes a bare catalog id,
      * as `getMethod` does: the whole method is erased, never one of its versions.
@@ -1336,8 +1372,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * closed, and a `null` `run_id` reads as not given. Throws `RequestArgumentError` before any
      * request when `name` or `inputs` is not given (`null` counting as not given), and for a
      * `run_id` that is given but is not a non-empty string. Throws `ApiResponseError`: `404`
-     * `run_not_found` for a `run_id` that is not one of this method's runs in the caller's
-     * organization, with nothing written; `413` `payload_too_large` for an example larger than one
+     * `run.not_found` for a `run_id` that is not one of this method's runs in the caller's
+     * organization, with nothing written; `413` `request.too_large` for an example larger than one
      * stored item holds; `422` for a name that is empty, blank or over 200 characters, or inputs
      * that are not a JSON object; and the codes every example route answers.
      */
@@ -1350,12 +1386,12 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * may be short while `nextCursor` is set, because the platform reads examples whole and stops
      * a read at 1 MB; `iterateMethodExamples` follows the cursor for a caller that wants them all.
      *
-     * Throws `ApiResponseError`: `400` `malformed_request` for a cursor the listing did not issue
-     * for this method, `422` for a `limit` outside 1 to 100, and the codes every example route
-     * answers. A page whose `items` is not an array, whose `next_cursor` is neither a string nor
-     * `null`, or one of whose items is not an example `readMethodExample` can read, is an answer
-     * the SDK cannot read, thrown as an `ApiResponseError` too. An example whose inputs hold an
-     * integer past the safe range is read like any other, that integer as a `bigint`.
+     * Throws `ApiResponseError`: `422` `request.invalid` for a cursor the listing did not issue for
+     * this method or a `limit` outside 1 to 100, and the codes every example route answers. A page
+     * whose `items` is not an array, whose `next_cursor` is neither a string nor `null`, or one of
+     * whose items is not an example `readMethodExample` can read, is an answer the SDK cannot read,
+     * thrown as an `ApiResponseError` too. An example whose inputs hold an integer past the safe
+     * range is read like any other, that integer as a `bigint`.
      */
     listMethodExamples(methodId: string, query?: ListMethodExamplesQuery): Promise<MethodExamplePage>;
     /**
@@ -1407,7 +1443,7 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      *
      * Throws `RequestArgumentError` before any request for an example id that is empty, `.` or
      * `..`, or when neither `name` nor `inputs` is given. Throws `ApiResponseError`: `413`
-     * `payload_too_large` for inputs larger than one stored item holds, `422` for a name that is
+     * `request.too_large` for inputs larger than one stored item holds, `422` for a name that is
      * empty, blank or over 200 characters, or inputs that are not a JSON object, a `503` that wrote
      * nothing, safe to retry, when concurrent edits kept landing under the write, and the codes
      * every example route answers.
@@ -1425,13 +1461,13 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * since and nothing was written. A stale run is the expected end of a run that outlasted an
      * edit, so it is answered, never thrown. Both arms carry the `example` as it stands.
      *
-     * Throws `RequestArgumentError` before any request, checking in this order: an example id that
-     * is empty, `.` or `..`, or holds a lone surrogate, a `run_id` that is not a non-empty string,
-     * and an `input_revision` that is not a positive integer. Throws `ApiResponseError` when no
-     * verdict was produced: `404` `not_found` for an example deleted since, `404` `run_not_found`
-     * for a run that is not one of this method's, with nothing written, and the codes every example
-     * route answers. An answer whose `outcome` is neither arm's, or whose `example` is not an
-     * example `readMethodExample` can read, is an answer the SDK cannot read, thrown as an
+     * Throws `RequestArgumentError` before any request, checking in this order: an example id that is
+     * empty, `.` or `..`, or holds a lone surrogate, a `run_id` that is not a non-empty string, and
+     * an `input_revision` that is not a positive integer. Throws `ApiResponseError` when no verdict
+     * was produced: `404` `pipelex.catalog.not_found` for an example deleted since, `404`
+     * `run.not_found` for a run that is not one of this method's, with nothing written, and the codes
+     * every example route answers. An answer whose `outcome` is neither arm's, or whose `example` is
+     * not an example `readMethodExample` can read, is an answer the SDK cannot read, thrown as an
      * `ApiResponseError` too, read as `publishMethod` reads its verdict.
      */
     recordMethodExampleLatestRun(methodId: string, exampleId: string, input: MethodExampleLatestRunInput): Promise<MethodExampleLatestRunResult>;
@@ -1457,8 +1493,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * the body is closed, and `null` reads as not given. Throws `RequestArgumentError` before any
      * request when `name` or `inputs` is not given, for an `example_id` that is not a non-empty
      * string or an `input_revision` that is not a positive integer, and when only one of the two is
-     * given. Throws `ApiResponseError`: `403` `role_not_permitted` for a role that may not change
-     * methods, such as a runner; `413` `payload_too_large` for an example larger than one stored item
+     * given. Throws `ApiResponseError`: `403` `auth.forbidden` for a role that may not change
+     * methods, such as a runner; `413` `request.too_large` for an example larger than one stored item
      * holds; `422` for a name that is empty, blank or over 200 characters, or inputs that are not a
      * JSON object; and the codes every example route answers. An answer whose `outcome` is neither
      * arm's, or whose `example` is not an example `readMethodExample` can read, is an answer the SDK
@@ -1469,10 +1505,10 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * Delete an example — `DELETE /v1/methods/{id}/examples/{example_id}`. The platform answers
      * `204`. Deleting the example leaves its latest run in the method's history.
      *
-     * Throws `RequestArgumentError` for an example id that is empty, `.` or `..`, before any
-     * request: `..` would address the method, and its erasure would answer the delete. Throws
-     * `ApiResponseError`: `404` `not_found` when there is no such example, one already deleted
-     * included, and the codes every example route answers.
+     * Throws `RequestArgumentError` for an example id that is empty, `.` or `..`, before any request:
+     * `..` would address the method, and its erasure would answer the delete. Throws
+     * `ApiResponseError`: `404` `pipelex.catalog.not_found` when there is no such example, one
+     * already deleted included, and the codes every example route answers.
      */
     deleteMethodExample(methodId: string, exampleId: string): Promise<void>;
     /** The caller's org memberships + active-org feature flags — `GET /v1/organizations/memberships`. */
@@ -1508,17 +1544,17 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      *
      * Throws `RequestArgumentError` for an organization id that is empty, `.` or `..`, before any
      * request. Throws `ApiResponseError`, refusing every change of the request when it refuses one:
-     * `403` `forbidden` when `orgId` is not the active organization, `403` `role_not_permitted` for
-     * a caller who is not its admin, `404` for a missing organization, `409` `conflict` for a
-     * personal workspace, which has no branding, and `422` `validation_failed` for a colour that is
-     * not `#rrggbb` or a key the body does not know. A logo's refusal names its slot in the error's
-     * `errors[]`, each entry's `field` being `square_logo` or `wide_logo` and its `detail` the
-     * sentence to show under that slot: `400` `invalid_storage_uri` for a URI that is not a storage
-     * URI, `403` `forbidden` for another organization's file, and `422` `validation_failed` with a
-     * `LogoRefusalCode` per broken rule for a file the platform refused. A failure of the platform's
-     * storage while reading or copying a logo is a `500` `storage_backend_failed`, retryable, with
-     * nothing written. A `503` `service_unavailable` is a failure of its database, after which the
-     * write may have landed or not: the same input sent again is safe.
+     * `403` `pipelex.org.mismatch` when `orgId` is not the active organization, `403`
+     * `auth.forbidden` for a caller who is not its admin, `404` `pipelex.org.not_found` for a missing
+     * organization, `409` `pipelex.org.not_manageable` for a personal workspace, which has no
+     * branding, and `422` `request.invalid` for a colour that is not `#rrggbb` or a key the body does
+     * not know. A logo's refusal names its slot in its problem's `errors`, each item's
+     * `location.field` being `square_logo` or `wide_logo` and its `detail` the sentence to show under
+     * that slot: `422` `pipelex.storage.uri_invalid` for a URI that is not a storage URI, `403`
+     * `pipelex.org.mismatch` for another organization's file, and `422` `request.invalid` with an
+     * item per broken rule, its code one `LogoRefusalCode` names, for a file the platform refused. A
+     * `503` `runtime.unavailable` is a failure of the platform's storage or its database, after which
+     * the write may have landed or not: the same input sent again is safe.
      */
     updateOrganizationBranding(orgId: string, input: OrganizationBrandingUpdate): Promise<OrganizationBranding>;
     /** The active org's subscription state — `GET /v1/billing/subscription`. */
@@ -1533,7 +1569,7 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
     }): Promise<CheckoutResponse>;
     /**
      * Switch the existing subscription's plan — `POST /v1/billing/change-plan`.
-     * A 409 `conflict` (`ApiResponseError.code`) means there is no subscription
+     * A 409 `pipelex.billing.subscription_conflict` (`ApiResponseError.code`) means there is no subscription
      * to change — start one via `createCheckout` first.
      */
     changePlan(input: {
@@ -1541,14 +1577,14 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
     }): Promise<ChangePlanResponse>;
     /**
      * A Stripe billing-portal session URL — `GET /v1/billing/portal`. A 409
-     * `conflict` (`ApiResponseError.code`) means there is no subscription yet.
+     * `pipelex.billing.subscription_conflict` (`ApiResponseError.code`) means there is no subscription yet.
      */
     getBillingPortal(): Promise<BillingPortalResponse>;
     /** List the caller's Pipelex API keys — `GET /v1/pipelex-api-keys`. */
     listPipelexApiKeys(): Promise<PipelexApiKeyList>;
     /**
      * Mint a Pipelex API key — `POST /v1/pipelex-api-keys`. The plaintext
-     * `api_key` is returned ONCE. A 409 `pipelex_api_key_limit_reached`
+     * `api_key` is returned ONCE. A 409 `pipelex.billing.plan_limit`
      * (`ApiResponseError.code`) means the per-account key limit is hit.
      */
     createPipelexApiKey(input: {
@@ -1609,8 +1645,9 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
     /**
      * Upload a base64 file — `POST /v1/upload`, answering the file's `uri`, the `filename` as sent
      * and the `file_id` of its record. An answer with no non-empty string `uri` names no
-     * stored file, so it is an answer the SDK cannot read: an `ApiResponseError`, `runtime` and
-     * not retryable, which `uploadFile` wraps as an `UploadTransportError` with code `unexpected`.
+     * stored file, so it is an answer the SDK cannot read: an `ApiResponseError` whose problem is
+     * `client.response_unreadable`, which `uploadFile` wraps as an `UploadTransportError` with the
+     * reason `unexpected`.
      */
     upload(input: UploadInput): Promise<UploadedFile>;
     /**
@@ -1631,9 +1668,9 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * target is short-lived and a bearer capability, so keep it out of logs. The route
      * never replays a grant: ask again for a new one rather than retrying; with a
      * `sha256`, a new grant answers the same file record. A declared `size` over the cap
-     * is a `413` `ApiResponseError` (`code` `payload_too_large`), a malformed `sha256` and
-     * a `size` other than the one the organization holds those bytes at are a `422`, and a
-     * deployment without the route answers a `404`. See `docs/input-preparation.md`.
+     * is a `413` `ApiResponseError` (`code` `request.too_large`), a malformed `sha256` and
+     * a `size` other than the one the organization holds those bytes at are a `422`
+     * (`request.invalid`), and a deployment without the route answers a `404`. See `docs/input-preparation.md`.
      */
     requestUploadGrant(input: UploadGrantInput, options?: {
         signal?: AbortSignal;
@@ -1699,7 +1736,7 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      *
      * Throws `ApiResponseError`: `400` for a date bound that is not an instant with an offset, a
      * range whose start is after its end, or a cursor of another list or other filters; `404`
-     * `run_not_found` for a run that is not the organization's; `422` for a `limit` outside 1 to
+     * `run.not_found` for a run that is not the organization's; `422` for a `limit` outside 1 to
      * 200, an unknown `kind`, more than 100 values of `format` or `mediaType`, or an id that cannot
      * be one. A page whose `items` is not an array or whose `next_cursor` is neither a string nor
      * `null` is an `ApiResponseError` of an answer the SDK cannot read. See `docs/files.md`.
@@ -1736,10 +1773,11 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `stored` when its bytes are there.
      *
      * Throws `RequestArgumentError` for a file id that is empty, `.` or `..`, or holds a lone
-     * surrogate, before any request. Throws `ApiResponseError`: `404` `not_found` for a file that is
-     * not the organization's; `422` for a `usesLimit` outside 1 to 200 or an id that cannot be one.
-     * An answer that is not an object, or whose `uses` is not a page of `items` and `next_cursor`, is
-     * an answer the SDK cannot read, thrown as an `ApiResponseError` too. See `docs/files.md`.
+     * surrogate, before any request. Throws `ApiResponseError`: `404` `pipelex.storage.not_found` for
+     * a file that is not the organization's; `422` for a `usesLimit` outside 1 to 200 or an id that
+     * cannot be one. An answer that is not an object, or whose `uses` is not a page of `items` and
+     * `next_cursor`, is an answer the SDK cannot read, thrown as an `ApiResponseError` too. See
+     * `docs/files.md`.
      */
     getFile(fileId: string, query?: GetFileQuery): Promise<FileDetail>;
     /**
@@ -1754,10 +1792,10 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * kept records.
      *
      * Throws `RequestArgumentError` for a `uri` that is not a non-empty string, before any request.
-     * Throws `ApiResponseError`: `400` `invalid_storage_uri` for a malformed address, `403`
-     * `forbidden` for another organization's, `404` `run_not_found` for a run that is not the
-     * organization's, and `422` for an address over 512 characters. An answer whose `items` is not an
-     * array is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
+     * Throws `ApiResponseError`: `pipelex.storage.uri_invalid` for a malformed address, `403`
+     * `pipelex.org.mismatch` for another organization's, `404` `run.not_found` for a run that is not
+     * the organization's, and `422` for an address over 512 characters. An answer whose `items` is
+     * not an array is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
      */
     getFilesByUri(uri: string, options?: GetFilesByUriOptions): Promise<FileRecordList>;
     /**
@@ -1777,9 +1815,9 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      *
      * Sends `name` alone: the body is closed. Throws `RequestArgumentError` for a file id that is
      * empty, `.` or `..`, or holds a lone surrogate, and for a `name` that is not a string, before
-     * any request. Throws `ApiResponseError`: `403` `role_not_permitted` past the rule above; `404`
-     * `not_found` for a file that is not the organization's; `422` for a name over 512 characters or
-     * with nothing left once cleaned. An answer that is not an object is an answer the SDK cannot
+     * any request. Throws `ApiResponseError`: `403` `auth.forbidden` past the rule above; `404`
+     * `pipelex.storage.not_found` for a file that is not the organization's; `422` for a name over
+     * 512 characters or with nothing left once cleaned. An answer that is not an object is an answer the SDK cannot
      * read, thrown as an `ApiResponseError` too.
      */
     renameFile(fileId: string, input: FileRenameInput): Promise<FileRecord>;
@@ -1806,8 +1844,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * Sends each file as `{ file_id }` or `{ uri }` and nothing else: the body is closed. Throws
      * `RequestArgumentError` before any request when `files` is not a list, or one of its items does
      * not name exactly one of `file_id` and `uri` as a non-empty string. Throws `ApiResponseError`:
-     * `422` for more than 100 files, or an id or address longer than one can be; `500` `config` when
-     * the platform cannot sign at all. An answer that is not one item per requested file, each an
+     * `422` `request.invalid` for more than 100 files, or an id or address longer than one can be;
+     * `500` `pipelex.storage.not_configured` when the platform cannot sign at all. An answer that is not one item per requested file, each an
      * object with its `url` or its `error`, is an answer the SDK cannot read, thrown as an
      * `ApiResponseError` whose body hides every link.
      */
@@ -1830,18 +1868,18 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * list of non-empty strings, when `run_id` is not a non-empty string, and when `name` is not a
      * string. Throws `ApiResponseError`:
      *
-     * - `422` `file_archive_too_large` past a cap, at most 500 files or 2,000,000,000 bytes, whose
-     *   `problemDocument.limit` names it (`FileArchiveLimit`), so the person can be told how far over
-     *   the selection is;
-     * - `422` `validation_failed` for more than 1,000 ids listed, or an id longer than one can be;
-     * - `404` `not_found` for a file that is not the organization's, the `detail` naming up to five
-     *   of them, or a run whose files hold nothing stored to zip; `404` `run_not_found` for a run
-     *   that is not the organization's;
-     * - `409` `conflict`: an `input` one, not retryable, for a selected file whose upload has not
-     *   finished; a `runtime` one, retryable, for a run whose files are not all recorded yet, which
-     *   the same request clears a few seconds after the run ends;
-     * - `503` `service_unavailable`, retryable, when the archive could not be queued: the same request
-     *   sent again asks for a new archive.
+     * - `422` `pipelex.files.archive_too_large` past a cap, at most 500 files or 2,000,000,000
+     *   bytes, whose problem's `limit` member names it (`FileArchiveLimit`), so the person can be told
+     *   how far over the selection is;
+     * - `422` `request.invalid` for more than 1,000 ids listed, or an id longer than one can be;
+     * - `404` `pipelex.storage.not_found` for a file that is not the organization's, the `detail`
+     *   naming up to five of them, or a run whose files hold nothing stored to zip; `404`
+     *   `run.not_found` for a run that is not the organization's;
+     * - `409` `run.not_finished`, `retry` `yes`, for a run whose files are not all recorded yet,
+     *   which the same request clears a few seconds after the run ends, and a `409` with `retry` `no`
+     *   for a selected file whose upload has not finished;
+     * - `503` `runtime.unavailable`, `retry` `yes`, when the archive could not be queued: the same
+     *   request sent again asks for a new archive.
      *
      * An answer that is not an archive, an object with a string `archive_id` and a known `state`, is
      * an answer the SDK cannot read, thrown as an `ApiResponseError` too.
@@ -1860,10 +1898,10 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * still `queued` or `building` an hour after it was asked for reads as `failed`.
      *
      * Throws `RequestArgumentError` for an archive id that is empty, `.` or `..`, or holds a lone
-     * surrogate, before any request. Throws `ApiResponseError`: `404` `not_found` for an archive that
-     * is not the organization's, never existed, or has expired, a day after `created_at`; `500` when
-     * the link cannot be signed. An answer that is not an archive is an answer the SDK cannot read,
-     * thrown as an `ApiResponseError` whose body hides the link.
+     * surrogate, before any request. Throws `ApiResponseError`: `404` `pipelex.storage.not_found` for
+     * an archive that is not the organization's, never existed, or has expired, a day after
+     * `created_at`; `500` when the link cannot be signed. An answer that is not an archive is an
+     * answer the SDK cannot read, thrown as an `ApiResponseError` whose body hides the link.
      */
     getFileArchive(archiveId: string): Promise<FileArchive>;
     /**
@@ -1894,14 +1932,15 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `expected_updated_at`, and nothing else: the body is closed, and a `null` token reads as not
      * given. Throws `RequestArgumentError` before any request for a `file_id` or a `path` that is not
      * a non-empty string, and an `expected_updated_at` that is not a string. Throws
-     * `ApiResponseError`: `403` `role_not_permitted` for a role that may not change methods; `404`
-     * for an unknown method or a file that is not the organization's; `409` `method_being_deleted`,
-     * `409` `method_update_conflict` for a stale `expected_updated_at`, and `409` `conflict` for a
-     * file whose upload has not finished or whose stored bytes do not match its record; `422`
-     * `invalid_method_files` for a path the draft cannot hold, such as `.env` or `../logo.png`, and
-     * `422` `method_tree_too_large` past the deployment's limits. An answer whose `blob` is neither
-     * arm's, or whose `file` or `method` is not an object, is an answer the SDK cannot read, thrown
-     * as an `ApiResponseError` too.
+     * `ApiResponseError`: `403` `auth.forbidden` for a role that may not change methods; `404`
+     * for an unknown method or a file that is not the organization's; `409` `pipelex.catalog.being_deleted`,
+     * `409` `pipelex.catalog.update_conflict` for a stale `expected_updated_at`, and `409` `conflict` for a
+     * file whose upload has not finished or whose stored bytes do not match its record; and `422`
+     * `method.package_invalid` for a path the draft cannot hold, such as `.env` or `../logo.png`,
+     * naming the path in its `params`, and past the deployment's limits, its `params` carrying
+     * `reason` `too_large` and the integer `limit`. An answer whose `blob` is neither arm's, or
+     * whose `file` or `method` is not an object, is an answer the SDK cannot read, thrown as an
+     * `ApiResponseError` too.
      */
     copyFileIntoDraft(methodId: string, input: DraftFileFromFileInput): Promise<DraftFileFromFileResult>;
     /**
@@ -1919,7 +1958,7 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `iterateRuns` does the latter for you.
      *
      * Each item is a `RunHistoryItem` — the id, status, timestamps, pipe and,
-     * for a failed run, its error report. The run's organization, creator,
+     * for a failed run, its own problem. The run's organization, creator,
      * method and workflow id are not on the list; `getRunDetail` returns them.
      *
      * `createdFrom` / `createdTo` are applied server-side as index key
@@ -1974,8 +2013,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * The whole record for one run — `GET /v1/runs/{id}`.
      *
      * The ONLY call that returns what the run actually executed and its
-     * `inputs`. Kept off the status read, which pollers hit every few seconds. A failed run's stored report, `error`, is checked field by
-     * field (see `RunErrorReport`).
+     * `inputs`. Kept off the status read, which pollers hit every few seconds. A failed run's problem, `error`, is kept when it is a
+     * problem document and read as `null` otherwise.
      *
      * Read with `parseExactJson`, so an integer past `Number.MAX_SAFE_INTEGER` in the inputs is a
      * `bigint` holding its exact digits, and the inputs passed back to `start` or saved as an
@@ -2032,19 +2071,21 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
  * Whether a request that failed `elapsedMs` after it was sent was cut off by the hosted gateway's
  * ~30-second limit on a request it waits on, rather than refused.
  *
- * It is when, after at least ~28 seconds, the failure is a `503` or `504` answer, or the client's
- * own time limit (`ApiUnreachableError` with the code `ABORT_TIMEOUT`). A fast `503` is the API
- * saying the request was not handled, and any other unreachable host is never the gateway's
- * cut-off, however long it took. The fetch API cannot say whether `ABORT_TIMEOUT` ran out before
+ * It is when, after at least ~28 seconds, the failure is a `503` or `504` answer whose body is no
+ * problem document, or the client's own time limit (`ApiUnreachableError` with the code
+ * `ABORT_TIMEOUT`). A fast `503` is the API saying the request was not handled, a problem document
+ * is the API's own answer however long it took, and any other unreachable host is never the
+ * gateway's cut-off. The fetch API cannot say whether `ABORT_TIMEOUT` ran out before
  * the connection was made, so it is read as the gateway's; with Node's own dispatcher it never
  * does past the threshold, since undici gives up a connection that does not come after ten
  * seconds (`UND_ERR_CONNECT_TIMEOUT`), the TLS handshake included. The Python SDK's
  * `is_gateway_cut_off` reads the same failures, its `ABORT_TIMEOUT` being httpx's read or write
  * timeout.
  *
- * The blocking `execute` turns such a failure into a `PipelineExecuteTimeoutError`. Whether a
- * failed `start` or `execute` may have started a run needs no timing: the error says it as
- * `runMayHaveStarted`, which reads every `503` but the platform's coded one as a run that may
- * have started, however quickly it came back.
+ * The blocking `execute` turns such a failure into a `PipelineExecuteTimeoutError`, for its
+ * message. Whether a failed `start` or `execute` may have started a run needs no timing: the
+ * error's problem says it, its `retry` being `outcome_unknown` for every answer from the edge
+ * that is no problem document past a `5xx` but a `501`, however quickly it came back, while a
+ * `503` problem document from the platform says as received whether it started one.
  */
 export declare function isGatewayCutOff(error: unknown, elapsedMs: number): boolean;