@pipelex/sdk 0.52.0 → 0.53.0

package/dist/errors.js

@@ -1,99 +1,112 @@
 /**
  * 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, buildProblem, isProblem, parseJsonBody, readAnswer, unreadableAnswer, } from "mthds/protocol";
-import { isPlainObject } from "./error-models.js";
-import { fallbackVerdict, problemVerdict } from "./error-verdicts.js";
-import { answerMayHaveStartedRun, transportMayHaveStartedRun } from "./run-may-have-started.js";
-export { PipelineRequestError };
-const ERROR_DOMAINS = new Set(["input", "config", "runtime"]);
-/** Whether a value is one of the three error domains. */
-export function isErrorDomain(value) {
-    return typeof value === "string" && ERROR_DOMAINS.has(value);
-}
-/** Build a verdict; each class below declares its own with it. */
-function makeVerdict(errorDomain, retryable) {
-    return Object.freeze({ errorDomain, retryable });
-}
-/**
- * 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 class PipelexRequestError extends PipelineRequestError {
-    /** Whether asking again can plausibly succeed. Always decided. */
-    retryable;
-    /** Who can fix the failure: `input`, `config` or `runtime`. Always decided. */
-    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.
-     */
-    runMayHaveStarted;
-    constructor(message, verdict, options) {
-        super(message, options);
-        this.name = "PipelexRequestError";
-        this.runMayHaveStarted = options?.runMayHaveStarted === true;
-        // Asking again could start a second run, so a run that may have started is never retryable.
-        this.retryable = this.runMayHaveStarted ? false : verdict.retryable;
-        this.errorDomain = verdict.errorDomain;
-    }
+ * 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, buildProblem, isProblem, readAnswer, readProblemBody } from "mthds/protocol";
+import { outcomeUnknownProblem, readHostedAnswer } from "./answer-reading.js";
+import { requestMayHaveLeft } from "./transport-reading.js";
+export { ProblemError };
+/** The `cause` option of an error, given only when there is one, so `cause` stays absent otherwise. */
+function causeOption(cause) {
+    return cause === undefined ? undefined : { cause };
+}
+// ── The problems this module builds ──────────────────────────────────
+/**
+ * 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 function argumentInvalidProblem(argument, reason) {
+    return buildProblem("client.argument_invalid", { argument, reason });
 }
 /**
- * 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.
- */
-export function errorVerdictOf(err) {
-    if (!(err instanceof Error))
-        return undefined;
-    const { retryable, errorDomain, problem } = err;
-    if (typeof retryable === "boolean" && isErrorDomain(errorDomain)) {
-        return { retryable, errorDomain };
+ * 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 function responseUnreadableProblem(status, runId) {
+    return buildProblem("client.response_unreadable", { status }, runId === undefined ? {} : { pipeline_run_id: runId });
+}
+/** The problem the standard reads from an answer's status alone, as for a body that is no problem document. */
+export function statusProblem(status) {
+    return readAnswer({ status, headers: {}, body: "" }, { createsRun: false }).problem;
+}
+/**
+ * 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 function isTransientStorageStatus(status) {
+    return status === 408 || status === 429 || (status >= 500 && status <= 599 && status !== 501);
+}
+/**
+ * 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 function storageStatusProblem(status) {
+    if (isTransientStorageStatus(status))
+        return buildProblem("runtime.unavailable", {});
+    if (status === 501)
+        return buildProblem("runtime.unsupported", { capability: "this storage request" });
+    return responseUnreadableProblem(status);
+}
+/** The problem of a request refused for its credential: `auth.invalid_credential`, or `auth.missing_credential` when it carried none. */
+function credentialRefusedProblem(credentialSent) {
+    return credentialSent
+        ? buildProblem("auth.invalid_credential", {})
+        : buildProblem("auth.missing_credential", {});
+}
+/** The problem an error wrapping another carries: the wrapped error's, when it carries one. */
+function wrappedProblem(cause) {
+    return cause instanceof ProblemError ? cause.problem : undefined;
+}
+/**
+ * The problem of a refused credential, in this order: the server's own, when the wrapped
+ * `ApiResponseError` answered a problem document; then what the caller knows of its own request,
+ * when it says whether the request carried a credential, which the edge's bare `401` or `403` does
+ * not say; then the wrapped error's problem, its reading of that status; and otherwise
+ * `auth.invalid_credential`.
+ */
+function credentialProblem(cause, credentialSent) {
+    if (cause instanceof ApiResponseError && readProblemBody(cause.responseBody) !== undefined) {
+        return cause.problem;
     }
-    return isProblem(problem) ? problemVerdict(problem) : undefined;
+    if (credentialSent !== undefined)
+        return credentialRefusedProblem(credentialSent);
+    return wrappedProblem(cause) ?? credentialRefusedProblem(true);
 }
+// ── The base every request error derives from ────────────────────────
 /**
- * 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 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 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 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 function runMayHaveStartedOf(err) {
-    if (!(err instanceof Error))
-        return false;
-    return err.runMayHaveStarted === true;
+export class PipelexRequestError extends ProblemError {
+    constructor(message, problem, options) {
+        super(problem, options);
+        this.name = "PipelexRequestError";
+        this.message = message;
+    }
 }
 // ── Argument refusals ────────────────────────────────────────────────
 /**
@@ -107,15 +120,16 @@ export function runMayHaveStartedOf(err) {
  * 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 class RequestArgumentError extends PipelexRequestError {
     constructor(message, options) {
-        super(message, options?.verdict ?? makeVerdict("input", false), options);
+        super(message, options?.problem ?? argumentInvalidProblem("arguments", "unspecified"), causeOption(options?.cause));
         this.name = "RequestArgumentError";
     }
 }
@@ -126,25 +140,34 @@ export 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 class InputPreparationError extends PipelexRequestError {
     constructor(message, options) {
-        super(message, options?.verdict ?? makeVerdict("input", false), options);
+        super(message, options?.problem ?? argumentInvalidProblem("inputs", "unspecified"), causeOption(options?.cause));
         this.name = "InputPreparationError";
     }
 }
 /**
  * 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 class InvalidLocalSourceError extends InputPreparationError {
     source;
     constructor(message, source, options) {
-        super(message, options);
+        super(message, {
+            ...options,
+            problem: buildProblem("input.file_unreadable", {
+                input: source,
+                file_type: "file",
+                reason: "unreadable",
+            }),
+        });
         this.name = "InvalidLocalSourceError";
         this.source = source;
     }
@@ -160,13 +183,20 @@ export 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 class InvalidInputValueError extends InputPreparationError {
     inputName;
     inputPath;
     constructor(message, details, options) {
-        super(message, options);
+        super(message, {
+            ...options,
+            problem: buildProblem("input.invalid", {
+                input: details.inputName,
+                field: details.inputPath,
+            }),
+        });
         this.name = "InvalidInputValueError";
         this.inputName = details.inputName;
         this.inputPath = details.inputPath;
@@ -184,8 +214,9 @@ const UPLOAD_NOT_ALLOWED_KIND_WORDS = {
  * 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 class UploadNotAllowedError extends InputPreparationError {
     inputName;
@@ -194,7 +225,7 @@ export class UploadNotAllowedError extends InputPreparationError {
     constructor(details, options) {
         super(`Input "${details.inputPath}" is ${UPLOAD_NOT_ALLOWED_KIND_WORDS[details.valueKind]}, which ` +
             "would need an upload, and this preparation uploads nothing: pass an http(s) URL or a " +
-            "pipelex-storage:// reference instead.", options);
+            "pipelex-storage:// reference instead.", { ...options, problem: argumentInvalidProblem(details.inputPath, details.valueKind) });
         this.name = "UploadNotAllowedError";
         this.inputName = details.inputName;
         this.inputPath = details.inputPath;
@@ -203,18 +234,19 @@ export 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 class MethodLoadError extends InputPreparationError {
-    validationErrors;
     serverMessage;
     constructor(message, details, options) {
-        super(message, options);
+        super(message, {
+            ...options,
+            problem: buildProblem("method.invalid", {}, { errors: details.errors }),
+        });
         this.name = "MethodLoadError";
-        this.validationErrors = details.validationErrors;
         this.serverMessage = details.serverMessage;
     }
 }
@@ -225,48 +257,63 @@ export class MethodLoadError extends InputPreparationError {
  * 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 class RejectedAssetError extends InputPreparationError {
     filename;
     status;
-    code;
+    reason;
     constructor(message, filename, status, options) {
-        super(message, options);
+        super(message, {
+            cause: options?.cause,
+            problem: options?.problem ?? statusProblem(status),
+        });
         this.name = "RejectedAssetError";
         this.filename = filename;
         this.status = status;
-        this.code = options?.code;
+        this.reason = options?.reason;
     }
 }
 /**
  * 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 class UnsupportedUploadCapabilityError extends InputPreparationError {
     filename;
     constructor(message, options) {
-        super(message, { ...options, verdict: makeVerdict("config", false) });
+        super(message, {
+            cause: options?.cause,
+            problem: buildProblem("runtime.unsupported", { capability: "file upload" }),
+        });
         this.name = "UnsupportedUploadCapabilityError";
         this.filename = options?.filename;
     }
 }
 /**
  * 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 class UploadAuthenticationError extends InputPreparationError {
     status;
     filename;
     constructor(message, status, options) {
-        super(message, { ...options, verdict: makeVerdict("config", false) });
+        super(message, {
+            cause: options?.cause,
+            problem: credentialProblem(options?.cause, options?.credentialSent),
+        });
         this.name = "UploadAuthenticationError";
         this.status = status;
         this.filename = options?.filename;
@@ -275,102 +322,114 @@ export class UploadAuthenticationError extends InputPreparationError {
 /**
  * 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 class TestFileRefusedError extends InputPreparationError {
     status;
-    code;
+    reason;
     filename;
     methodId;
     constructor(message, options) {
         super(message, {
-            ...options,
-            verdict: errorVerdictOf(options?.cause) ?? testFileRefusalVerdict(options?.code),
+            cause: options?.cause,
+            problem: wrappedProblem(options?.cause) ?? testFileRefusalProblem(options?.reason),
         });
         this.name = "TestFileRefusedError";
         this.status = options?.status;
-        this.code = options?.code;
+        this.reason = options?.reason;
         this.filename = options?.filename;
         this.methodId = options?.methodId;
     }
 }
-/** The verdict of a test file's refusal that wraps no error carrying one. */
-function testFileRefusalVerdict(code) {
-    // A role is changed by an admin of the organization, never by sending the request again.
-    if (code === "role_not_permitted")
-        return makeVerdict("config", false);
-    return makeVerdict("input", false);
+/** The problem of a test file's refusal that wraps no error carrying one; `undefined` leaves the family's own. */
+function testFileRefusalProblem(reason) {
+    switch (reason) {
+        case "role_not_permitted":
+            return buildProblem("auth.forbidden", { requirement: "a role that may change methods" });
+        case "method_not_found":
+        case "method_being_deleted":
+            return argumentInvalidProblem("method_id", reason);
+        case undefined:
+            return undefined;
+    }
 }
 /**
  * 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 class UploadTransportError extends InputPreparationError {
     status;
-    code;
+    reason;
     filename;
     constructor(message, options) {
         super(message, {
-            ...options,
-            verdict: errorVerdictOf(options?.cause) ?? uploadTransportVerdict(options?.code, options?.status),
+            cause: options?.cause,
+            problem: options?.problem ??
+                wrappedProblem(options?.cause) ??
+                uploadTransportProblem(options?.reason, options?.status),
         });
         this.name = "UploadTransportError";
         this.status = options?.status;
-        this.code = options?.code;
+        this.reason = options?.reason;
         this.filename = options?.filename;
     }
 }
-/** The verdict of an upload transport failure that wraps no error carrying one. */
-function uploadTransportVerdict(code, status) {
-    switch (code) {
+/**
+ * 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 function uploadTransportProblem(reason, status) {
+    switch (reason) {
         case "timeout":
+        case "unreachable":
         case "storage_timeout":
         case "conflict":
-            return makeVerdict("runtime", true);
+            return buildProblem("runtime.unavailable", {});
         case "server_error":
-            // A fault in storage may pass, but a 501 says storage does not implement the request, and
-            // sending it again will not change that. The status reads as an API's would.
-            return makeVerdict("runtime", status === undefined || fallbackVerdict(status, undefined, true).retryable);
+            return status === undefined
+                ? buildProblem("runtime.unavailable", {})
+                : storageStatusProblem(status);
         case "unexpected":
-            // Storage's 408 or 429 refused the request for its timing, which a later attempt can pass;
-            // any other status, or none, says nothing of the kind.
-            return makeVerdict("runtime", status !== undefined && fallbackVerdict(status, undefined, true).retryable);
-        case "unreachable":
-            return makeVerdict("config", true);
+        case undefined:
+            return status === undefined
+                ? buildProblem("runtime.unexpected", {})
+                : storageStatusProblem(status);
         case "redirected":
-            return makeVerdict("config", false);
-        default:
-            // `invalid_grant_url`, no code, and a code this version does not know.
-            return makeVerdict("runtime", false);
+            return buildProblem("runtime.misconfigured", {});
+        case "invalid_grant_url":
+            return responseUnreadableProblem(200);
     }
 }
 /**
@@ -383,14 +442,15 @@ function uploadTransportVerdict(code, status) {
  * 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 class ArtifactOperationError extends PipelexRequestError {
     constructor(message, options) {
-        super(message, options?.verdict ?? makeVerdict("runtime", false), options);
+        super(message, options?.problem ?? buildProblem("runtime.unexpected", {}), causeOption(options?.cause));
         this.name = "ArtifactOperationError";
     }
 }
@@ -399,14 +459,14 @@ export 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 class ScopeUnavailableError extends ArtifactOperationError {
     scope;
     runId;
     constructor(scope, runId, options) {
         super(`Run "${runId}" carries no "${scope}" artifact to walk for produced files — ` +
-            "it is null or absent from the results body.", options);
+            "it is null or absent from the results body.", { cause: options?.cause, problem: responseUnreadableProblem(200, runId) });
         this.name = "ScopeUnavailableError";
         this.scope = scope;
         this.runId = runId;
@@ -414,56 +474,70 @@ export 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 class ArtifactFetchError extends ArtifactOperationError {
     uri;
-    code;
+    reason;
     status;
-    constructor(message, uri, code, status, options) {
-        super(message, { ...options, verdict: artifactFetchVerdict(code, status) });
+    constructor(message, uri, reason, status, options) {
+        super(message, {
+            cause: options?.cause,
+            problem: options?.problem ?? artifactFetchProblem(reason, uri, status),
+        });
         this.name = "ArtifactFetchError";
         this.uri = uri;
-        this.code = code;
+        this.reason = reason;
         this.status = status;
     }
 }
-/** The verdict of one reference's fetch failure, by its code and the store's status. */
-function artifactFetchVerdict(code, status) {
-    switch (code) {
+/**
+ * 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 function artifactFetchProblem(reason, uri, status) {
+    switch (reason) {
         case "invalid_storage_uri":
         case "forbidden":
-        case "unsupported_url":
         case "not_found":
-        case "too_large":
-            return makeVerdict("input", false);
+            return buildProblem("input.reference_not_found", { input: uri });
+        case "unsupported_url":
+            return buildProblem("client.link_refused", { reason: "unsupported_scheme" });
         case "plain_http_refused":
-            return makeVerdict("config", false);
+            return buildProblem("client.link_refused", { reason: "plain_http" });
+        case "redirect_refused":
+            return buildProblem("client.link_refused", { reason: "redirect" });
+        case "store_error":
+        case "store_refused":
+            return status === undefined
+                ? buildProblem("runtime.unavailable", {})
+                : storageStatusProblem(status);
         case "timeout":
         case "network":
-            return makeVerdict("runtime", true);
-        case "store_error":
-            // The store's status reads as an API's would: refused for its timing (408, 429) or a fault
-            // that may pass (a 5xx) can succeed on a retry, while a 501 or a 4xx will not.
-            return makeVerdict("runtime", status !== undefined && fallbackVerdict(status, undefined, true).retryable);
+            return buildProblem("runtime.unavailable", {});
         default:
-            // `redirect_refused`, `store_refused`, and a code this version does not know.
-            return makeVerdict("runtime", false);
+            return buildProblem("runtime.unexpected", {});
     }
 }
 /**
@@ -473,14 +547,19 @@ function artifactFetchVerdict(code, status) {
  * 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 class ArtifactAuthenticationError extends ArtifactOperationError {
     status;
     verdict;
     constructor(message, status, verdict, options) {
-        super(message, { ...options, verdict: makeVerdict("config", false) });
+        super(message, {
+            cause: options?.cause,
+            problem: credentialProblem(options?.cause, options?.credentialSent),
+        });
         this.name = "ArtifactAuthenticationError";
         this.status = status;
         this.verdict = verdict;
@@ -495,77 +574,88 @@ export class ArtifactAuthenticationError extends ArtifactOperationError {
  * `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 class MethodFileTransferError extends PipelexRequestError {
     operation;
-    code;
+    reason;
     sha256;
     path;
     status;
     constructor(message, details) {
-        super(message, methodFileTransferVerdict(details.code));
+        super(message, methodFileTransferProblem(details.reason, details.status));
         this.name = "MethodFileTransferError";
         this.operation = details.operation;
-        this.code = details.code;
+        this.reason = details.reason;
         this.sha256 = details.sha256;
         this.path = details.path;
         this.status = details.status;
     }
 }
-/** The verdict of a failed transfer of a method's file, by its code. */
-function methodFileTransferVerdict(code) {
-    switch (code) {
+/** The problem of a failed transfer of a method's file, by its reason and storage's status. */
+export function methodFileTransferProblem(reason, status) {
+    switch (reason) {
         case "unreachable":
         case "storage_error":
+            return buildProblem("runtime.unavailable", {});
+        case "refused":
+            return status === undefined
+                ? buildProblem("runtime.unexpected", {})
+                : storageStatusProblem(status);
         case "mismatch":
-            return makeVerdict("runtime", true);
-        default:
-            // `refused`, and a code this version does not know.
-            return makeVerdict("runtime", false);
+            return responseUnreadableProblem(200);
     }
 }
+// ── Transport ────────────────────────────────────────────────────────
 /**
  * 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 class ApiUnreachableError extends PipelexRequestError {
     apiUrl;
-    code;
-    constructor(message, apiUrl, code, options) {
-        super(message, makeVerdict(code === "ABORT_TIMEOUT" ? "runtime" : "config", true), {
-            ...options,
-            runMayHaveStarted: options?.mayStartRun === true && transportMayHaveStartedRun(options.cause),
-        });
+    networkCode;
+    constructor(message, apiUrl, networkCode, options) {
+        super(message, transportProblem(apiUrl, networkCode, options), causeOption(options?.cause));
         this.name = "ApiUnreachableError";
         this.apiUrl = apiUrl;
-        this.code = code;
+        this.networkCode = networkCode;
+    }
+}
+/** The SDK's own time limit ran out while the request was sent or answered. */
+export const ABORT_TIMEOUT = "ABORT_TIMEOUT";
+/** The problem of a request that got no answer, agreeing with whether it may have left. */
+function transportProblem(apiUrl, networkCode, options) {
+    if (options?.mayStartRun === true && requestMayHaveLeft(options.cause)) {
+        return outcomeUnknownProblem();
+    }
+    if (networkCode === ABORT_TIMEOUT && options?.timeoutMs !== undefined) {
+        return buildProblem("client.timeout", { seconds: options.timeoutMs / 1000 });
     }
+    return buildProblem("client.unreachable", { base_url: apiUrl });
 }
 /**
  * Thrown when the blocking `execute` (`POST /v1/execute`) is killed by the
@@ -573,9 +663,9 @@ export class ApiUnreachableError extends PipelexRequestError {
  * 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 class PipelineExecuteTimeoutError extends PipelexRequestError {
     elapsedMs;
@@ -583,62 +673,49 @@ export class PipelineExecuteTimeoutError extends PipelexRequestError {
         const seconds = Math.round(elapsedMs / 1000);
         super(`The Pipelex Hosted API times out synchronous requests after ~30s — this run took ${seconds}s. ` +
             "The blocking execute path can't run methods longer than 30s behind the gateway. " +
-            "Start the run and poll for its result instead: `start()` then `waitForResult(runId)`.", makeVerdict("input", false), { ...options, runMayHaveStarted: true });
+            "Start the run and poll for its result instead: `start()` then `waitForResult(runId)`.", outcomeUnknownProblem(), causeOption(options?.cause));
         this.name = "PipelineExecuteTimeoutError";
         this.elapsedMs = elapsedMs;
     }
 }
+// ── The run lifecycle ────────────────────────────────────────────────
+/**
+ * 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 function runFailedProblem(runId, status, runError) {
+    return buildProblem("run.failed", { pipeline_run_id: runId, run_status: status }, { pipeline_run_id: runId, extra: { run_error: runError ?? undefined } });
+}
 /**
  * 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 class RunFailedError extends PipelexRequestError {
     runId;
     status;
-    error;
     constructor(message, runId, status, options) {
-        super(message, runFailureVerdict(options?.error ?? null), options?.cause === undefined ? undefined : { cause: options.cause });
+        super(message, options?.problem ?? runFailedProblem(runId, status), causeOption(options?.cause));
         this.name = "RunFailedError";
         this.runId = runId;
         this.status = status;
-        this.error = options?.error ?? null;
     }
-}
-/** The verdict of a failed run, read from its stored report. */
-function runFailureVerdict(report) {
-    const domain = report?.error_domain;
-    return makeVerdict(isErrorDomain(domain) ? domain : "runtime", report?.retryable === true);
+    /** The run's own problem, nested as `run_error`, when the run ended with one. */
+    get runError() {
+        const nested = this.problem.run_error;
+        return isProblem(nested) ? nested : undefined;
+    }
 }
 /**
  * Thrown when a completed run cannot deliver its main stuff.
@@ -650,28 +727,34 @@ function runFailureVerdict(report) {
  * 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 class MissingMainStuffError extends PipelexRequestError {
     runId;
     constructor(message, runId) {
-        super(message, makeVerdict("runtime", false));
+        super(message, responseUnreadableProblem(200, runId));
         this.name = "MissingMainStuffError";
         this.runId = runId;
     }
 }
+/** `client.follow_failed`: the client stopped following a run that may still be going. */
+function followFailedProblem(runId) {
+    return buildProblem("client.follow_failed", { pipeline_run_id: runId }, { pipeline_run_id: runId });
+}
 /**
  * Thrown when `waitForResult` exceeds its `timeoutMs` before the run reaches a
  * terminal state. The run is NOT cancelled — it keeps executing server-side and
  * can be resumed later by `runId` (the poll loop just stopped waiting).
  *
- * Its verdict is `runtime` and retryable: the run is still going, and waiting again can succeed.
+ * 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 class RunTimeoutError extends PipelexRequestError {
     runId;
     timeoutMs;
     constructor(message, runId, timeoutMs) {
-        super(message, makeVerdict("runtime", true));
+        super(message, followFailedProblem(runId));
         this.name = "RunTimeoutError";
         this.runId = runId;
         this.timeoutMs = timeoutMs;
@@ -686,14 +769,15 @@ export 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 class RunStillRunningError extends PipelexRequestError {
     runId;
     retryAfterSeconds;
     location;
     constructor(message, runId, retryAfterSeconds = null, location = null, options) {
-        super(message, makeVerdict("runtime", true), options);
+        super(message, followFailedProblem(runId), causeOption(options?.cause));
         this.name = "RunStillRunningError";
         this.runId = runId;
         this.retryAfterSeconds = retryAfterSeconds;
@@ -707,16 +791,17 @@ export 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 class RunLifecycleUnavailableError extends PipelexRequestError {
     apiUrl;
     constructor(message, apiUrl, options) {
-        super(message, makeVerdict("config", false), options);
+        super(message, buildProblem("runtime.unsupported", { capability: "the durable run lifecycle" }), causeOption(options?.cause));
         this.name = "RunLifecycleUnavailableError";
         this.apiUrl = apiUrl;
     }
@@ -728,262 +813,69 @@ export 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 class PagingNotTerminatingError extends PipelexRequestError {
     pageLimit;
     constructor(message, pageLimit) {
-        super(message, makeVerdict("runtime", false));
+        super(message, responseUnreadableProblem(200));
         this.name = "PagingNotTerminatingError";
         this.pageLimit = pageLimit;
     }
 }
+/** The response header carrying the request's correlation id. */
+const REQUEST_ID_HEADER = "x-request-id";
+/** A header's value, as fetch gives the headers or as a plain map of names. */
+function headerValue(headers, name) {
+    if (headers === undefined)
+        return undefined;
+    if (typeof headers.get === "function") {
+        const value = headers.get(name);
+        return value === null || value === "" ? undefined : value;
+    }
+    const map = headers;
+    const found = Object.keys(map).find((key) => key.toLowerCase() === name);
+    const value = found === undefined ? undefined : map[found];
+    return value === undefined || value === "" ? undefined : value;
+}
 /**
  * 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 class ApiResponseError extends PipelexRequestError {
     apiUrl;
     status;
     statusText;
     responseBody;
-    errorType;
-    serverMessage;
-    /**
-     * 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`.
-     */
-    code;
-    /**
-     * 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.
-     */
-    type;
-    /** RFC 9457 `title`: the short human label of the error class. */
-    title;
-    /** RFC 9457 `instance`: the occurrence — the request path, or a request URN. */
-    instance;
-    /**
-     * 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.
-     */
-    requestId;
-    /**
-     * The body's `error_category`: the finer classification of an inference failure — known
-     * values `transient`, `configuration`, `content`, `capacity`, `ambiguous`, `unknown`.
-     */
-    errorCategory;
-    /** The body's `user_action`: what the caller should do next, when the server can say. */
-    userAction;
-    /** The body's `model`: the model an inference failure used. */
-    model;
-    /** The body's `provider`: the provider an inference failure reached. */
-    provider;
-    /**
-     * 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.
-     */
-    providerMetadata;
-    /** The body's `migration`: a pending configuration migration that explains the failure. */
-    migration;
-    /**
-     * 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.
-     */
-    errors;
-    /**
-     * 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.
-     */
-    problemDocument;
-    /**
-     * 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.
-     */
-    validationErrors;
-    /**
-     * 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.
-     */
-    problem;
-    constructor(message, apiUrl, status, statusText, responseBody, errorType, serverMessage, validationErrors, code, options) {
-        super(message, responseVerdict(status, errorType, code, options?.details), {
-            ...(options?.cause === undefined ? {} : { cause: options.cause }),
-            runMayHaveStarted: options?.mayStartRun === true && answerMayHaveStartedRun(status, code),
-        });
+    requestIdHeader;
+    constructor(message, apiUrl, status, statusText, responseBody, options) {
+        super(message, options?.problem ??
+            readHostedAnswer({ status, headers: options?.headers ?? {}, body: responseBody }, { createsRun: options?.mayStartRun === true }).problem, causeOption(options?.cause));
         this.name = "ApiResponseError";
         this.apiUrl = apiUrl;
         this.status = status;
         this.statusText = statusText;
         this.responseBody = responseBody;
-        this.errorType = errorType;
-        this.serverMessage = serverMessage;
-        this.validationErrors = validationErrors;
-        this.code = code;
-        const details = options?.details;
-        this.type = details?.type;
-        this.title = details?.title;
-        this.instance = details?.instance;
-        this.requestId = details?.requestId;
-        this.errorCategory = details?.errorCategory;
-        this.userAction = details?.userAction;
-        this.model = details?.model;
-        this.provider = details?.provider;
-        this.providerMetadata = details?.providerMetadata;
-        this.migration = details?.migration;
-        this.errors = details?.errors;
-        this.problemDocument = options?.problemDocument;
-        this.problem = standardReading(status, responseBody, options?.headers ?? {}, options?.mayStartRun === true, code);
-    }
-}
-/**
- * An answer read as the MTHDS standard reads it, as `mthds`'s own client does, agreeing with the
- * error's `runMayHaveStarted`: on a request that may create a run, the SDK's own reading of
- * whether a run may have started (`answerMayHaveStartedRun`) decides, as an
- * `ApiUnreachableError`'s does for a request that got no answer, so that `problem` never says a
- * run may exist where `runMayHaveStarted` says none started, nor the reverse.
- *
- * - Where a run may have started, the answer reads as `client.outcome_unknown`, naming the run
- *   when the body names one (the platform's `bad_gateway` does when it lost a start's
- *   acknowledgement), whatever the body: a `408`, which a proxy may answer for a request it
- *   forwarded, every `5xx` but a `501` and a `503` carrying the platform's code
- *   `pipeline_start_unavailable`, and a `2xx` the SDK could not read, since the server accepted
- *   the request. A core problem document in such a body is not kept, since one inviting a retry
- *   would contradict `runMayHaveStarted`.
- * - Where none started, which is every answer to a request that creates no run, a status outside
- *   `2xx` whose body is a core problem document reads as that document, and any other as the
- *   answer to a request that creates none: the code its status names (`runtime.unavailable` for
- *   that `503`), else `client.response_unreadable` naming the status (that `501`). A `2xx` the SDK
- *   could not read is `client.response_unreadable`.
- */
-function standardReading(status, body, headers, mayStartRun, code) {
-    const runMayHaveStarted = mayStartRun && answerMayHaveStartedRun(status, code);
-    if (!runMayHaveStarted) {
-        if (status >= 200 && status < 300)
-            return unreadableAnswer(status);
-        return readAnswer({ status, headers, body }, { createsRun: false }).problem;
-    }
-    const reading = parseJsonBody(body);
-    const runId = reading.ok && isPlainObject(reading.value) ? reading.value.pipeline_run_id : undefined;
-    if (typeof runId !== "string" || runId === "") {
-        return buildProblem("client.outcome_unknown", {});
-    }
-    return buildProblem("client.outcome_unknown", { pipeline_run_id: runId }, { pipeline_run_id: runId });
-}
-/**
- * The verdict of a refused request: each member the document's own when it is valid, and the
- * fallback's otherwise, except that a sent `input` or `config` domain with no sent `retryable` is
- * not retryable. A `404` is named when the body carries a platform `code` or a runner
- * `error_type`, read from the constructor's arguments, so an `ApiResponseError` a consumer builds
- * by hand gets the verdict the client would give it.
- */
-function responseVerdict(status, errorType, code, problem) {
-    const fallback = fallbackVerdict(status, code, code !== undefined || errorType !== undefined);
-    const sentDomain = problem?.errorDomain;
-    const sentRetryable = problem?.retryable;
-    if (!isErrorDomain(sentDomain)) {
-        return makeVerdict(fallback.errorDomain, typeof sentRetryable === "boolean" ? sentRetryable : fallback.retryable);
-    }
-    if (typeof sentRetryable === "boolean")
-        return makeVerdict(sentDomain, sentRetryable);
-    // The server said who fixes the failure and nothing of a retry. When the caller or the
-    // environment must change, asking again unchanged meets the same answer, whatever the status
-    // would suggest; only a `runtime` fault keeps the status's reading.
-    return makeVerdict(sentDomain, sentDomain === "runtime" ? fallback.retryable : false);
+        this.requestIdHeader = headerValue(options?.headers, REQUEST_ID_HEADER);
+    }
+    /** The request's id: the problem's `request_id`, else the answer's `X-Request-ID` header. */
+    get requestId() {
+        return super.requestId ?? this.requestIdHeader;
+    }
 }
 //# sourceMappingURL=errors.js.map