@pipelex/sdk 0.52.0 → 0.53.0

package/dist/errors.d.ts

@@ -1,106 +1,67 @@
 /**
  * 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, and `runMayHaveStarted`, which says
- * whether a failed start or execute may still have started a run. The one exported error outside
- * the family, `CodegenLockError`, declares the verdict's two members itself.
- */
-import { PipelineRequestError } from "mthds/protocol";
-import type { AnswerHeaders, Problem } from "mthds/protocol";
-import type { ValidationErrorItem } from "./models.js";
+ * errors `PipelexApiClient` raises. Every one derives from `PipelexRequestError`, itself the MTHDS
+ * standard's `ProblemError` (re-exported from `mthds/protocol`), and so carries its failure as a
+ * problem document: the runtime's own when it answered with one, and otherwise the problem the SDK
+ * builds for a failure it detects itself, under a registered code. A program branches on `code`,
+ * and on `domain`, `retry` and `nextStep` when it handles several codes alike; the rest of the
+ * problem (`params`, `location`, `errors`, `pipeline_run_id`, `request_id` and any member the
+ * runtime added) is read off `problem`. The Python twin, `pipelex-sdk`, builds the same code for
+ * every failure, which the shared case file `tests/fixtures/sdk-problems.json` pins in both suites.
+ *
+ * The exported errors outside the family, `CodegenLockError` and `ExactJsonUnsupportedError`, are
+ * `ProblemError`s too.
+ */
+import { ProblemError } from "mthds/protocol";
+import type { AnswerHeaders, Problem, ProblemItem } from "mthds/protocol";
 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 { ProblemError };
 /**
- * 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.
+ * The problem of an argument refused before any request left: `client.argument_invalid`, naming
+ * the argument and why it was refused, as an identifier (`not_a_string`, `mutually_exclusive`, …).
  */
-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;
+export declare function argumentInvalidProblem(argument: string, reason: string): Problem;
 /**
- * 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, and on a request that may create a run, that it cannot
- * start a second one: a failed `start` or `execute` that may still have started a run (an error
- * whose `runMayHaveStarted` is true) is never retryable, whatever the server or the fallback table
- * says, since asking again could pay for the run twice. Everywhere else it says nothing about
- * whether the first attempt had an effect.
+ * The problem of an answer the SDK cannot use as the route's answer: `client.response_unreadable`,
+ * naming its status, and the run it is about as its member when there is one.
  */
-export interface ErrorVerdict {
-    readonly retryable: boolean;
-    readonly errorDomain: ErrorDomain;
-}
+export declare function responseUnreadableProblem(status: number, runId?: string): Problem;
+/** The problem the standard reads from an answer's status alone, as for a body that is no problem document. */
+export declare function statusProblem(status: number): Problem;
 /**
- * The base of every error this SDK raises over a request, carrying the verdict as two readonly
- * own properties, `retryable` and `errorDomain`, and a third, `runMayHaveStarted`. 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.
- *
- * `runMayHaveStarted` is false unless the subclass passes it: only `ApiUnreachableError` and
- * `ApiResponseError` built for a request that may create a run, and `PipelineExecuteTimeoutError`,
- * ever carry it as true, and when they do, `retryable` is false whatever the verdict passed.
- *
- * 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, and
- * `runMayHaveStartedOf` for the third member.
- */
-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;
-    /**
-     * Whether the failed request may still have started a run whose id never reached the caller:
-     * a `start` or an `execute` (and so `startAndWaitForResult`'s start, or the blocking execute it
-     * falls back to) that failed in a way that does not prove the server started nothing. When it
-     * is true, `retryable` is false: look the run up in the run history before starting it again.
-     * False for every other request, a wait on a run already named included. Always decided.
-     */
-    readonly runMayHaveStarted: boolean;
-    constructor(message: string, verdict: ErrorVerdict, options?: {
-        cause?: unknown;
-        runMayHaveStarted?: boolean;
-    });
-}
+ * Whether a storage answer's `status` refuses the request for its timing or fails in a way a later
+ * attempt can pass: a `408`, a `429`, or a `5xx` other than `501`.
+ */
+export declare function isTransientStorageStatus(status: number): boolean;
 /**
- * The verdict of anything a `catch` holds: the pair from an `Error` carrying a boolean
- * `retryable` and a known `errorDomain`, else the verdict of the MTHDS standard's problem an
- * `Error` carries as `problem`, 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, and of a consumer's own subclass. An error of the
- * standard's own client (`mthds`) carries its verdict on its problem, as `domain` and `retry` in
- * the standard's vocabulary, and reads as that problem's verdict in this SDK's
- * (`problemVerdict`), whatever the runner's body held beside it. `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.
+ * The problem of a storage answer the SDK reads by its status, storage answering no problem
+ * document: `runtime.unavailable` for a transient status ({@link isTransientStorageStatus}), so
+ * that asking again can succeed; `runtime.unsupported` for a `501`, storage not implementing the
+ * request it was sent; and `client.response_unreadable` naming the status otherwise, an answer the
+ * SDK has no reading for.
  */
-export declare function errorVerdictOf(err: unknown): ErrorVerdict | undefined;
+export declare function storageStatusProblem(status: number): Problem;
 /**
- * Whether anything a `catch` holds is a failed run start that may still have started a run: true
- * only for an `Error` carrying `runMayHaveStarted` as `true`.
+ * The base of every error this SDK raises over a request, carrying the failure as `problem`.
+ *
+ * It refines the standard's `ProblemError`, so every getter that reads the problem is there:
+ * `code`, the member a program branches on; `domain`, who must act (`input`, `method`,
+ * `account`, `operator` or `runtime`); `retry`, whether sending the same request again can succeed
+ * (`yes`, `no`, or `outcome_unknown` where a run may already exist and must be read, never started
+ * again); `nextStep`, what to do; `retryAfter`, the seconds to wait before a repeat when the
+ * problem gives them; and `requestId`, the id to hand to support. `instanceof ProblemError` and
+ * `instanceof PipelineRequestError` match every SDK error, as does `mthds`'s `isProblemError`.
  *
- * The check is structural, as `errorVerdictOf`'s is, so it reads an error raised by another copy
- * of this SDK installed beside this one. Anything else is false: an error of a request that
- * cannot start a run, an `mthds` error, which the standard's client never raises over a start of
- * this SDK, and a value that is not an `Error`.
+ * The message is the SDK's own sentence, as it always was, rather than the problem's: the problem's
+ * `detail` and `next_step.detail` are on `problem` for whoever renders them. Its subclasses are
+ * meant to be raised, never this class itself.
  */
-export declare function runMayHaveStartedOf(err: unknown): boolean;
+export declare abstract class PipelexRequestError extends ProblemError {
+    constructor(message: string, problem: Problem, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * 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
@@ -112,16 +73,17 @@ export declare function runMayHaveStartedOf(err: unknown): boolean;
  * to 255 visible ASCII characters, 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`.
+ * Its problem is `client.argument_invalid`, unless `options.problem` gives another: the client
+ * gives `client.not_configured` naming `base_url` for a base URL that is not host-only, since it
+ * typically comes from `PIPELEX_BASE_URL`. One built from a message alone names the argument
+ * `arguments`, for the reason `unspecified`. 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;
+        problem?: Problem;
     });
 }
 /**
@@ -130,20 +92,22 @@ export declare class RequestArgumentError extends PipelexRequestError {
  * 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.
+ * Its problem is the one `options.problem` gives: the SDK's own subclasses state theirs, a direct
+ * raise gives `client.argument_invalid` for an argument refused or the wrapped error's for a
+ * refusal the API answered, and a consumer's subclass, such as a form reporting a missing input in
+ * its own words, may give any. One built with none, from a message alone, carries
+ * `client.argument_invalid` naming `inputs`, for the reason `unspecified`.
  */
 export declare class InputPreparationError extends PipelexRequestError {
     constructor(message: string, options?: {
         cause?: unknown;
-        verdict?: ErrorVerdict;
+        problem?: Problem;
     });
 }
 /**
  * A local asset could not be turned into bytes: a missing or unreadable path, or
  * a path string in a non-Node runtime (path strings are Node-only). `source` is
- * the offending path.
+ * the offending path. Its problem is `input.file_unreadable`, naming the path.
  */
 export declare class InvalidLocalSourceError extends InputPreparationError {
     readonly source: string;
@@ -162,7 +126,8 @@ export declare class InvalidLocalSourceError extends InputPreparationError {
  * As on `UploadNotAllowedError`, `inputName` is the input the value belongs to and `inputPath`
  * where it sits inside that input (`report.attachments[1]`, or the name alone for a top-level
  * file). The message names that path and describes the value by its kind, never by its content,
- * since the value is the caller's data.
+ * since the value is the caller's data. Its problem is `input.invalid`, naming the input and the
+ * path inside it.
  */
 export declare class InvalidInputValueError extends InputPreparationError {
     readonly inputName: string;
@@ -188,8 +153,9 @@ export type UploadNotAllowedKind = "local_path" | "data_url" | "bytes";
  * reads a file of its own because the caller named it. `inputName` is the input the value belongs
  * to, `inputPath` where it sits inside that input (`report.attachments[1]`, or the name alone for a
  * top-level file), and `valueKind` what it is. The value itself is neither in the message nor on
- * the error, since it is the caller's data. Its verdict is `input`, not retryable: the caller must
- * pass an `http(s)` URL or a `pipelex-storage://` reference instead.
+ * the error, since it is the caller's data. Its problem is `client.argument_invalid`, naming the
+ * input's path and the value's kind as the reason: the caller must pass an `http(s)` URL or a
+ * `pipelex-storage://` reference instead.
  */
 export declare class UploadNotAllowedError extends InputPreparationError {
     readonly inputName: string;
@@ -205,16 +171,15 @@ export declare class UploadNotAllowedError extends InputPreparationError {
 }
 /**
  * The pipe I/O answer said the method does not load (`is_valid: false`), so its signature cannot
- * be read and no input can be prepared: the method, not the inputs, must change.
- * `validationErrors` holds the answer's items, each kept when it carries a string `category` and
- * `message`, possibly none; `serverMessage` is the answer's own `message` when it is a string. The
- * error's message names the first item's message, else the answer's own.
+ * be read and no input can be prepared: the method, not the inputs, must change. Its problem is
+ * `method.invalid`, whose `errors` are the answer's problem items, each read member by member
+ * (see `readProblemItems`), possibly none; `serverMessage` is the answer's own `message` when it is
+ * a string. The error's message names the first item's `detail`, else the answer's own message.
  */
 export declare class MethodLoadError extends InputPreparationError {
-    readonly validationErrors: ValidationErrorItem[];
     readonly serverMessage: string | undefined;
     constructor(message: string, details: {
-        validationErrors: ValidationErrorItem[];
+        errors: ProblemItem[];
         serverMessage?: string | undefined;
     }, options?: {
         cause?: unknown;
@@ -234,7 +199,7 @@ export declare class MethodLoadError extends InputPreparationError {
  * 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";
+export type RejectedAssetReason = "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. A storage
@@ -242,25 +207,29 @@ export type RejectedAssetCode = "too_large" | "grant_used" | "grant_expired" | "
  * 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,
+ * `status` locate it, and `reason` says why: the SDK sets it on every one it raises,
  * so it is undefined only on one a caller constructs without it.
+ *
+ * Its problem is the refusal's as the API answered it, which `uploadFile` passes, and otherwise
+ * the one the standard reads from `status` alone, storage answering no problem document.
  */
 export declare class RejectedAssetError extends InputPreparationError {
     readonly filename: string;
     readonly status: number;
-    readonly code: RejectedAssetCode | undefined;
+    readonly reason: RejectedAssetReason | undefined;
     constructor(message: string, filename: string, status: number, options?: {
         cause?: unknown;
-        code?: RejectedAssetCode;
+        reason?: RejectedAssetReason;
+        problem?: Problem;
     });
 }
 /**
  * The configured deployment does not support upload (no `/v1/upload` route, seen
  * as a `404` other than a test file's unknown method, which is a {@link TestFileRefusedError}).
  * Upload is a hosted Pipelex-product capability even though the SDK
- * can be pointed at other base URLs. Its verdict is `config`, not retryable: the base URL
- * must point at a deployment that serves upload. `filename` is the file whose upload met it, as
- * `uploadFile` sent it.
+ * can be pointed at other base URLs. Its problem is `runtime.unsupported`, naming file upload as
+ * the capability the deployment lacks: the base URL must point at a deployment that serves
+ * upload. `filename` is the file whose upload met it, as `uploadFile` sent it.
  */
 export declare class UnsupportedUploadCapabilityError extends InputPreparationError {
     readonly filename: string | undefined;
@@ -271,8 +240,11 @@ export declare class UnsupportedUploadCapabilityError extends InputPreparationEr
 }
 /**
  * Upload was not authorized — a `401`, or a `403` from the upload route other than a test file's
- * `role_not_permitted`, which is a {@link TestFileRefusedError}. Its verdict is `config`, not
- * retryable: the credential must change. `filename` is the file whose upload was refused, as
+ * refused role, which is a {@link TestFileRefusedError}. Its problem is the server's own when the
+ * wrapped error, which `uploadFile` passes as `cause`, answered a problem document. Otherwise it is
+ * `auth.invalid_credential` when the request carried a credential and `auth.missing_credential`
+ * when it carried none, as `options.credentialSent` says, and the wrapped error's reading of the
+ * status when the caller does not say. `filename` is the file whose upload was refused, as
  * `uploadFile` sent it.
  */
 export declare class UploadAuthenticationError extends InputPreparationError {
@@ -281,6 +253,7 @@ export declare class UploadAuthenticationError extends InputPreparationError {
     constructor(message: string, status: number, options?: {
         cause?: unknown;
         filename?: string;
+        credentialSent?: boolean;
     });
 }
 /**
@@ -288,36 +261,37 @@ export declare class UploadAuthenticationError extends InputPreparationError {
  * than on the message. A test file is a statement about a method, so the route holds it to what
  * changing that method takes:
  *
- * - `role_not_permitted` — a `403` coded `role_not_permitted`: the caller's role in the
- *   organization may not change methods, as a runner's may not. Upload the file as `uploaded`,
- *   or with the credential of a member who may change methods.
- * - `method_not_found` — a `404` coded `not_found`: the method the test file names is not one of
- *   the organization's.
- * - `method_being_deleted` — a `409` coded `method_being_deleted`: the method the test file names
- *   is being erased.
+ * - `role_not_permitted` — the caller's role in the organization may not change methods, as a
+ *   runner's may not (the route's `auth.forbidden`). Upload the file as `uploaded`, or with the
+ *   credential of a member who may change methods.
+ * - `method_not_found` — the method the test file names is not one of the organization's (the
+ *   route's `pipelex.catalog.not_found`).
+ * - `method_being_deleted` — the method the test file names is being erased (the route's
+ *   `pipelex.catalog.being_deleted`).
  */
-export type TestFileRefusalCode = "role_not_permitted" | "method_not_found" | "method_being_deleted";
+export type TestFileRefusalReason = "role_not_permitted" | "method_not_found" | "method_being_deleted";
 /**
  * The upload route refused a test file (`kind: "test"`) for what it claims, never for its bytes:
  * the caller's role may not change methods, or the method it names is unknown or being erased.
- * `code` says which; the SDK sets it on every one it raises, so it is undefined only on one a
+ * `reason` 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, `filename` the file `uploadFile` was
  * sending and `methodId` the method it named, and the wrapped `ApiResponseError` is reachable via
  * `cause`.
  *
- * Its verdict is the wrapped error's when `cause` carries one, the server's own; otherwise `code`
- * decides: `role_not_permitted` is `config`, since the caller's role must change, and the other
- * two are `input`, since the request must name another method; none is retryable.
+ * Its problem is the wrapped error's when `cause` carries one, the server's own. Otherwise it is
+ * `auth.forbidden` for `role_not_permitted`, naming a role that may change methods as the
+ * requirement, and `client.argument_invalid` naming `method_id` for the other two, the reason as
+ * the reason.
  */
 export declare class TestFileRefusedError extends InputPreparationError {
     readonly status: number | undefined;
-    readonly code: TestFileRefusalCode | undefined;
+    readonly reason: TestFileRefusalReason | undefined;
     readonly filename: string | undefined;
     readonly methodId: string | undefined;
     constructor(message: string, options?: {
         cause?: unknown;
         status?: number;
-        code?: TestFileRefusalCode;
+        reason?: TestFileRefusalReason;
         filename?: string;
         methodId?: string;
     });
@@ -345,44 +319,52 @@ export declare class TestFileRefusedError extends InputPreparationError {
  *   `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";
+export type UploadTransportReason = "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,
  * 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
+ * unexpected `upload()` failure. `reason` 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`, and `filename` is the file it was sending; `uploadWithGrant` wraps no response,
  * because storage's error body can echo the grant's credential, and leaves `filename` undefined.
  *
- * 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 hashless 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.
+ * Its problem is `options.problem` when given, else the wrapped error's when `cause` carries one:
+ * `uploadFile` wraps the `ApiResponseError` or `ApiUnreachableError` the client's `upload()`
+ * threw. Otherwise — always the case from `uploadWithGrant`, which wraps no response — `reason`
+ * decides (`uploadTransportProblem`).
  */
 export declare class UploadTransportError extends InputPreparationError {
     readonly status: number | undefined;
-    readonly code: UploadTransportCode | undefined;
+    readonly reason: UploadTransportReason | undefined;
     readonly filename: string | undefined;
     constructor(message: string, options?: {
         cause?: unknown;
         status?: number;
-        code?: UploadTransportCode;
+        reason?: UploadTransportReason;
         filename?: string;
+        problem?: Problem;
     });
 }
+/**
+ * The problem of an upload transport failure that wraps no error carrying one, by its reason and
+ * the status storage answered:
+ *
+ * - `timeout`, `unreachable`, `storage_timeout` and `conflict` are `runtime.unavailable`: storage,
+ *   a service the upload depends on, did not take the file, and a later attempt can (the SDK's
+ *   own raise sites give `client.timeout` and `client.unreachable` instead, naming the limit and
+ *   the host);
+ * - `server_error`, `unexpected` and no reason at all are `storageStatusProblem`'s reading of the
+ *   status: `runtime.unavailable` for a `408`, a `429` or a `5xx` other than `501`,
+ *   `runtime.unsupported` for a `501`, `client.response_unreadable` for any other status; a
+ *   `server_error` with no status is `runtime.unavailable`, and the others `runtime.unexpected`;
+ * - `redirected` is `runtime.misconfigured`: storage redirecting a signed upload is a fault of the
+ *   deployment;
+ * - `invalid_grant_url` is `client.response_unreadable`: the grant the API answered is unusable.
+ */
+export declare function uploadTransportProblem(reason: UploadTransportReason | undefined, status: number | undefined): Problem;
 /**
  * Base class for the failures the artifact operations raise on their own
  * (`fetchArtifact` / `downloadArtifacts`) — the download twin of
@@ -393,15 +375,16 @@ export declare class UploadTransportError extends InputPreparationError {
  * 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).
+ * Its problem is `options.problem`, else `runtime.unexpected`: the SDK gives
+ * `client.argument_invalid` where it refuses an argument (a `scope`, a bound, a location),
+ * `runtime.unsupported` for a runtime with no filesystem, `client.write_failed` for a directory
+ * that cannot be created, and `client.response_unreadable` for a resolution that answered the
+ * wrong count of items.
  */
 export declare class ArtifactOperationError extends PipelexRequestError {
     constructor(message: string, options?: {
         cause?: unknown;
-        verdict?: ErrorVerdict;
+        problem?: Problem;
     });
 }
 /**
@@ -409,7 +392,7 @@ export declare class ArtifactOperationError extends PipelexRequestError {
  * results: `main_stuff` or `working_memory` is `null`, or the key is missing
  * from the body altogether. Distinct from an empty walk over a present scope,
  * which is a produced verdict with no artifacts. `scope` names the scope,
- * `runId` the run.
+ * `runId` the run. Its problem is `client.response_unreadable`, naming the run.
  */
 export declare class ScopeUnavailableError extends ArtifactOperationError {
     readonly scope: ArtifactScope;
@@ -420,31 +403,43 @@ export declare class ScopeUnavailableError extends ArtifactOperationError {
 }
 /**
  * One reference could not be turned into a bounded response by `fetchArtifact`.
- * `code` says why, in a closed vocabulary the download verdict shares for its
- * per-item errors: the resolve route's own per-reference codes
+ * `reason` says why, in a closed vocabulary the download verdict shares for its
+ * per-item errors: the resolve route's own per-reference reasons
  * (`invalid_storage_uri`, `forbidden`), then the fetch boundary's —
  * `unsupported_url`, `plain_http_refused`, `redirect_refused`, `store_refused`
  * (a 401/403 from the object store), `not_found` (404/410), `store_error`
- * (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.
+ * (any other non-2xx), `too_large`, `timeout`, `network`, and `unknown` for a failure the SDK
+ * cannot place. `status` is the store's HTTP status when one was received. `downloadArtifacts`
+ * never lets this escape: it becomes the item's `error`.
+ *
+ * Its problem is `options.problem` when given, else follows `reason` and `status`
+ * (`artifactFetchProblem`). The SDK gives `client.download_limit_exceeded` naming the cap for
+ * `too_large`, `client.timeout` naming the budget for `timeout`, and `client.unreachable` naming
+ * the store's origin for `network`.
  */
 export declare class ArtifactFetchError extends ArtifactOperationError {
     readonly uri: string;
-    readonly code: string;
+    readonly reason: string;
     readonly status: number | undefined;
-    constructor(message: string, uri: string, code: string, status?: number, options?: {
+    constructor(message: string, uri: string, reason: string, status?: number, options?: {
         cause?: unknown;
+        problem?: Problem;
     });
 }
+/**
+ * The problem of one reference's fetch failure that its raise site states none for, by its reason
+ * and the store's status: `input.reference_not_found` naming the reference for
+ * `invalid_storage_uri`, `forbidden` and `not_found`; `client.link_refused` for
+ * `unsupported_url`, `plain_http_refused` and `redirect_refused`; for `store_error` and
+ * `store_refused`, the object store failing or refusing a link the platform has just signed,
+ * `storageStatusProblem`'s reading of the store's status (`runtime.unavailable` for a `408`, a
+ * `429` or a `5xx` other than `501`, `runtime.unsupported` for a `501`, and
+ * `client.response_unreadable` naming any other status, a `401` or a `403` included), and
+ * `runtime.unavailable` when no status is known; `runtime.unavailable` for `timeout` and
+ * `network`; and `runtime.unexpected` otherwise, `unknown` and a reason this version does not know
+ * included.
+ */
+export declare function artifactFetchProblem(reason: string, uri: string, status?: number): Problem;
 /**
  * The resolve route refused the caller's credential (`401` / `403`) during a
  * `downloadArtifacts` call. No further reference can be resolved with it, so
@@ -452,14 +447,17 @@ export declare class ArtifactFetchError extends ArtifactOperationError {
  * 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`. (`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.)
+ * error's own problem.) Its problem is the server's own when the wrapped error answered a problem
+ * document; otherwise `auth.invalid_credential`, or `auth.missing_credential` when
+ * `options.credentialSent` says the request carried no credential, and the wrapped error's reading
+ * of the status when the caller does not say.
  */
 export declare class ArtifactAuthenticationError extends ArtifactOperationError {
     readonly status: number;
     readonly verdict: DownloadArtifactsResult;
     constructor(message: string, status: number, verdict: DownloadArtifactsResult, options?: {
         cause?: unknown;
+        credentialSent?: boolean;
     });
 }
 /** Which way a file of a method's tree was moving when its transfer failed. */
@@ -474,7 +472,7 @@ export type MethodFileTransferOperation = "upload" | "download";
  * - `mismatch`: a download's bytes are not the file the listing names, another size or another
  *   SHA-256.
  */
-export type MethodFileTransferCode = "unreachable" | "storage_error" | "refused" | "mismatch";
+export type MethodFileTransferReason = "unreachable" | "storage_error" | "refused" | "mismatch";
 /**
  * A file of a method's tree that could not be moved between this machine and the platform's
  * storage: thrown by `createMethod` and `writeDraft` when a file the organization lacks could not
@@ -484,68 +482,72 @@ export type MethodFileTransferCode = "unreachable" | "storage_error" | "refused"
  * `writeMethodTree` when a saved file could not be downloaded through its link, or its bytes are
  * not the file the listing names.
  *
- * `operation` says which way the file was moving, `code` why it failed, `sha256` which bytes,
+ * `operation` says which way the file was moving, `reason` why it failed, `sha256` which bytes,
  * `path` the tree path when one is known, and `status` storage's HTTP status when it answered.
  * Neither the message nor any member carries the link, whose query is a bearer credential, nor
  * storage's error body, which can echo the signed request, and it keeps no `cause`, since the
  * failure fetch throws can quote the URL.
  *
- * Its domain is always `runtime`, since neither the call nor the environment is at fault:
- * `unreachable`, `storage_error` and `mismatch` are retryable, since the same transfer can succeed
- * later, and `refused` is not. A download refused for an expired link succeeds once the method is
- * read again, which serves fresh links. A code this version does not know is not retryable.
+ * Its problem follows `reason` (`methodFileTransferProblem`): `unreachable` and `storage_error`
+ * are `runtime.unavailable`, since the same transfer can succeed later; `refused` is
+ * `storageStatusProblem`'s reading of storage's status (`client.response_unreadable` naming it, or
+ * `runtime.unsupported` for a `501`), a download refused for an expired link succeeding once the
+ * method is read again, which serves fresh links; and `mismatch` is `client.response_unreadable`.
  */
 export declare class MethodFileTransferError extends PipelexRequestError {
     readonly operation: MethodFileTransferOperation;
-    readonly code: MethodFileTransferCode;
+    readonly reason: MethodFileTransferReason;
     readonly sha256: string | undefined;
     readonly path: string | undefined;
     readonly status: number | undefined;
     constructor(message: string, details: {
         operation: MethodFileTransferOperation;
-        code: MethodFileTransferCode;
+        reason: MethodFileTransferReason;
         sha256?: string;
         path?: string;
         status?: number;
     });
 }
+/** The problem of a failed transfer of a method's file, by its reason and storage's status. */
+export declare function methodFileTransferProblem(reason: MethodFileTransferReason, status: number | undefined): Problem;
 /**
  * Thrown when the Pipelex API host cannot be reached at all (DNS failure,
  * connection refused, TLS handshake failure, request timeout). The HTTP
  * exchange never produced a response — distinguish from `ApiResponseError`,
- * which represents a non-2xx response that did come back.
+ * which represents a response that did come back, a body that arrived and could not be decoded
+ * included.
  *
- * `code` is the underlying network error code when available
+ * `networkCode` 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.
- *
- * On a request that may create a run (`options.mayStartRun`, which the client sets on `start` and
- * `execute`), `runMayHaveStarted` is true unless `cause`, the failure fetch threw, proves the
- * request never left: the name lookup, the connection or the TLS handshake failed. A reset, a time
- * limit or a body that could not be decoded proves nothing, so the run may have started and the
- * error is not retryable.
+ * Its problem is the transport's: `client.timeout`, naming the time limit, for the SDK's own time
+ * limit (`ABORT_TIMEOUT`) when the client gives it as `options.timeoutMs`, and
+ * `client.unreachable`, naming the base URL, otherwise. Both have `retry` `yes`. On a request that
+ * may create a run (`options.mayStartRun`, which the client sets on `start` and `execute`), it is
+ * `client.outcome_unknown` instead, whose `retry` is `outcome_unknown`, unless `cause`, the failure
+ * fetch threw, proves the request never left: the name lookup, the connection or the TLS handshake
+ * failed. A reset or a time limit proves nothing, so the run may have started.
  */
 export declare class ApiUnreachableError extends PipelexRequestError {
     readonly apiUrl: string;
-    readonly code: string | undefined;
-    constructor(message: string, apiUrl: string, code: string | undefined, options?: {
+    readonly networkCode: string | undefined;
+    constructor(message: string, apiUrl: string, networkCode: string | undefined, options?: {
         cause?: unknown;
         mayStartRun?: boolean;
+        timeoutMs?: number;
     });
 }
+/** The SDK's own time limit ran out while the request was sent or answered. */
+export declare const ABORT_TIMEOUT = "ABORT_TIMEOUT";
 /**
  * Thrown when the blocking `execute` (`POST /v1/execute`) is killed by the
  * 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. `runMayHaveStarted` is always true: the gateway gave up on
- * the request, and the run it carried goes on without its id reaching the caller.
+ * Its problem is `client.outcome_unknown`: the gateway gave up on the request, and the run it
+ * carried may go on without its id reaching the caller, so it is looked up in the run history
+ * rather than sent again, and the next one is started and polled.
  */
 export declare class PipelineExecuteTimeoutError extends PipelexRequestError {
     readonly elapsedMs: number;
@@ -553,49 +555,36 @@ export declare class PipelineExecuteTimeoutError extends PipelexRequestError {
         cause?: unknown;
     });
 }
+/**
+ * The problem of a run that ended without success, `run.failed`, naming the run and its terminal
+ * status, with the run's own problem nested as `run_error` when there is one.
+ */
+export declare function runFailedProblem(runId: string, status: RunStatus, runError?: Problem | null): Problem;
 /**
  * Thrown when a run reaches a terminal state that is not `COMPLETED` (`FAILED`, `CANCELLED`,
  * `TERMINATED`, `TIMED_OUT`) — by `waitForResult`, `startAndWaitForResult` and the artifact
  * download when the platform answers the results read with HTTP 409. (`getRunResult` returns
  * the same facts as its `failed` arm instead of throwing.)
  *
- * - `status` is the run's terminal status, read from the problem's `run_status` member, or from
- *   its `detail` sentence on a platform that predates the member.
- * - `error` is the run's stored error report as the platform serves it, typed whole as
- *   `RunErrorReport`: the runner's `error_type`, `message`, `title`, `type_uri`, `error_domain`,
- *   `error_category`, `retryable`, `user_action`, `provider_metadata`, `caller_facing_message`,
- *   `validation_errors` and anything newer through its index signature. Branch on
- *   `error.error_domain`, `error.type_uri` and `error.retryable`; show `error.user_action` as the
- *   next step. The platform serves the runner's STRICT projection, so `message` is the author's
- *   copy only when `caller_facing_message` is `true` and the placeholder
- *   `An internal error occurred.` otherwise, `user_action` comes only with caller-facing copy,
- *   `provider_metadata` keeps only `status_code` and `retry_after_seconds`, and `model`,
- *   `provider` and `migration` are absent; deciding what a person sees is still the consumer's.
- *   A run the platform ended or settled itself carries the caller-facing report the platform
- *   wrote, in the same shape. A cancelled, terminated or timed-out run carries a report when a
- *   completion callback carried one, and a timed-out run otherwise the platform's timeout report.
- *   `null` when the run ended with no stored report (one whose start failed, or one cancelled,
- *   terminated or given its status by hand with no completion callback carrying a report).
- * - The error's own `message` is the problem's `detail`, which names the status and then the
- *   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.
+ * - `problem` is `run.failed`, the results read's own problem document as the platform answered
+ *   it, or the one the SDK builds for a failed run it learned of otherwise. Its `retry` is `no`:
+ *   the run is over, and starting it again spends credit.
+ * - `runError` is the run's own problem, which `run.failed` nests as `run_error`: why the run did
+ *   not succeed, under its own code (`run.cancelled`, `run.timed_out`, a model's or a method's
+ *   code), with its own `domain`, `retry` and `next_step`. Branch on it to tell a run worth
+ *   starting again from one whose method or inputs must change. `undefined` when the run ended
+ *   with no problem stored.
+ * - `status` is the run's terminal status, `runId` the run.
  */
 export declare class RunFailedError extends PipelexRequestError {
     readonly runId: string;
     readonly status: RunStatus;
-    readonly error: RunErrorReport | null;
     constructor(message: string, runId: string, status: RunStatus, options?: {
         cause?: unknown;
-        error?: RunErrorReport | null;
+        problem?: Problem;
     });
+    /** The run's own problem, nested as `run_error`, when the run ended with one. */
+    get runError(): Problem | undefined;
 }
 /**
  * Thrown when a completed run cannot deliver its main stuff.
@@ -607,7 +596,8 @@ export declare class RunFailedError extends PipelexRequestError {
  * 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.
+ * Its problem is `client.response_unreadable`, naming the run: the API broke its own contract on a
+ * completed run.
  */
 export declare class MissingMainStuffError extends PipelexRequestError {
     readonly runId: string;
@@ -618,7 +608,8 @@ export declare class MissingMainStuffError extends PipelexRequestError {
  * 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.
+ * Its problem is `client.follow_failed`, naming the run: its `retry` is `outcome_unknown` and its
+ * step `read_run`, since the run goes on and is read by its id, never started again.
  */
 export declare class RunTimeoutError extends PipelexRequestError {
     readonly runId: string;
@@ -634,7 +625,8 @@ export declare class RunTimeoutError extends PipelexRequestError {
  * 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.
+ * Its problem is `client.follow_failed`, naming the run: its `retry` is `outcome_unknown`, since
+ * the run exists and executing again would pay for a second one, and its step `read_run`.
  */
 export declare class RunStillRunningError extends PipelexRequestError {
     readonly runId: string;
@@ -651,11 +643,12 @@ export declare class RunStillRunningError extends PipelexRequestError {
  * Run polling is a hosted-API extension, not part of the MTHDS Protocol: the
  * open-source `pipelex-api` runner executes methods but has no run store, so
  * 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.
+ * (the Pipelex Hosted API) serves status/results. A route the deployment lacks answers a `404`
+ * whose body is no problem document; a run the platform does not know answers a `404` problem
+ * document, `run.not_found`, which is an `ApiResponseError`.
  *
- * Its verdict is `config`, not retryable: the base URL points at a bare runner without the run
- * lifecycle.
+ * Its problem is `runtime.unsupported`, naming the durable run lifecycle as the capability the
+ * deployment lacks: the base URL points at a bare runner without it.
  */
 export declare class RunLifecycleUnavailableError extends PipelexRequestError {
     readonly apiUrl: string;
@@ -670,57 +663,52 @@ export declare class RunLifecycleUnavailableError extends PipelexRequestError {
  * The ceiling, `pageLimit` pages, sits far beyond any real catalog, run history or file list, 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.
+ * paging was introduced to remove. Its problem is `client.response_unreadable`.
  */
 export declare class PagingNotTerminatingError extends PipelexRequestError {
     readonly pageLimit: number;
     constructor(message: string, pageLimit: number);
 }
 /**
- * The platform codes a refusal about a stored method or one of its versions carries in
- * `ApiResponseError.code`, beside the generic `not_found`, `conflict` and `validation_failed`:
+ * The registry codes a refusal about a stored method or one of its versions carries, beside the
+ * core codes every route may answer:
  *
- * - `method_update_conflict` (`409`): the draft moved since the token a `writeDraft` or a
- *   `publishMethod` sent, so nothing was written or published. Read the method again and
- *   decide whether to keep its draft or overwrite it with the fresh token.
- * - `method_being_deleted` (`409`): the method's erasure has started, on every route that
+ * - `pipelex.catalog.update_conflict` (`409`): the draft moved since the token a `writeDraft` or a
+ *   `publishMethod` sent, so nothing was written or published. Read the method again and decide
+ *   whether to keep its draft or overwrite it with the fresh token.
+ * - `pipelex.catalog.being_deleted` (`409`): the method's erasure has started, on every route that
  *   addresses it.
- * - `method_not_published` (`409`): a bare `method_id` names the latest published version and
- *   the method was never published. Publish it, or address its draft as `mt_…@draft`.
- * - `method_version_not_found` (`404`): `mt_…@<n>`, or `getMethodVersion`, names a version
- *   the method never published. An unknown method is `not_found` instead.
- * - `organization_not_found` (`404`): the destination of a `copyMethod` is one the caller does
- *   not belong to, one still being set up, or one that does not exist, answered alike so the
- *   platform never says whether an organization exists. An unknown method is `not_found`.
- * - `method_copy_too_large` (`422`): a `copyMethod` past one of the copy's bounds on the stored
- *   files it copies, which `problemDocument.limit` names (`MethodCopyLimit`).
- *
- * `code` stays a `string`, since the platform adds codes; this type names the ones a method
- * caller branches on. Each is `input` and not retryable by the fallback verdict.
- */
-export type MethodErrorCode = "method_update_conflict" | "method_being_deleted" | "method_not_published" | "method_version_not_found" | "organization_not_found" | "method_copy_too_large";
-/**
- * The platform code a refusal about a request's `Idempotency-Key` carries in
- * `ApiResponseError.code`, beside the generic `conflict`:
- *
- * - `idempotency_key_in_use` (`409`): an earlier request under the same key and the same body is
- *   still being handled, or this one lost the key while it was handled, so nothing ran for this
- *   one. `runtime` and retryable: wait a few seconds (the answer carries a `Retry-After` header,
- *   which `ApiResponseError` does not expose) and send the same request again under the **same**
- *   key, which is answered with the earlier request's
- *   outcome once it is stored. A new key would run it a second time. On a `start`, its
- *   `runMayHaveStarted` is false: this request started nothing.
- *
- * The key's other refusal carries the generic `conflict` (`409`, `input`, not retryable): the
- * key was used before with a different body, or is bound to a run that has since been deleted.
- * Either way the request is sent again under a new key, with the original body for the first.
- */
-export type IdempotencyErrorCode = "idempotency_key_in_use";
-/**
- * The `code` of an `errors[]` entry when `updateOrganizationBranding` refuses a logo. The entry's
- * `field` is the slot, `square_logo` or `wide_logo`, and its `detail` the sentence to show under
- * that slot. The refusal itself is a `422` `validation_failed` naming both slots' failures at
- * once, one entry per broken rule, and writes nothing:
+ * - `pipelex.catalog.not_published` (`409`): a bare `method_id` names the latest published version
+ *   and the method was never published. Publish it, or address its draft as `mt_…@draft`.
+ * - `pipelex.catalog.not_found` (`404`): the method is not one of the organization's, or
+ *   `mt_…@<n>`, or `getMethodVersion`, names a version the method never published.
+ * - `pipelex.org.not_found` (`404`): the destination of a `copyMethod` is one the caller does not
+ *   belong to, one still being set up, or one that does not exist, answered alike so the platform
+ *   never says whether an organization exists. An unknown method is `pipelex.catalog.not_found`.
+ * - `pipelex.catalog.copy_too_large` (`422`): a `copyMethod` past one of the copy's bounds on the
+ *   stored files it copies, which the problem's `limit` member names (`MethodCopyLimit`).
+ *
+ * `code` stays a `string`, since the registry adds codes; this type names the ones a method caller
+ * branches on. Each has `domain` `input` and `retry` `no`.
+ */
+export type MethodErrorCode = "pipelex.catalog.update_conflict" | "pipelex.catalog.being_deleted" | "pipelex.catalog.not_published" | "pipelex.catalog.not_found" | "pipelex.org.not_found" | "pipelex.catalog.copy_too_large";
+/**
+ * The registry codes a refusal about a request's `Idempotency-Key` carries:
+ *
+ * - `request.idempotency_key_in_use` (`409`): an earlier request under the same key and the same
+ *   body is still being handled, so nothing ran for this one. Its `retry` is `yes`: wait the
+ *   problem's `retry_after` seconds (`ApiResponseError.retryAfter`) and send the same request
+ *   again under the **same** key, which is answered with the earlier request's outcome once it is
+ *   stored. A new key would run it a second time.
+ * - `request.idempotency_conflict` (`409`): the key was used before with a different body, or is
+ *   bound to a run that has since been deleted. Its `retry` is `no`: the request is sent again
+ *   under a new key, with the original body for the first.
+ */
+export type IdempotencyErrorCode = "request.idempotency_key_in_use" | "request.idempotency_conflict";
+/**
+ * The reason the platform gives a refused logo when `updateOrganizationBranding` refuses one. The
+ * refusal is one problem naming both slots' failures at once, one item of its `errors` per broken
+ * rule, and writes nothing:
  *
  * - `logo_not_an_upload`: the URI is neither a new upload of the organization nor the `uri` the
  *   slot already holds: a run's or a method's file, a stale `branding/` copy, or the other slot's
@@ -748,200 +736,55 @@ export type IdempotencyErrorCode = "idempotency_key_in_use";
  * - `logo_too_small`: a raster square logo under 128 px on a side.
  * - `logo_not_wide`: a wide logo less than one and a half times as wide as it is tall.
  * - `logo_too_short`: a raster wide logo under 64 px tall.
- *
- * Two refusals of a logo URI come before any file is read and name the slot the same way, with
- * the platform's own code: `400` `invalid_storage_uri` for a URI that is not a storage URI, and
- * `403` `forbidden` for another organization's file. A colour's refusal names its key instead
- * (`colors.action`, `dark_colors.header`) with pydantic's code. `FieldError.code` stays a
- * `string`, since the platform adds codes.
  */
 export type LogoRefusalCode = "logo_not_an_upload" | "logo_not_found" | "logo_too_large" | "logo_type_not_accepted" | "logo_unreadable" | "logo_active_content" | "logo_not_square" | "logo_too_small" | "logo_not_wide" | "logo_too_short";
-/**
- * The last constructor argument of `ApiResponseError`: the error's `cause`, the hosted problem
- * document's typed members, the decoded document whole, the answer's headers, and whether the
- * request that met the answer may create a run.
- */
+/** What an `ApiResponseError` is built from beside its message and the answer's facts. */
 export interface ApiResponseErrorOptions {
     cause?: unknown;
-    /** The hosted problem document's typed members, as the client parsed them. */
-    details?: ProblemDetails;
-    problemDocument?: Record<string, unknown>;
     /**
-     * The answer's headers, which the standard's reading takes a `Retry-After` from (see
-     * `ApiResponseError.problem`). The client passes them; a consumer building the error by hand
-     * may leave them out.
+     * The answer read as its problem. The client passes the one it read (`readHostedAnswer`); a
+     * consumer building the error by hand may leave it out, and the error then reads the answer
+     * itself, as the client would.
+     */
+    problem?: Problem;
+    /**
+     * The answer's headers, which a `Retry-After` and an `X-Request-ID` are read from. The client
+     * passes them; a consumer building the error by hand may leave them out.
      */
     headers?: AnswerHeaders;
     /**
-     * The request was a `start` or an `execute`, so the answer is read for whether it may have
-     * started a run (see `ApiResponseError.runMayHaveStarted`). The client sets it on those two
-     * routes alone; a consumer building the error by hand sets it to get the verdict the client
-     * would give.
+     * The request was a `start` or an `execute`, which creates a run, so an answer that is no
+     * problem document is read for whether the run may exist (`readHostedAnswer`). The client sets
+     * it on those two routes alone; it only matters when `problem` is left out.
      */
     mayStartRun?: boolean;
 }
 /**
  * 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 hosted problem member, what made it unreadable as `cause` (the parse failure,
- * or `mthds`'s refusal of the `python` field), the verdict the fallback gives a 2xx (`runtime`,
- * not retryable), and as `problem` the standard's reading of such an answer:
- * `client.response_unreadable`, or `client.outcome_unknown` on a request that may create a run.
- *
- * 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, 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 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.
- * - **A run that may have started.** On a `start` or an `execute`, `runMayHaveStarted` says
- *   whether the answer leaves a run possibly started without its id reaching the caller: any
- *   `2xx` the SDK could not read, a `408`, and every `5xx` but a `501` and the platform's `503`
- *   coded `pipeline_start_unavailable`, which says the runner was never reached. Then
- *   `retryable` is false, whatever the server sent: asking again could start a second run. A
- *   runner's own failure of a blocking execute reads the same, since the SDK cannot tell a run
- *   that ended from one that goes on, and its `retryable` stays readable on `problemDocument`.
- *   On every other route it is false.
- * - **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; they are the
- *   fields that mean the same on both surfaces.
- * - **The native codes.** `code` is the platform's own closed code (`conflict`, `not_found`,
- *   `pipelex_api_key_limit_reached`, …; `MethodErrorCode` names the method ones and
- *   `IdempotencyErrorCode` the idempotency key's) and `errorType` the runner's open exception
- *   class name. Each is finer than `errorDomain` and
- *   specific to the surface that emits it, and a client of that surface may branch on it: the
- *   platform's `type` is derived from its `code` one to one
- *   (`https://pipelex.com/errors/<code>`), so the two read the same answer. A problem the
- *   platform relays from the runner carries the runner's `type` and `errorType` and no `code`.
- * - **For a person.** `title` is the stable label of the error class, `serverMessage` the
- *   per-occurrence `detail`, `userAction` the advised next step, and `errorCategory`, `model`,
- *   `provider` and `providerMetadata` describe an inference failure.
- * - **For support.** `requestId` correlates the response with the server's logs; it is read
- *   from the body, or from the `X-Request-ID` response header when the body has none.
- *   `instance` is the occurrence's URN or request path.
- * - **Per-item failures.** `errors` is the platform's field-level list (`field`, `code`,
- *   `detail`), and `validationErrors` the structured diagnostics of a bundle that failed
- *   validation.
- * - **The standard's reading.** `problem` is the same answer read as the MTHDS standard reads
- *   it, the problem `mthds`'s own `ApiResponseError` carries: the body itself when it is a core
- *   problem document, and otherwise the problem its status reads as (`readAnswer` in
- *   `mthds/protocol`), except on a request that may create a run, where `runMayHaveStarted`
- *   decides: `client.outcome_unknown` for every answer that leaves a run possibly started, a core
- *   problem document's body included. Branch on `problem.code` to handle this SDK's errors and the
- *   standard client's alike. The hosted plane's problem documents predate the core registry, so
- *   for them `problem` says little; the members above are read from the hosted document as they
- *   always were, and those the standard names its own way do not collide with it: `code` is the
- *   platform's code beside the registry's `problem.code`, and `errors` the platform's field
- *   errors beside the problem items of `problem.errors`.
- *
- * `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 error is a `PipelineRequestError`, as every error of this SDK is, rather than the
- * standard's `ProblemError`: a `ProblemError`'s `code` is the registry's and its message the
- * problem's sentence, while this error's `code` is the platform's and its message names the
- * route and the hosted document's `detail`, so it carries the standard's reading as `problem`
- * instead.
+ * non-2xx refusal, a body that arrived and could not be decoded, 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.
+ *
+ * Its `problem` is the answer read as a problem (`readHostedAnswer`): the body itself when it is a
+ * problem document, as the hosted API answers every refusal, its `pipelex.*` code and any member
+ * the standard does not name kept; and otherwise the reading of the edge's bare answers by its
+ * status, `client.outcome_unknown` among them for a start or an execute the gateway cut off. Every
+ * getter of `ProblemError` reads it: branch on `code`, never on the HTTP status or the wording of
+ * a message. `retryAfter` is the problem's `retry_after`, which the `Retry-After` header fills when
+ * the problem invites a retry and gives none, and `requestId` the problem's `request_id`, else the
+ * answer's `X-Request-ID` header, the id to hand to support.
+ *
+ * `status` is the answer's HTTP status whatever the problem's own `status` says, `statusText` its
+ * reason phrase and `responseBody` its raw text, so a member this SDK does not name stays
+ * reachable without re-reading the body.
  */
 export declare class ApiResponseError extends PipelexRequestError {
     readonly apiUrl: string;
     readonly status: number;
     readonly statusText: string;
     readonly responseBody: string;
-    readonly errorType: string | undefined;
-    readonly serverMessage: string | undefined;
-    /**
-     * The platform's native code — a closed set (`conflict`, `not_found`, `run_not_found`,
-     * `pipelex_api_key_limit_reached`, …), one-to-one with `type`; `MethodErrorCode` names the
-     * ones about a stored method and its versions, and `IdempotencyErrorCode` the one about a
-     * request's idempotency key. Finer than `errorDomain` and specific to the
-     * platform: a runner's problem carries `errorType` instead. `undefined` for a body that
-     * carries no `code`.
-     */
-    readonly code: string | undefined;
-    /**
-     * RFC 9457 `type`: the stable URI naming the error class. With `errorDomain`, the field a
-     * machine consumer branches on — the same class carries the same URI on every occurrence.
-     */
-    readonly type: string | undefined;
-    /** RFC 9457 `title`: the short human label of the error class. */
-    readonly title: string | undefined;
-    /** RFC 9457 `instance`: the occurrence — the request path, or a request URN. */
-    readonly instance: string | undefined;
-    /**
-     * The request's correlation id — the body's `request_id`, or the `X-Request-ID` response
-     * header when the body carries none. The id to hand to support: it finds the server's log
-     * lines for this request.
-     */
-    readonly requestId: 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 `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. */
-    readonly model: string | undefined;
-    /** The body's `provider`: the provider an inference failure reached. */
-    readonly provider: string | undefined;
-    /**
-     * The body's `provider_metadata`: what the provider's SDK said. On the hosted API it comes
-     * from the runner's problem document, which the hosted runner renders under its STRICT
-     * disclosure, so it keeps only `status_code` and `retry_after_seconds`; a runner that
-     * discloses errors VERBOSE, as a self-hosted one does when `ERROR_DISCLOSURE` is unset, sends
-     * it whole, the provider's raw text included.
-     */
-    readonly providerMetadata: ProviderErrorMetadata | undefined;
-    /** The body's `migration`: a pending configuration migration that explains the failure. */
-    readonly migration: MigrationErrorBlock | undefined;
-    /**
-     * The platform's field-level `errors[]` — one item per offending request field. A refused
-     * branding write names the logo slot or the colour key each entry is about in its `field`,
-     * with a `LogoRefusalCode` for a logo the platform measured.
-     */
-    readonly errors: FieldError[] | undefined;
-    /**
-     * The decoded problem document whole — every member, named or not, such as a failed run's
-     * `run_status` and `error` or a member a newer server adds. `undefined` when the body was not
-     * a JSON object.
-     */
-    readonly problemDocument: Record<string, unknown> | undefined;
-    /**
-     * Structured per-error diagnostics on a problem body that carries a top-level
-     * `validation_errors[]` — the 422 a **run route** (`execute`, `start`) answers when the
-     * runner refuses the method for its validation errors.
-     *
-     * Everywhere else an invalid bundle is a produced verdict, not an `ApiResponseError`:
-     * `POST /v1/validate` answers it with a **200** `PipelexInvalidReport`, and the crate
-     * routes with a **200** `CrateInvalidReport`, whose `validation_errors[]` the caller
-     * reads off the returned value. This field is `undefined` for any error that carries no
-     * per-error list (auth, transport, a request-shape 422, the 422 `pipe-io` answers for a
-     * pipe selection it refuses). A consumer must NOT assume a given `error_type` implies a
-     * populated list — fall back to `serverMessage` when this is empty.
-     */
-    readonly validationErrors: ValidationErrorItem[] | undefined;
-    /**
-     * The answer read as the MTHDS standard reads it, the problem `mthds`'s own client carries,
-     * agreeing with `runMayHaveStarted`: `client.outcome_unknown` where a run may have started,
-     * whatever the body, and where none started the body when it is a core problem document,
-     * otherwise the reading of an answer to a request that creates no run.
-     * Built from the constructor's arguments, so an error a consumer builds by hand carries the
-     * reading the client would give it.
-     */
-    readonly problem: Problem;
-    constructor(message: string, apiUrl: string, status: number, statusText: string, responseBody: string, errorType: string | undefined, serverMessage: string | undefined, validationErrors: ValidationErrorItem[] | undefined, code: string | undefined, options?: ApiResponseErrorOptions);
+    private readonly requestIdHeader;
+    constructor(message: string, apiUrl: string, status: number, statusText: string, responseBody: string, options?: ApiResponseErrorOptions);
+    /** The request's id: the problem's `request_id`, else the answer's `X-Request-ID` header. */
+    get requestId(): string | undefined;
 }