@pipelex/sdk 0.51.0 → 0.53.0

package/README.md

@@ -81,17 +81,17 @@ console.log(saved.method_version); // 3
 `start` and `startAndWaitForResult` take an optional `idempotencyKey`, sent as the `Idempotency-Key` header of `POST /v1/start`. The hosted API binds the key to the run the first request starts, so the same start sent again under the same key is answered with that run and starts nothing: a start whose answer was lost can be sent again without paying for a second run. Generate one key per run, and keep it with the options, unchanged, across that start's retries:
 
 ```ts
-import { runMayHaveStartedOf } from "@pipelex/sdk";
+import { isProblemError } from "mthds/protocol";
 
 const options = { method_id: "mt_abc123", inputs, idempotencyKey: crypto.randomUUID() };
 const ack = await client.start(options).catch((err: unknown) => {
   // The run may exist: under the same key, the same start is answered with it.
-  if (runMayHaveStartedOf(err)) return client.start(options);
+  if (isProblemError(err) && err.retry === "outcome_unknown") return client.start(options);
   throw err;
 });
 ```
 
-A key is 1 to 255 visible ASCII characters; a key reused with other options is refused with a `409` `conflict`, and one whose earlier start is still being handled with a retryable `409` `idempotency_key_in_use` ([`docs/errors.md`](./docs/errors.md#a-starts-idempotency-key--idempotencykey)). A bare runner ignores the header.
+A key is 1 to 255 visible ASCII characters; a key reused with other options is refused with a `409` `request.idempotency_conflict`, and one whose earlier start is still being handled with a `409` `request.idempotency_key_in_use` whose `retry` is `yes` ([`docs/errors.md`](./docs/errors.md#a-starts-idempotency-key--idempotencykey)). A bare runner ignores the header.
 
 ### Checking a model reference
 
@@ -110,7 +110,7 @@ if (verdict.resolution === "resolved") {
 }
 ```
 
-A reference the runner cannot read at all (blank, a sigil alone, too long) or an unknown category throws `ApiResponseError`, a `422` whose `errorType` is `InvalidModelReference` or `InvalidModelCategory`.
+A reference the runner cannot read at all (blank, a sigil alone, too long) or an unknown category throws `ApiResponseError`, a `422` `request.invalid` whose `location.field` names `reference` or `type`.
 
 ### Product routes
 
@@ -168,8 +168,9 @@ for await (const saved of client.iterateMethodExamples(created.method_id)) {
 }
 
 // Copy a method into a team, or into your personal workspace, with its draft, its form inputs and
-// its examples (web sessions only). A bundle naming storage the destination cannot read answers
-// `refused`, a verdict rather than an error; the key makes a retry copy once.
+// its examples (web sessions only). A bundle naming storage the destination cannot read, or, in a
+// duplicate, a file under the original's run files, which erasing the original would remove,
+// answers `refused`, a verdict rather than an error; the key makes a retry copy once.
 const copy = await client.copyMethod(
   created.method_id,
   { destination_org_id: "org_team", expected_draft_updated_at: draft.updated_at },
@@ -207,25 +208,25 @@ try {
 
 ### Errors
 
-Every error the SDK throws carries a verdict: `retryable`, whether asking again can succeed, and `errorDomain`, who can fix the failure (`input` for the caller, `config` for a change to the environment such as the credential, the plan or the base URL, `runtime` for nobody beforehand). Both are always decided, and `errorVerdictOf` reads them from anything a `catch` holds, an error of the standard's own `mthds` client included, which it reads by its problem's `domain` and `retry`, returning `undefined` for what carries no verdict, such as a bug in the calling code or your own abort. A failed `start` or blocking `execute` also says whether it may have created a run anyway, as `runMayHaveStarted`, read with `runMayHaveStartedOf`: when it is `true`, `retryable` is `false`, since asking again could start a second paid run, and the person should look the run up in the run history first ([`docs/errors.md`](./docs/errors.md#a-failed-run-start--runmayhavestarted)), unless the start carried an `idempotencyKey`, in which case sending it again unchanged recovers the run ([above](#a-start-you-can-retry-idempotencykey)).
+Every error the SDK throws carries its failure as one problem document, the MTHDS standard's RFC 9457 document, under a registered code: the hosted API's own when it refused the request, the problem the platform stored when a run failed, and one the SDK builds under a `client.*` code for a failure it detects itself, such as a request that got no answer or an answer it cannot read. Every error is the standard's `ProblemError`, so `isProblemError` from `mthds/protocol` matches it, and its getters read the problem: `code` to branch on, `domain` for who must act (`input`, `method`, `account`, `operator` or `runtime`), `retry` for whether sending the same request again can succeed (`yes`, `no`, or `outcome_unknown` when a start may have created a run, which is looked up in the run history before anything is sent again, unless the start carried an `idempotencyKey`, in which case sending it again unchanged recovers the run, [above](#a-start-you-can-retry-idempotencykey)), `nextStep` for what to do, `retryAfter` and `requestId`, the id to hand to support. Branch on the problem, never on the HTTP status or the message.
 
 ```ts
-import { errorVerdictOf } from "@pipelex/sdk";
+import { isProblemError } from "mthds/protocol";
 
 try {
   await client.startAndWaitForResult({ method_id: "mt_abc123", inputs });
 } catch (err) {
-  const verdict = errorVerdictOf(err);
-  if (verdict === undefined) throw err; // not an SDK error: a bug, or the caller's own abort
-  if (verdict.retryable) return scheduleRetry();
-  if (verdict.errorDomain === "input") return askTheUserToFix(err);
-  return reportToOperator(err);
+  if (!isProblemError(err)) throw err; // not an SDK failure: a bug, or the caller's own abort
+  if (err.retry === "outcome_unknown") return lookUpTheRunBeforeStartingAgain(err);
+  if (err.retry === "yes") return scheduleRetry(err.retryAfter);
+  if (err.domain === "input" || err.domain === "method") return askTheUserToFix(err.problem);
+  return reportToOperator(err.problem);
 }
 ```
 
-A refused request throws an `ApiResponseError` carrying every member of the server's RFC 9457 problem document. **Branch on `errorDomain` and `type`**, as the hosted-envelope spec says, never on the HTTP status or the message: `errorDomain` is the verdict's domain and `type` is the stable URI of the error class, the same on every occurrence. The verdict is the server's when it sent a valid one, and otherwise the SDK's fallback, read from the status, except that an `input` or `config` domain the server sent without `retryable` is not retryable; `problemDocument` keeps what the server sent. `userAction` gives the next step, and `requestId` — from the body, or the `X-Request-ID` header — is the id to hand to support. `code` (the platform's native code, one-to-one with `type`) and `errorType` (the runner's exception class name) are each surface's finer code, and a client of that surface may branch on it too: on the platform's own refusals `code` and `type` read the same answer, `MethodErrorCode` naming the codes a method caller branches on, while a refusal the platform relays from the runner carries the runner's `type` and `errorType` and no `code`. `errors` carries the platform's field-level failures.
+A refused request throws an `ApiResponseError` whose `problem` is the hosted API's problem document as received, a `pipelex.*` code and every member the standard does not name included, such as the `limit` a refusal past a bound names; an answer whose body is no problem document, from the hosted edge, a gateway or a proxy, reads by its status. `status`, `statusText` and `responseBody` keep the answer itself. `MethodErrorCode` names the codes a method caller branches on, and `IdempotencyErrorCode` those of an `Idempotency-Key`.
 
-On the hosted API, a run that ends without completing throws a `RunFailedError` from `waitForResult`, `startAndWaitForResult` and `downloadArtifacts`, and comes back as the `failed` arm of `getRunResult`. (Against a bare `pipelex-api` runner, `startAndWaitForResult` runs the method with the blocking `execute`, so a failed run there throws the runner's `ApiResponseError`, whose problem members carry the same classification.) Its `status` is the run's terminal status and its `error` is the run's stored error report, checked field by field and typed as `RunErrorReport`: the reason in `message`, `error_domain`, `type_uri` and `retryable` to branch on, `user_action` as the next step, and the provider's answer in `provider_metadata`'s `status_code` and `retry_after_seconds`. It is `null` when the run ended without a report, and the error's own verdict comes from it: the report's domain, and retryable only when the report says so. The platform serves the runner's STRICT projection of the report: `message` is the author's copy when `caller_facing_message` is `true` and `An internal error occurred.` otherwise, `user_action` comes only with caller-facing copy, and the model, the provider and the provider's own text are left out, so `message` can be shown as it comes and what a person sees is still your presentation:
+On the hosted API, a run that ends without completing throws a `RunFailedError` from `waitForResult`, `startAndWaitForResult` and `downloadArtifacts`, and comes back as the `failed` arm of `getRunResult`. Its `problem` is `run.failed`, naming the run and its terminal status, and its `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`, `model.unavailable`, `method.invalid`, …), with its own `retry` and `next_step`. It is `undefined` when the run ended with no problem stored.
 
 ```ts
 import { RunFailedError } from "@pipelex/sdk";
@@ -234,13 +235,13 @@ try {
   await client.waitForResult(runId);
 } catch (err) {
   if (err instanceof RunFailedError) {
-    console.error(err.message); // "Run finished with status FAILED: <the reason>"
-    console.error(err.error?.user_action?.detail ?? "No next step was given.");
+    console.error(err.message); // names the run and its terminal status
+    console.error(err.runError?.next_step.detail ?? "No next step was given.");
   }
 }
 ```
 
-[`docs/errors.md`](./docs/errors.md) gives each class's verdict, the fallback table, and every field of both.
+[`docs/errors.md`](./docs/errors.md) gives each class's problem, the reading of an answer that is no problem document, and the case file both SDKs run.
 
 ### Client identification
 
@@ -289,7 +290,7 @@ These pages ship inside the published package, so a reader who has only installe
 | [`docs/exact-integers.md`](./docs/exact-integers.md) | Which reads keep an integer past `Number.MAX_SAFE_INTEGER` exact, as a `bigint` (a run's inputs and outputs, an example's inputs), how a request body writes it back with its digits, and `parseExactJson` and `stringifyExactJson` for code showing such data as JSON text |
 | [`docs/crate-routes.md`](./docs/crate-routes.md) | `resolve`, `codegen` and `pipeIo` — the method's tree as the protocol's `files` map, with its dependencies, the normalized crate, the stamped types, and a method's I/O artifacts without a validation — and the offline `runCodegenCheck` that guards a committed tree |
 | [`docs/client-identification.md`](./docs/client-identification.md) | The `User-Agent` every API request carries, and `appInfo`, the option that puts your program's name in front of it |
-| [`docs/errors.md`](./docs/errors.md) | The verdict every error carries (`retryable`, `errorDomain`, `errorVerdictOf`), a failed run's stored error report on `RunFailedError` and `RunRead`, and every member of a refused request's `ApiResponseError`, with the fields to branch on |
+| [`docs/errors.md`](./docs/errors.md) | The problem every error carries (`code`, `domain`, `retry`, `nextStep`), a start whose outcome is unknown, each class's problem, a refused request's `ApiResponseError`, a failed run's `run.failed` and its nested `run_error`, and a verdict's problem items |
 
 ## Develop
 

package/dist/answer-reading.d.ts

@@ -0,0 +1,70 @@
+/**
+ * How the SDK reads an answer that is not the route's result as a problem: a refusal, a failure, or
+ * a `2xx` it cannot read. The Python twin, `pipelex-sdk`, reads every answer the same way in
+ * `pipelex_sdk.answer_reading`, and the shared case file `tests/fixtures/sdk-problems.json` pins the
+ * readings both apply.
+ *
+ * - A body that is a problem document reads as received, every member it carries kept, a
+ *   `pipelex.*` code and the members the standard does not name included, its `status` taken from
+ *   the answer when it leaves it out and its `retry_after` from the `Retry-After` header when it
+ *   gives none and its `retry` is `yes` (`readAnswer` in `mthds/protocol`). On a start or an
+ *   execute too: the problem's own `retry` says whether a run may exist.
+ * - A body that is no problem document is the hosted edge's, a gateway's or a proxy's, which
+ *   nobody configures, and reads by the rules below. They stay written here until the registry
+ *   records them and every client generates them.
+ *
+ * On a request that creates a run, a `start` or an `execute`:
+ *
+ * - a `2xx` the SDK could not read is `client.outcome_unknown`, since the server accepted the
+ *   request and only its acknowledgement was lost, naming the run when the body names one;
+ * - a `408`, which a proxy may answer for a request it forwarded, and a `5xx` but a `501`, which a
+ *   gateway answers when the platform was slow or unreachable behind it, are
+ *   `client.outcome_unknown` too, whatever the time it took: the run may have started behind it.
+ *
+ * On any route, and on a start for every other status:
+ *
+ * - a `401` is `auth.missing_credential`: the edge answers it before the platform when the request
+ *   carries no credential;
+ * - a `403` is `auth.invalid_credential`: the edge's authorizer refused the credential, or the
+ *   route is outside what the credential may call;
+ * - a `404` is `request.not_found`: no route matches;
+ * - a `408` and a `429` are `runtime.unavailable`, with the `Retry-After` the answer gives: a
+ *   proxy timed the request out, or the edge throttled it, and a later attempt can pass. The core
+ *   registry's `account.rate_limited` names the limit and its window, which an edge throttle does
+ *   not say, so a client cannot state it;
+ * - a `500` is `runtime.unexpected`;
+ * - a `502`, a `503` and a `504` are `runtime.unavailable`, with the `Retry-After` the answer
+ *   gives;
+ * - any other status reads as `readAnswer` reads it: the one core code raised with that status
+ *   when a client can state it (`request.method_not_allowed` for a `405`), and otherwise
+ *   `client.response_unreadable` naming the status. A `2xx` the SDK could not read is
+ *   `client.response_unreadable` too.
+ */
+import type { AnswerHeaders, Problem } from "mthds/protocol";
+/** An answer the hosted API, its edge or a proxy in front of it gave. */
+export interface HostedAnswer {
+    status: number;
+    headers: AnswerHeaders;
+    body: string;
+}
+/** An answer read as its problem, and whether that problem is the answer's own body. */
+export interface HostedAnswerReading {
+    problem: Problem;
+    /** Whether the body is the problem document `problem` was read from, as received. */
+    fromBody: boolean;
+}
+/**
+ * Read an answer that is not the route's result as its problem, by the rules this module's header
+ * gives. `createsRun` is true for a `start` and an `execute`, and only for them.
+ */
+export declare function readHostedAnswer(answer: HostedAnswer, options?: {
+    createsRun?: boolean;
+}): HostedAnswerReading;
+/** The run a body that is no problem document names as its `pipeline_run_id`, when it names one. */
+export declare function runIdNamedBy(body: string): string | undefined;
+/**
+ * `client.outcome_unknown`, the problem of a request that may have started a run whose
+ * acknowledgement never reached the caller, naming the run in its parameters and as its member
+ * when its id is known.
+ */
+export declare function outcomeUnknownProblem(runId?: string): Problem;

package/dist/answer-reading.js

@@ -0,0 +1,106 @@
+/**
+ * How the SDK reads an answer that is not the route's result as a problem: a refusal, a failure, or
+ * a `2xx` it cannot read. The Python twin, `pipelex-sdk`, reads every answer the same way in
+ * `pipelex_sdk.answer_reading`, and the shared case file `tests/fixtures/sdk-problems.json` pins the
+ * readings both apply.
+ *
+ * - A body that is a problem document reads as received, every member it carries kept, a
+ *   `pipelex.*` code and the members the standard does not name included, its `status` taken from
+ *   the answer when it leaves it out and its `retry_after` from the `Retry-After` header when it
+ *   gives none and its `retry` is `yes` (`readAnswer` in `mthds/protocol`). On a start or an
+ *   execute too: the problem's own `retry` says whether a run may exist.
+ * - A body that is no problem document is the hosted edge's, a gateway's or a proxy's, which
+ *   nobody configures, and reads by the rules below. They stay written here until the registry
+ *   records them and every client generates them.
+ *
+ * On a request that creates a run, a `start` or an `execute`:
+ *
+ * - a `2xx` the SDK could not read is `client.outcome_unknown`, since the server accepted the
+ *   request and only its acknowledgement was lost, naming the run when the body names one;
+ * - a `408`, which a proxy may answer for a request it forwarded, and a `5xx` but a `501`, which a
+ *   gateway answers when the platform was slow or unreachable behind it, are
+ *   `client.outcome_unknown` too, whatever the time it took: the run may have started behind it.
+ *
+ * On any route, and on a start for every other status:
+ *
+ * - a `401` is `auth.missing_credential`: the edge answers it before the platform when the request
+ *   carries no credential;
+ * - a `403` is `auth.invalid_credential`: the edge's authorizer refused the credential, or the
+ *   route is outside what the credential may call;
+ * - a `404` is `request.not_found`: no route matches;
+ * - a `408` and a `429` are `runtime.unavailable`, with the `Retry-After` the answer gives: a
+ *   proxy timed the request out, or the edge throttled it, and a later attempt can pass. The core
+ *   registry's `account.rate_limited` names the limit and its window, which an edge throttle does
+ *   not say, so a client cannot state it;
+ * - a `500` is `runtime.unexpected`;
+ * - a `502`, a `503` and a `504` are `runtime.unavailable`, with the `Retry-After` the answer
+ *   gives;
+ * - any other status reads as `readAnswer` reads it: the one core code raised with that status
+ *   when a client can state it (`request.method_not_allowed` for a `405`), and otherwise
+ *   `client.response_unreadable` naming the status. A `2xx` the SDK could not read is
+ *   `client.response_unreadable` too.
+ */
+import { buildProblem, parseJsonBody, readAnswer, readProblemBody, retryAfterSeconds, unreadableAnswer, } from "mthds/protocol";
+/**
+ * Read an answer that is not the route's result as its problem, by the rules this module's header
+ * gives. `createsRun` is true for a `start` and an `execute`, and only for them.
+ */
+export function readHostedAnswer(answer, options = {}) {
+    if (readProblemBody(answer.body) !== undefined) {
+        return readAnswer(answer, { createsRun: false });
+    }
+    return { problem: bareAnswerProblem(answer, options.createsRun === true), fromBody: false };
+}
+/** Whether `status` is a success. */
+function isSuccess(status) {
+    return status >= 200 && status < 300;
+}
+/** The problem of an answer whose body is no problem document, by the edge's rules. */
+function bareAnswerProblem(answer, createsRun) {
+    const { status } = answer;
+    if (createsRun && (isSuccess(status) || status === 408 || (status >= 500 && status !== 501))) {
+        return outcomeUnknownProblem(runIdNamedBy(answer.body));
+    }
+    if (isSuccess(status))
+        return unreadableAnswer(status);
+    switch (status) {
+        case 401:
+            return buildProblem("auth.missing_credential", {}, { status });
+        case 403:
+            return buildProblem("auth.invalid_credential", {}, { status });
+        case 404:
+            return buildProblem("request.not_found", {}, { status });
+        case 500:
+            return buildProblem("runtime.unexpected", {}, { status });
+        case 408:
+        case 429:
+        case 502:
+        case 503:
+        case 504:
+            return buildProblem("runtime.unavailable", {}, { status, retryAfter: retryAfterSeconds(answer.headers) });
+        default:
+            return readAnswer(answer, { createsRun: false }).problem;
+    }
+}
+/** The run a body that is no problem document names as its `pipeline_run_id`, when it names one. */
+export function runIdNamedBy(body) {
+    const reading = parseJsonBody(body);
+    if (!reading.ok)
+        return undefined;
+    const { value } = reading;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const runId = value.pipeline_run_id;
+    return typeof runId === "string" && runId !== "" ? runId : undefined;
+}
+/**
+ * `client.outcome_unknown`, the problem of a request that may have started a run whose
+ * acknowledgement never reached the caller, naming the run in its parameters and as its member
+ * when its id is known.
+ */
+export function outcomeUnknownProblem(runId) {
+    if (runId === undefined)
+        return buildProblem("client.outcome_unknown", {});
+    return buildProblem("client.outcome_unknown", { pipeline_run_id: runId }, { pipeline_run_id: runId });
+}
+//# sourceMappingURL=answer-reading.js.map

package/dist/answer-reading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer-reading.js","sourceRoot":"","sources":["../src/answer-reading.ts"],"names":[],"mappings":"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"}

package/dist/artifacts.js

@@ -27,23 +27,11 @@
  * only `downloadArtifacts` touches a filesystem.
  */
 import { ApiResponseError, ArtifactAuthenticationError, ArtifactFetchError, ArtifactOperationError, RunFailedError, RunStillRunningError, ScopeUnavailableError, } from "./errors.js";
+import { argumentInvalidProblem, responseUnreadableProblem } from "./errors.js";
+import { buildProblem } from "mthds/protocol";
 import { absenceCause, loadNodeHost } from "./node-host.js";
 import { MAX_TIMER_DELAY_MS, isTimerDelay } from "./timers.js";
 // ── Constants ────────────────────────────────────────────────────────
-/**
- * The verdict of an argument the artifact operations refuse (a `scope`, a bound, a location):
- * the caller's to fix, and asking again unchanged cannot pass.
- */
-const ARGUMENT_REFUSED = {
-    verdict: { errorDomain: "input", retryable: false },
-};
-/**
- * The verdict of an environment that cannot hold a download (a runtime with no filesystem, a
- * directory that cannot be created): someone changes the environment first.
- */
-const ENVIRONMENT_REFUSED = {
-    verdict: { errorDomain: "config", retryable: false },
-};
 /** The scheme of a durable storage reference. */
 export const PIPELEX_STORAGE_SCHEME = "pipelex-storage://";
 /**
@@ -283,14 +271,14 @@ export function artifactFilename(location, contentType, scope) {
     const loose = location;
     const uri = loose?.uri;
     if (typeof uri !== "string") {
-        throw new ArtifactOperationError(`artifactFilename needs a location carrying its reference as a string "uri"; got ${String(uri)}.`, ARGUMENT_REFUSED);
+        throw new ArtifactOperationError(`artifactFilename needs a location carrying its reference as a string "uri"; got ${String(uri)}.`, { problem: argumentInvalidProblem("location", "not_a_location") });
     }
     const foundAt = loose?.found_at;
     const first = Array.isArray(foundAt) ? foundAt[0] : undefined;
     const segments = typeof first === "string" ? parsePath(first) : undefined;
     if (segments === undefined) {
         throw new ArtifactOperationError(`artifactFilename needs a location whose first "found_at" entry is a path such as ` +
-            `"$.items[0].url"; got ${typeof first === "string" ? JSON.stringify(first) : String(first)}.`, ARGUMENT_REFUSED);
+            `"$.items[0].url"; got ${typeof first === "string" ? JSON.stringify(first) : String(first)}.`, { problem: argumentInvalidProblem("location", "not_a_path") });
     }
     return filenameFor(segments, uri, contentType, scope);
 }
@@ -360,7 +348,7 @@ function extensionOf(name) {
 }
 function requireScope(scope) {
     if (scope !== "main_stuff" && scope !== "working_memory") {
-        throw new ArtifactOperationError(`"scope" must be "main_stuff" or "working_memory", got ${String(scope)}.`, ARGUMENT_REFUSED);
+        throw new ArtifactOperationError(`"scope" must be "main_stuff" or "working_memory", got ${String(scope)}.`, { problem: argumentInvalidProblem("scope", "unknown_value") });
     }
 }
 // ── resolveArtifacts ─────────────────────────────────────────────────
@@ -384,7 +372,7 @@ export async function resolveArtifacts(client, uris, options = {}) {
         if (!Array.isArray(resolved) || resolved.length !== chunk.length) {
             throw new ArtifactOperationError(`The bulk resolve route answered ${Array.isArray(resolved) ? resolved.length : "no"} ` +
                 `item(s) for ${chunk.length} reference(s) — a malformed answer, so no reference can be ` +
-                "matched to its verdict.");
+                "matched to its verdict.", { problem: responseUnreadableProblem(200) });
         }
         items.push(...resolved);
     }
@@ -430,13 +418,15 @@ function fetchBounds(options) {
     // A longer delay overflows the timer, which then fires at once as a false timeout.
     if (!isTimerDelay(timeoutMs)) {
         throw new ArtifactOperationError(`"timeoutMs" must be a positive number no larger than ${MAX_TIMER_DELAY_MS}, got ` +
-            `${String(timeoutMs)}.`, ARGUMENT_REFUSED);
+            `${String(timeoutMs)}.`, { problem: argumentInvalidProblem("timeoutMs", "not_positive") });
     }
     return { maxBytes, timeoutMs, allowHttp: options.allowHttp ?? false, signal: options.signal };
 }
 function requirePositive(name, value) {
     if (!Number.isFinite(value) || value <= 0) {
-        throw new ArtifactOperationError(`"${name}" must be a positive number, got ${String(value)}.`, ARGUMENT_REFUSED);
+        throw new ArtifactOperationError(`"${name}" must be a positive number, got ${String(value)}.`, {
+            problem: argumentInvalidProblem(name, "not_positive"),
+        });
     }
 }
 /**
@@ -529,7 +519,10 @@ async function fetchResolvedUrl(uri, downloadUrl, bounds, dispatcher, release) {
     }
     const failure = (err) => {
         if (timedOut) {
-            return new ArtifactFetchError(`Fetching the artifact timed out after ${bounds.timeoutMs}ms.`, uri, "timeout", undefined, { cause: err });
+            return new ArtifactFetchError(`Fetching the artifact timed out after ${bounds.timeoutMs}ms.`, uri, "timeout", undefined, {
+                cause: err,
+                problem: buildProblem("client.timeout", { seconds: bounds.timeoutMs / 1000 }),
+            });
         }
         // The caller's reason, not `err`: a browser rejects the fetch, and errors a body
         // cut short, with a generic AbortError rather than the signal's reason.
@@ -537,7 +530,7 @@ async function fetchResolvedUrl(uri, downloadUrl, bounds, dispatcher, release) {
             return userSignal.reason;
         if (err instanceof ArtifactFetchError)
             return err;
-        return new ArtifactFetchError(`The artifact could not be fetched: ${err instanceof Error ? err.message : String(err)}.`, uri, "network", undefined, { cause: err });
+        return new ArtifactFetchError(`The artifact could not be fetched: ${err instanceof Error ? err.message : String(err)}.`, uri, "network", undefined, { cause: err, problem: buildProblem("client.unreachable", { base_url: url.origin }) });
     };
     if (controller.signal.aborted) {
         // Already aborted before the request: the same outcome `fetch` would give,
@@ -570,7 +563,7 @@ async function fetchResolvedUrl(uri, downloadUrl, bounds, dispatcher, release) {
     if (Number.isFinite(declared) && declared > bounds.maxBytes) {
         await discard(response);
         releaseOnce();
-        throw new ArtifactFetchError(`The artifact is ${formatMiB(declared)}, over the ${formatMiB(bounds.maxBytes)} cap.`, uri, "too_large", response.status);
+        throw new ArtifactFetchError(`The artifact is ${formatMiB(declared)}, over the ${formatMiB(bounds.maxBytes)} cap.`, uri, "too_large", response.status, { problem: downloadLimitProblem(bounds.maxBytes) });
     }
     if (response.body === null) {
         releaseOnce();
@@ -612,7 +605,7 @@ async function fetchResolvedUrl(uri, downloadUrl, bounds, dispatcher, release) {
             if (total > bounds.maxBytes) {
                 await upstream.cancel().catch(() => undefined);
                 releaseOnce();
-                streamController.error(new ArtifactFetchError(`The artifact crossed the ${formatMiB(bounds.maxBytes)} cap mid-stream.`, uri, "too_large", response.status));
+                streamController.error(new ArtifactFetchError(`The artifact crossed the ${formatMiB(bounds.maxBytes)} cap mid-stream.`, uri, "too_large", response.status, { problem: downloadLimitProblem(bounds.maxBytes) }));
                 return;
             }
             streamController.enqueue(chunk.value);
@@ -654,6 +647,10 @@ function decodedHeaders(headers) {
     decoded.delete("content-length");
     return decoded;
 }
+/** `client.download_limit_exceeded`, naming the cap in bytes. */
+function downloadLimitProblem(maxBytes) {
+    return buildProblem("client.download_limit_exceeded", { limit: maxBytes });
+}
 function statusRefusal(uri, response) {
     const status = response.status;
     // A browser hands a manual redirect back as an opaque-redirect response, whose
@@ -769,7 +766,7 @@ async function readCompletedResults(client, runId, scope, signal) {
             (state.retry_after_seconds != null ? ` — retry in ${state.retry_after_seconds}s.` : "."), runId, state.retry_after_seconds);
     }
     if (state.state === "failed") {
-        throw new RunFailedError(state.message, runId, state.status, { error: state.error });
+        throw new RunFailedError(state.message, runId, state.status, { problem: state.problem });
     }
     return state.result;
 }
@@ -801,7 +798,10 @@ export async function downloadArtifacts(client, request) {
         throw new ArtifactOperationError(loaded.reason === null
             ? "downloadArtifacts writes to a filesystem and is Node-only. In another runtime, resolve " +
                 "with resolveArtifacts or stream with fetchArtifact instead."
-            : `downloadArtifacts cannot write to the filesystem: ${loaded.reason}`, { ...ENVIRONMENT_REFUSED, ...absenceCause(loaded) });
+            : `downloadArtifacts cannot write to the filesystem: ${loaded.reason}`, {
+            ...absenceCause(loaded),
+            problem: buildProblem("runtime.unsupported", { capability: "writing to the filesystem" }),
+        });
     }
     const host = loaded.host;
     const scope = request.scope ?? "main_stuff";
@@ -809,7 +809,7 @@ export async function downloadArtifacts(client, request) {
     const concurrency = request.concurrency ?? DEFAULT_DOWNLOAD_CONCURRENCY;
     const maxTotalBytes = request.maxTotalBytes ?? DEFAULT_DOWNLOAD_MAX_TOTAL_BYTES;
     if (!Number.isInteger(concurrency) || concurrency < 1) {
-        throw new ArtifactOperationError(`"concurrency" must be a positive integer, got ${String(concurrency)}.`, ARGUMENT_REFUSED);
+        throw new ArtifactOperationError(`"concurrency" must be a positive integer, got ${String(concurrency)}.`, { problem: argumentInvalidProblem("concurrency", "not_positive") });
     }
     requirePositive("maxTotalBytes", maxTotalBytes);
     const bounds = fetchBounds(request);
@@ -817,7 +817,7 @@ export async function downloadArtifacts(client, request) {
     const hasResults = request.results != null;
     if (hasRunId === hasResults) {
         throw new ArtifactOperationError("downloadArtifacts takes exactly one of `run_id` (the results are re-read) or `results` " +
-            "(a RunResults in hand).", ARGUMENT_REFUSED);
+            "(a RunResults in hand).", { problem: argumentInvalidProblem("run_id", "not_exactly_one_selector") });
     }
     const results = hasResults
         ? request.results
@@ -845,7 +845,10 @@ export async function downloadArtifacts(client, request) {
         await fs.mkdir(dir, { recursive: true });
     }
     catch (cause) {
-        throw new ArtifactOperationError(`The download directory "${dir}" cannot be created or used: ${cause instanceof Error ? cause.message : String(cause)}.`, { cause, ...ENVIRONMENT_REFUSED });
+        throw new ArtifactOperationError(`The download directory "${dir}" cannot be created or used: ${cause instanceof Error ? cause.message : String(cause)}.`, {
+            cause,
+            problem: buildProblem("client.write_failed", { path: dir, reason: osErrorReason(cause) }),
+        });
     }
     // Dense, never sparse: `map` skips the holes of `new Array(n)`, and the verdict
     // must name every reference, reached or not.
@@ -1061,15 +1064,25 @@ function assembleVerdict(scope, artifacts, aborted) {
         verdict.aborted = true;
     return verdict;
 }
-/** An item's `[code, detail]` for an error thrown while fetching or reading it. */
+/**
+ * An item's `[code, detail]` for an error thrown while fetching or reading it: the fetch's own
+ * reason for an `ArtifactFetchError`, `aborted` for the caller's abort, and `unknown` for any other
+ * error, which is no network failure but a fault the SDK cannot place, such as a defect of its own
+ * or of the caller's code, so it is never read as one a retry can pass.
+ */
 function classifyFailure(err, signal) {
     if (err instanceof ArtifactFetchError)
-        return [err.code, err.message];
+        return [err.reason, err.message];
     if (signal?.aborted === true)
         return ["aborted", "The download was aborted while this artifact was being fetched."];
     return [
-        "network",
+        "unknown",
         `The artifact could not be read: ${err instanceof Error ? err.message : String(err)}.`,
     ];
 }
+/** Why a directory could not be made, as the operating system's code (`EACCES`), or `unwritable`. */
+function osErrorReason(cause) {
+    const code = cause?.code;
+    return typeof code === "string" && /^[A-Z][A-Z0-9_]*$/.test(code) ? code : "unwritable";
+}
 //# sourceMappingURL=artifacts.js.map