@pipelex/sdk 0.30.0 → 0.33.0

package/dist/client.js

@@ -3,7 +3,8 @@
 // client and the MTHDS runners cannot disagree about what they reject.
 import { assertExclusiveRunSources, hasBundlePayload, parseMethodFiles, serializeMethodFiles, } from "mthds/protocol";
 import { assertArtifactSelection, assertWaitOptions, pollUntilResult, selectionIncludesMainStuff, } from "./runs.js";
-import { ApiResponseError, ApiUnreachableError, EmptyMethodSourceError, MissingMainStuffError, PipelineExecuteTimeoutError, PipelineRequestError, RunLifecycleUnavailableError, RunStillRunningError, } from "./errors.js";
+import { ApiResponseError, ApiUnreachableError, EmptyMethodSourceError, MissingMainStuffError, PagingNotTerminatingError, PipelineExecuteTimeoutError, PipelineRequestError, RequestArgumentError, RunLifecycleUnavailableError, RunStillRunningError, } from "./errors.js";
+import { isPlainObject, isValidationItem, readFieldError, readMigration, readProviderMetadata, readRunErrorReport, } from "./error-models.js";
 import { methodSourceToContents } from "./method-source.js";
 import { buildUserAgent } from "./user-agent.js";
 import { uploadFile as uploadFileImpl } from "./upload.js";
@@ -44,10 +45,22 @@ const VALIDATE_MARKDOWN_RENDER_FORMAT = "markdown";
  * `RunLifecycleUnavailableError` on the first poll.
  */
 const BARE_RUNNER_IMPLEMENTATION = "pipelex-api";
-/** Parse a wire method into the public shape (`python` → `MethodFile[]`). */
-function methodDataFromWire(wire) {
+/**
+ * Parse a wire method into the public shape (`python` → `MethodFile[]`). A stored `python` that
+ * is not the serialized `[{ name, content }]` list is server data the SDK cannot read, not a
+ * caller's argument, so `mthds`'s refusal is handed to `unreadable`, which builds the error to
+ * throw from the answer that carried it.
+ */
+function methodDataFromWire(wire, unreadable) {
     const { python, ...rest } = wire;
-    return python == null ? rest : { ...rest, python: parseMethodFiles(python) };
+    if (python == null)
+        return rest;
+    try {
+        return { ...rest, python: parseMethodFiles(python) };
+    }
+    catch (err) {
+        throw unreadable(err);
+    }
 }
 /**
  * Serialize a write payload for the wire. `python` is three-way: OMITTED stays
@@ -82,11 +95,12 @@ export class PipelexApiClient {
         // this constructor and must be held to that rule, or a path-prefixed value
         // (e.g. `.../v1`) composes as `/v1/v1/...` and fails with a misleading
         // endpoint error instead of a clear base-URL one. Trailing slashes are
-        // stripped first; a remaining path/query/fragment/credentials is rejected.
+        // stripped first; a remaining path/query/fragment/credentials is rejected. The
+        // refusal is `config`: the value typically comes from PIPELEX_BASE_URL, the environment.
         if (!isValidBaseUrl(normalizedBaseUrl)) {
-            throw new PipelineRequestError(`Invalid API base URL "${normalizedBaseUrl}": must be host-only ` +
+            throw new RequestArgumentError(`Invalid API base URL "${normalizedBaseUrl}": must be host-only ` +
                 `(http/https, no path, query, fragment, or credentials). Endpoints ` +
-                `compose as {base}/v1/{endpoint}.`);
+                `compose as {base}/v1/{endpoint}.`, { verdict: { errorDomain: "config", retryable: false } });
         }
         this.baseUrl = normalizedBaseUrl;
         this.originUrl = new URL("/", this.baseUrl).origin;
@@ -182,25 +196,6 @@ export class PipelexApiClient {
             body,
         };
     }
-    /**
-     * Issue a request and parse the JSON body, throwing a plain `Error` on a non-2xx
-     * response. Used only by `health` — the origin-level liveness probe, which sits
-     * outside `/v1` and outside the RFC 7807 error taxonomy the `/v1` routes share.
-     * Every `/v1` route goes through a helper that maps its problem body to the typed
-     * `ApiResponseError` instead.
-     */
-    async requestJson(method, url, body) {
-        const res = await fetch(url, {
-            method,
-            headers: this.requestHeaders(body !== undefined),
-            body: body !== undefined ? JSON.stringify(body) : undefined,
-        });
-        if (!res.ok) {
-            const text = await res.text().catch(() => "");
-            throw new Error(`API ${method} ${url} failed (${res.status}): ${text || res.statusText}`);
-        }
-        return res.json();
-    }
     /**
      * Issue a Pipelex-product request (`/v1/me`, `/v1/methods`, `/v1/billing/*`,
      * …) and parse its JSON body, mapping a non-2xx response to the typed
@@ -210,6 +205,59 @@ export class PipelexApiClient {
      * timeout, not the blocking-execute ceiling.
      */
     async requestProduct(method, endpoint, body, options = {}) {
+        const res = await this.requestProductAnswer(method, endpoint, body, options);
+        return (res.body ? this.readAnswer(method, endpoint, res) : undefined);
+    }
+    /**
+     * A product request whose answer is an object the SDK or its caller reads before anything else
+     * — a bulk resolution's `items`, a run record's `error`, an upload grant's `url`. Unlike
+     * `requestProduct`, an empty
+     * 2xx is no answer here: it and a body that is not a JSON object throw the `ApiResponseError`
+     * of an answer the SDK cannot read (see `readObjectAnswerAt`).
+     */
+    async requestProductObject(method, endpoint, body, options = {}) {
+        const res = await this.requestProductAnswer(method, endpoint, body, options);
+        return this.readObjectAnswer(method, endpoint, res);
+    }
+    /**
+     * A methods-catalog route answering one stored method (`getMethod`, `createMethod`,
+     * `updateMethod`), parsed into the public shape. A stored `mthds` that is neither a string nor
+     * absent (`null` stays "no source", which `getMethodClosure` reports), and a stored `python`
+     * the SDK cannot parse, are an answer it cannot read, so each throws an `ApiResponseError` built
+     * from that answer, the latter with `mthds`'s refusal as `cause`: `runtime`, not retryable,
+     * since no change to the call fixes it.
+     */
+    async requestMethodData(method, endpoint, body) {
+        const res = await this.requestProductAnswer(method, endpoint, body);
+        const wire = this.readObjectAnswer(method, endpoint, res);
+        const source = wire.mthds;
+        if (source != null && typeof source !== "string") {
+            throw this.unreadableAnswer(method, `/${API_PREFIX}/${endpoint}`, res, "a stored method whose `mthds` field is not a string");
+        }
+        return methodDataFromWire(wire, (cause) => this.unreadableAnswer(method, `/${API_PREFIX}/${endpoint}`, res, "a stored method whose `python` field could not be read", cause));
+    }
+    /**
+     * One page of a cursor-paged product route (`listMethods`, `listRuns`), read as the platform
+     * always serializes it: `items` an array, `next_cursor` a string or `null`. A page breaking
+     * either is an answer the SDK cannot read, so it throws the `ApiResponseError` `unreadableAnswer`
+     * builds, `runtime` and not retryable, rather than handing the iterators a page they cannot
+     * walk: `items` that is not iterable, or a missing cursor that is neither the end nor a next
+     * page, which `iterateRuns` would follow forever.
+     */
+    async requestPage(endpoint) {
+        const res = await this.requestProductAnswer("GET", endpoint, undefined);
+        const page = this.readObjectAnswer("GET", endpoint, res);
+        const { items, next_cursor: nextCursor } = page;
+        if (!Array.isArray(items)) {
+            throw this.unreadableAnswer("GET", `/${API_PREFIX}/${endpoint}`, res, "a page whose `items` is not an array");
+        }
+        if (nextCursor !== null && typeof nextCursor !== "string") {
+            throw this.unreadableAnswer("GET", `/${API_PREFIX}/${endpoint}`, res, "a page whose `next_cursor` is neither a string nor null");
+        }
+        return { items: items, nextCursor };
+    }
+    /** Issue a product request and return its 2xx answer, a non-2xx thrown as `ApiResponseError`. */
+    async requestProductAnswer(method, endpoint, body, options = {}) {
         const res = await this.requestRaw(method, this.url(endpoint), {
             body,
             timeoutMs: POLL_REQUEST_TIMEOUT_MS,
@@ -218,14 +266,64 @@ export class PipelexApiClient {
         if (res.status < 200 || res.status >= 300) {
             this.throwApiResponseError(method, endpoint, res);
         }
-        return (res.body ? JSON.parse(res.body) : undefined);
+        return res;
     }
     throwApiResponseError(method, endpoint, res) {
+        this.throwApiResponseErrorAt(method, `/${API_PREFIX}/${endpoint}`, res);
+    }
+    /** The JSON body of a `/v1` route's 2xx answer; see `readAnswerAt`. */
+    readAnswer(method, endpoint, res) {
+        return this.readAnswerAt(method, `/${API_PREFIX}/${endpoint}`, res);
+    }
+    /** The JSON object body of a `/v1` route's 2xx answer; see `readObjectAnswerAt`. */
+    readObjectAnswer(method, endpoint, res) {
+        return this.readObjectAnswerAt(method, `/${API_PREFIX}/${endpoint}`, res);
+    }
+    /**
+     * The JSON body of a 2xx answer, naming the route by its `path` from the origin as a refusal
+     * does. A body that is not JSON, an empty one included, is an answer the SDK cannot read, so it
+     * throws the `ApiResponseError` `unreadableAnswer` builds, with the parse failure as `cause`.
+     * The one place a success body is parsed.
+     */
+    readAnswerAt(method, path, res) {
+        try {
+            return JSON.parse(res.body);
+        }
+        catch (err) {
+            throw this.unreadableAnswer(method, path, res, res.body ? "a body that is not JSON" : "an empty body where JSON was expected", err);
+        }
+    }
+    /**
+     * The JSON body of a 2xx answer from a route that answers an object, read as `readAnswerAt`
+     * reads it. A body that is JSON but not an object — `null`, a number, a string, an array — is
+     * an answer the SDK cannot read either, and throws the same `ApiResponseError`, with no `cause`.
+     */
+    readObjectAnswerAt(method, path, res) {
+        const answer = this.readAnswerAt(method, path, res);
+        if (!isPlainObject(answer)) {
+            throw this.unreadableAnswer(method, path, res, "a body that is not an object");
+        }
+        return answer;
+    }
+    /**
+     * The `ApiResponseError` of a 2xx answer the SDK cannot read, its message
+     * `API <method> <path> answered <status> with <what>`: the answer's status, its raw text as
+     * `responseBody`, no problem member but the `X-Request-ID` header, the failure that made it
+     * unreadable as `cause`, and the verdict the fallback gives a 2xx, `runtime` and not retryable.
+     */
+    unreadableAnswer(method, path, res, what, cause) {
+        return new ApiResponseError(`API ${method} ${path} answered ${res.status} with ${what}`, this.baseUrl, res.status, res.statusText, res.body, undefined, undefined, undefined, undefined, { cause, problem: { requestId: nonEmptyHeader(res.headers, REQUEST_ID_HEADER) } });
+    }
+    /**
+     * Throw the `ApiResponseError` of a non-2xx answer, naming the route by its `path` from the
+     * origin (`/v1/...`, or `/health` for the liveness probe).
+     */
+    throwApiResponseErrorAt(method, path, res) {
         const { errorType, serverMessage, validationErrors, code, problem, document } = parseErrorBody(res.body);
         // The body's `request_id` wins; the header is the fallback for a response whose body
         // carries none (a gateway error page, a non-problem body).
         const requestId = problem.requestId ?? nonEmptyHeader(res.headers, REQUEST_ID_HEADER);
-        throw new ApiResponseError(`API ${method} /${API_PREFIX}/${endpoint} failed (${res.status}): ${serverMessage ?? (res.body || res.statusText)}`, this.baseUrl, res.status, res.statusText, res.body, errorType, serverMessage, validationErrors, code, { problem: { ...problem, requestId }, problemDocument: document });
+        throw new ApiResponseError(`API ${method} ${path} failed (${res.status}): ${serverMessage ?? (res.body || res.statusText)}`, this.baseUrl, res.status, res.statusText, res.body, errorType, serverMessage, validationErrors, code, { problem: { ...problem, requestId }, problemDocument: document });
     }
     /**
      * Translate a "route absent" 404 (a bare pipelex-api with no platform block)
@@ -267,9 +365,24 @@ export class PipelexApiClient {
             "running server-side. Poll its results (hosted) or use start().", runId, parseRetryAfter(res.headers), res.headers.get("location"));
     }
     // ── Health ────────────────────────────────────────────────────────
+    /**
+     * The origin-level liveness probe — `GET /health`, which sits at the origin, NOT under the
+     * `/v1` prefix. A bare runner serves it; a hosted origin answers `/v1/health` instead, so
+     * there this throws.
+     *
+     * It goes through the same transport as every route: an unreachable origin is an
+     * `ApiUnreachableError`, and a non-2xx answer an `ApiResponseError` whose verdict the SDK's
+     * fallback reads from the status, since the probe answers no problem document. So is a 2xx
+     * whose body is not a JSON object, such as a gateway's HTML page: `runtime`, not retryable.
+     */
     async health() {
-        // `/health` is origin-level, NOT under the `/v1` prefix.
-        return this.requestJson("GET", `${this.originUrl}/health`);
+        const res = await this.requestRaw("GET", `${this.originUrl}/health`, {
+            timeoutMs: POLL_REQUEST_TIMEOUT_MS,
+        });
+        if (res.status < 200 || res.status >= 300) {
+            this.throwApiResponseErrorAt("GET", "/health", res);
+        }
+        return this.readObjectAnswerAt("GET", "/health", res);
     }
     // ── Protocol surface ─────────────────────────────────────────────────
     /**
@@ -295,9 +408,9 @@ export class PipelexApiClient {
             Object.keys(api).length === 0 &&
             Object.keys(hosted).length === 0 &&
             Object.keys(extensions).length === 0) {
-            throw new PipelineRequestError("Either pipe_code, mthds_contents, a method bundle (files/bundle_b64), a method_ref, a hosted method_id or a server-specific extension arg (extra) must be provided to execute().");
+            throw new RequestArgumentError("Either pipe_code, mthds_contents, a method bundle (files/bundle_b64), a method_ref, a hosted method_id or a server-specific extension arg (extra) must be provided to execute().");
         }
-        assertExclusiveRunSources(options);
+        assertRunSourcesExclusive(options);
         assertMethodRefPairsWithNothing(options);
         const request = {
             pipe_code: options.pipe_code,
@@ -323,7 +436,7 @@ export class PipelexApiClient {
             }
             // Wrap the base result in the enriched subtype (adds the `.main_stuff` accessor; the
             // `main_stuff_name` extension + working memory ride `pipe_output`).
-            return new PipelexExecuteResult(JSON.parse(res.body));
+            return new PipelexExecuteResult(this.readObjectAnswer("POST", "execute", res));
         }
         catch (err) {
             if (err instanceof RunStillRunningError)
@@ -361,9 +474,9 @@ export class PipelexApiClient {
             Object.keys(api).length === 0 &&
             Object.keys(hosted).length === 0 &&
             Object.keys(extensions).length === 0) {
-            throw new PipelineRequestError("Either pipe_code, mthds_contents, a method bundle (files/bundle_b64), a method_ref, a hosted method_id or a server-specific extension arg (extra) must be provided to start().");
+            throw new RequestArgumentError("Either pipe_code, mthds_contents, a method bundle (files/bundle_b64), a method_ref, a hosted method_id or a server-specific extension arg (extra) must be provided to start().");
         }
-        assertExclusiveRunSources(options);
+        assertRunSourcesExclusive(options);
         assertMethodRefPairsWithNothing(options);
         // `?? undefined` so JSON.stringify drops absent fields from the wire body.
         const request = {
@@ -401,7 +514,7 @@ export class PipelexApiClient {
         if (res.status < 200 || res.status >= 300) {
             this.throwApiResponseError("POST", "start", res);
         }
-        return JSON.parse(res.body);
+        return this.readObjectAnswer("POST", "start", res);
     }
     /**
      * Parse, validate, and dry-run an MTHDS bundle — `POST /v1/validate`.
@@ -480,19 +593,19 @@ export class PipelexApiClient {
             // A selector object. The illegal shapes are compile errors for typed
             // callers (`ValidateMethodSelector` pins the other key to `never`); the
             // runtime checks back them for untyped (JS) callers — a typed
-            // `PipelineRequestError`, never a native TypeError off a null source —
+            // `RequestArgumentError`, never a native TypeError off a null source —
             // mirroring the server's strict tooling XOR instead of silently picking.
             if (source === null || source === undefined || typeof source !== "object") {
-                throw new PipelineRequestError("validate() takes inline contents (a string[]) or a method selector object " +
+                throw new RequestArgumentError("validate() takes inline contents (a string[]) or a method selector object " +
                     "({ method_ref } or { method_id }).");
             }
             const methodRef = nonEmptyString(source.method_ref);
             const methodId = nonEmptyString(source.method_id);
             if ((methodRef === undefined) === (methodId === undefined)) {
-                throw new PipelineRequestError("validate() takes exactly one method selector: inline contents, { method_ref }, or { method_id }.");
+                throw new RequestArgumentError("validate() takes exactly one method selector: inline contents, { method_ref }, or { method_id }.");
             }
             if (mthdsSources !== undefined) {
-                throw new PipelineRequestError("mthds_sources labels inline mthds_contents; a method_ref / method_id validation gets " +
+                throw new RequestArgumentError("mthds_sources labels inline mthds_contents; a method_ref / method_id validation gets " +
                     "its source labels from the package's (or the stored method's) real file names.");
             }
             if (methodRef !== undefined)
@@ -512,7 +625,7 @@ export class PipelexApiClient {
         if (res.status < 200 || res.status >= 300) {
             this.throwApiResponseError("POST", "validate", res);
         }
-        return JSON.parse(res.body);
+        return this.readObjectAnswer("POST", "validate", res);
     }
     /**
      * Validate paired MTHDS files while preserving URI attribution for diagnostics.
@@ -524,7 +637,7 @@ export class PipelexApiClient {
      */
     async validateFiles(files, options = {}) {
         if (files.length === 0) {
-            throw new PipelineRequestError("At least one MTHDS file must be provided to validateFiles().");
+            throw new RequestArgumentError("At least one MTHDS file must be provided to validateFiles().");
         }
         const mthdsContents = files.map((file) => file.content);
         const hasAnyUri = files.some((file) => file.uri !== undefined);
@@ -638,7 +751,7 @@ export class PipelexApiClient {
         if (res.status < 200 || res.status >= 300) {
             this.throwApiResponseError("POST", endpoint, res);
         }
-        return JSON.parse(res.body);
+        return this.readObjectAnswer("POST", endpoint, res);
     }
     /** The model deck the runner can route to — `GET /v1/models[?type=]`. */
     async models(category) {
@@ -649,7 +762,7 @@ export class PipelexApiClient {
         if (res.status < 200 || res.status >= 300) {
             this.throwApiResponseError("GET", endpoint, res);
         }
-        return JSON.parse(res.body);
+        return this.readObjectAnswer("GET", endpoint, res);
     }
     /**
      * Protocol + implementation versions — `GET /v1/version` (always public).
@@ -662,7 +775,7 @@ export class PipelexApiClient {
         if (res.status < 200 || res.status >= 300) {
             this.throwApiResponseError("GET", "version", res);
         }
-        return JSON.parse(res.body);
+        return this.readObjectAnswer("GET", "version", res);
     }
     // ── Crate extensions (Pipelex API — `/v1/resolve`, `/v1/codegen`, `/v1/pipe-io`) ──
     //
@@ -776,8 +889,10 @@ export class PipelexApiClient {
      * Self-healing: a finished-but-unrecorded run resolves to its true terminal
      * status on read. `degraded: true` means Temporal was unreachable and
      * `status` is the last-known value; `retry_after_seconds` carries the
-     * server's backoff hint when present. Throws `RunLifecycleUnavailableError`
-     * when the lifecycle routes are absent (a bare runner).
+     * server's backoff hint when present. A failed run's stored report, `error`,
+     * is checked field by field (see `RunErrorReport`). Throws
+     * `RunLifecycleUnavailableError` when the lifecycle routes are absent (a bare
+     * runner).
      */
     async getRunStatus(runId, options = {}) {
         const endpoint = `${RUNS}/${encodeURIComponent(runId)}/status`;
@@ -790,7 +905,7 @@ export class PipelexApiClient {
         if (res.status < 200 || res.status >= 300) {
             this.throwApiResponseError("GET", endpoint, res);
         }
-        const run = JSON.parse(res.body);
+        const run = withCheckedReport(this.readObjectAnswer("GET", endpoint, res));
         const retryAfter = parseRetryAfter(res.headers);
         return retryAfter !== null ? { ...run, retry_after_seconds: retryAfter } : run;
     }
@@ -843,7 +958,7 @@ export class PipelexApiClient {
         if (res.status < 200 || res.status >= 300) {
             this.throwApiResponseError("GET", endpoint, res);
         }
-        const result = JSON.parse(res.body);
+        const result = this.readObjectAnswer("GET", endpoint, res);
         if (selectionIncludesMainStuff(options.artifacts) && result.main_stuff == null) {
             throw new MissingMainStuffError(`Completed run '${runId}' returned no main stuff — a completed run always delivers a main stuff.`, runId);
         }
@@ -944,8 +1059,7 @@ export class PipelexApiClient {
         if (query.cursor !== undefined)
             params.set("cursor", query.cursor);
         const suffix = params.toString();
-        const page = await this.requestProduct("GET", suffix ? `methods?${suffix}` : "methods");
-        return { items: page.items, nextCursor: page.next_cursor };
+        return this.requestPage(suffix ? `methods?${suffix}` : "methods");
     }
     /**
      * Every method in the catalog, streamed — follows the cursor for you.
@@ -997,16 +1111,15 @@ export class PipelexApiClient {
                 // partial answer with no error is back to the original bug one layer
                 // up; an error is the only honest response to a server that will not
                 // finish. Unreachable on real data — see MAX_PAGES.
-                throw new Error(`listMethods did not terminate after ${MAX_PAGES} pages; refusing to keep paging. ` +
-                    `This is a server-side fault, not a coverage limit.`);
+                throw new PagingNotTerminatingError(`listMethods did not terminate after ${MAX_PAGES} pages; refusing to keep paging. ` +
+                    `This is a server-side fault, not a coverage limit.`, MAX_PAGES);
             }
             cursor = page.nextCursor;
         }
     }
     /** Fetch one method by id — `GET /v1/methods/{id}`. */
     async getMethod(methodId) {
-        const wire = await this.requestProduct("GET", `methods/${encodeURIComponent(methodId)}`);
-        return methodDataFromWire(wire);
+        return this.requestMethodData("GET", `methods/${encodeURIComponent(methodId)}`);
     }
     /**
      * Resolve a stored method's id into its runnable MTHDS closure — a client-side
@@ -1038,13 +1151,11 @@ export class PipelexApiClient {
     }
     /** Create a method — `POST /v1/methods`. */
     async createMethod(input) {
-        const wire = await this.requestProduct("POST", "methods", methodWriteToWire(input));
-        return methodDataFromWire(wire);
+        return this.requestMethodData("POST", "methods", methodWriteToWire(input));
     }
     /** Replace a method (rename = changed `name`) — `PUT /v1/methods/{id}`. */
     async updateMethod(methodId, input) {
-        const wire = await this.requestProduct("PUT", `methods/${encodeURIComponent(methodId)}`, methodWriteToWire(input));
-        return methodDataFromWire(wire);
+        return this.requestMethodData("PUT", `methods/${encodeURIComponent(methodId)}`, methodWriteToWire(input));
     }
     /**
      * Erase a method and everything it produced — `DELETE /v1/methods/{id}`.
@@ -1149,7 +1260,7 @@ export class PipelexApiClient {
      * only: a deployment without the route answers a `404` `ApiResponseError`.
      */
     async resolveStorageUrls(input, options = {}) {
-        return this.requestProduct("POST", "resolve-storage-url/bulk", input, options);
+        return this.requestProductObject("POST", "resolve-storage-url/bulk", input, options);
     }
     /**
      * Resolve a whole list of `pipelex-storage://` references through the bulk
@@ -1182,9 +1293,18 @@ export class PipelexApiClient {
     async downloadArtifacts(request) {
         return downloadArtifactsImpl(this, request);
     }
-    /** Upload a base64 file — `POST /v1/upload`. */
+    /**
+     * Upload a base64 file — `POST /v1/upload`. An answer with no non-empty string `uri` names no
+     * stored file, so it is an answer the SDK cannot read: an `ApiResponseError`, `runtime` and
+     * not retryable, which `uploadFile` wraps as an `UploadTransportError` with code `unexpected`.
+     */
     async upload(input) {
-        return this.requestProduct("POST", "upload", input);
+        const res = await this.requestProductAnswer("POST", "upload", input);
+        const uploaded = this.readObjectAnswer("POST", "upload", res);
+        if (typeof uploaded.uri !== "string" || uploaded.uri === "") {
+            throw this.unreadableAnswer("POST", `/${API_PREFIX}/upload`, res, "an answer with no string `uri`");
+        }
+        return uploaded;
     }
     /**
      * Request a grant to upload one file straight to storage — `POST /v1/upload/grant`.
@@ -1203,7 +1323,7 @@ export class PipelexApiClient {
      * `docs/input-preparation.md`.
      */
     async requestUploadGrant(input, options = {}) {
-        return this.requestProduct("POST", "upload/grant", input, options);
+        return this.requestProductObject("POST", "upload/grant", input, options);
     }
     /**
      * Upload one local asset and return its {@link UploadRecord} — the single-asset
@@ -1277,8 +1397,8 @@ export class PipelexApiClient {
             params.set("limit", String(query.limit));
         if (query.cursor !== undefined)
             params.set("cursor", query.cursor);
-        const page = await this.requestProduct("GET", `runs?${params.toString()}`);
-        return { items: page.items, nextCursor: page.next_cursor };
+        const page = await this.requestPage(`runs?${params.toString()}`);
+        return { items: page.items.map(withCheckedReport), nextCursor: page.nextCursor };
     }
     /**
      * Every run of a method, streamed — follows the cursor for you.
@@ -1333,10 +1453,11 @@ export class PipelexApiClient {
      *
      * The ONLY call that returns `mthds_contents` (what the run actually
      * executed) and `inputs`. Kept off the status read, which pollers hit every
-     * few seconds.
+     * few seconds. A failed run's stored report, `error`, is checked field by
+     * field (see `RunErrorReport`).
      */
     async getRunDetail(runId) {
-        return this.requestProduct("GET", `runs/${encodeURIComponent(runId)}`);
+        return withCheckedReport(await this.requestProductObject("GET", `runs/${encodeURIComponent(runId)}`));
     }
     /** Patch a run's status (admin/manual) — `PUT /v1/runs/{id}`. */
     async updateRun(runId, input) {
@@ -1458,7 +1579,7 @@ function buildExtensions(extra) {
     const snapshot = { ...extra };
     const reserved = Object.keys(snapshot).filter((key) => RESERVED_EXTRA_KEYS.has(key));
     if (reserved.length > 0) {
-        throw new PipelineRequestError(`extra carries reserved request args [${reserved.sort().join(", ")}] — pass them as named options instead.`);
+        throw new RequestArgumentError(`extra carries reserved request args [${reserved.sort().join(", ")}] — pass them as named options instead.`);
     }
     const result = {};
     for (const [key, value] of Object.entries(snapshot)) {
@@ -1508,6 +1629,23 @@ function buildHostedRunExtensions(options) {
     const methodId = nonEmptyString(options.method_id);
     return methodId === undefined ? {} : { method_id: methodId };
 }
+/**
+ * The standard's run-source exclusivity check (`assertExclusiveRunSources`: the two bundle
+ * encodings together, or a bundle beside inline contents), its refusal rethrown as a
+ * `RequestArgumentError` with the same message and the standard's error as `cause`, so it carries
+ * a verdict like every other argument the client refuses.
+ */
+function assertRunSourcesExclusive(options) {
+    try {
+        assertExclusiveRunSources(options);
+    }
+    catch (err) {
+        if (err instanceof PipelineRequestError) {
+            throw new RequestArgumentError(err.message, { cause: err });
+        }
+        throw err;
+    }
+}
 /**
  * Enforce the run routes' `method_ref` exclusivity, mirroring the server's own
  * 422s so an illegal pairing fails before anything hits the wire. A
@@ -1528,13 +1666,13 @@ function assertMethodRefPairsWithNothing(options) {
     if (nonEmptyString(options.method_ref) === undefined)
         return;
     if (options.mthds_contents != null && options.mthds_contents.length > 0) {
-        throw new PipelineRequestError("method_ref and inline mthds_contents are mutually exclusive; send one or the other.");
+        throw new RequestArgumentError("method_ref and inline mthds_contents are mutually exclusive; send one or the other.");
     }
     if (options.files != null || options.bundle_b64 != null) {
-        throw new PipelineRequestError("method_ref and a method bundle (bundle_b64 / files) are mutually exclusive; send one or the other.");
+        throw new RequestArgumentError("method_ref and a method bundle (bundle_b64 / files) are mutually exclusive; send one or the other.");
     }
     if (nonEmptyString(options.method_id) !== undefined) {
-        throw new PipelineRequestError("method_ref and method_id are mutually exclusive: an address run carries its own provenance " +
+        throw new RequestArgumentError("method_ref and method_id are mutually exclusive: an address run carries its own provenance " +
             "and takes no run-history linkage id. Send exactly one method selector.");
     }
 }
@@ -1634,21 +1772,31 @@ const REQUEST_ID_HEADER = "x-request-id";
  * `Run finished with status <STATUS>` the platform keeps for exactly this reader, so the status
  * word is recovered from it then; a `409` that yields no known status either way (the one this
  * route answers for a stored result it refuses to read) reads as `FAILED`, and its `detail`
- * still says what happened. The report is relayed whole, as the runner wrote it: an object is
- * taken as the report, anything else reads as no report.
+ * still says what happened. The report is checked field by field by `readRunErrorReport`: an
+ * object is taken as the report, each named field kept when it has its declared type, and
+ * anything that is not an object reads as no report.
  */
 function runResultFailed(runId, body) {
     const { serverMessage, document } = parseErrorBody(body);
     const message = serverMessage ?? "Run finished without a result.";
-    const rawReport = document?.error;
     return {
         state: "failed",
         pipeline_run_id: runId,
         status: knownRunStatus(document?.run_status) ?? statusFromDetail(message) ?? "FAILED",
         message,
-        error: isPlainObject(rawReport) ? rawReport : null,
+        error: readRunErrorReport(document?.error),
     };
 }
+/**
+ * A run record with its stored report checked by `readRunErrorReport`. Only when the record
+ * carries the `error` key, so a server that does not serve it still leaves it absent; a record
+ * that is not an object is returned as it came.
+ */
+function withCheckedReport(record) {
+    if (!isPlainObject(record) || !Object.hasOwn(record, "error"))
+        return record;
+    return { ...record, error: readRunErrorReport(record.error) };
+}
 function knownRunStatus(value) {
     return typeof value === "string" && KNOWN_RUN_STATUSES.includes(value)
         ? value
@@ -1671,8 +1819,9 @@ function statusFromDetail(detail) {
  * on a non-JSON or non-object body.
  *
  * Each typed member is kept only when it has the type the problem document gives it, so a
- * malformed member reads as absent rather than as a wrong value; `document` keeps the decoded
- * object whole, members named or not.
+ * malformed member reads as absent rather than as a wrong value, and the nested members
+ * (`provider_metadata`, `migration`, `validation_errors`, `errors`) are checked field by field as a
+ * stored report's are; `document` keeps the decoded object whole, members named or not.
  */
 function parseErrorBody(body) {
     const empty = {
@@ -1715,10 +1864,10 @@ function parseErrorBody(body) {
         serverMessage = root.message;
     // `validation_errors` rides the problem envelope as a top-level array (the
     // VERBOSE projection of `ErrorReport.validation_errors`, retained under STRICT
-    // too — it describes the caller's own bundle, not server internals). Kept as a
-    // shallow array guard; per-item shape is the typed `ValidationErrorItem` contract.
+    // too — it describes the caller's own bundle, not server internals). Each item is
+    // kept when it is an object with a string `category` and `message`, as on a stored report.
     const validationErrors = Array.isArray(root.validation_errors)
-        ? root.validation_errors
+        ? root.validation_errors.filter(isValidationItem)
         : undefined;
     // The platform's closed native code (`conflict`, `not_found`, …), one-to-one with `type`.
     const code = typeof root.code === "string" ? root.code : undefined;
@@ -1733,19 +1882,18 @@ function parseErrorBody(body) {
         userAction: parseUserAction(root.user_action),
         model: stringMember(root.model),
         provider: stringMember(root.provider),
+        // The nested members are checked one level down by the readers a stored report goes
+        // through, so a misfit field reads as absent here exactly as it does there.
         providerMetadata: isPlainObject(root.provider_metadata)
-            ? root.provider_metadata
+            ? readProviderMetadata(root.provider_metadata)
             : undefined,
-        migration: isPlainObject(root.migration) ? root.migration : undefined,
+        migration: isPlainObject(root.migration) ? readMigration(root.migration) : undefined,
         errors: Array.isArray(root.errors)
-            ? root.errors.filter(isPlainObject)
+            ? root.errors.filter(isPlainObject).map(readFieldError)
             : undefined,
     };
     return { errorType, serverMessage, validationErrors, code, problem, document: root };
 }
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 /** A problem member kept only when it is a non-empty string. */
 function stringMember(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;