@pipelex/sdk 0.32.0 → 0.34.0

package/dist/client.js

@@ -2,8 +2,9 @@
 // source combinations are legal is an invariant of `RunRequest` itself, so this
 // 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 { assertArtifactSelection, assertWaitOptions, pollUntilResult, selectionIncludesMainStuff, throwIfAborted, } from "./runs.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";
@@ -25,6 +26,9 @@ import { MAX_TIMER_DELAY_MS, isTimerDelay } from "./timers.js";
 // cannot fire on real data; it exists only so a server minting fresh cursors
 // forever cannot hang a caller indefinitely.
 const MAX_PAGES = 10_000;
+/** Decoders of an answer's bytes: the strict one tells a body that is not UTF-8. */
+const STRICT_UTF8 = new TextDecoder("utf-8", { fatal: true });
+const LENIENT_UTF8 = new TextDecoder("utf-8");
 /** Hosted default — the client composes every endpoint as `{base}/v1/{endpoint}`. */
 export const DEFAULT_API_BASE_URL = "https://api.pipelex.com";
 // The client composes every endpoint from one origin (PIPELEX_BASE_URL): `{base}/v1/{endpoint}`.
@@ -44,10 +48,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 +98,14 @@ 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.
+        // It never quotes the value whole: what the rule refuses is where a secret travels
+        // (a password, a token in a query), so it names those parts without their text.
         if (!isValidBaseUrl(normalizedBaseUrl)) {
-            throw new PipelineRequestError(`Invalid API base URL "${normalizedBaseUrl}": must be host-only ` +
+            throw new RequestArgumentError(`Invalid API base URL ${describeRefusedBaseUrl(normalizedBaseUrl)}: it 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;
@@ -142,7 +161,7 @@ export class PipelexApiClient {
                 userSignal.addEventListener("abort", onUserAbort, { once: true });
         }
         let response;
-        let body;
+        let bytes;
         try {
             response = await fetch(url, {
                 method,
@@ -153,7 +172,7 @@ export class PipelexApiClient {
             // The body streams after the headers; keep the timer/abort armed until it
             // has fully arrived, or a stalled body would hang past the advertised
             // timeout with no way to cancel.
-            body = await response.text();
+            bytes = new Uint8Array(await response.arrayBuffer());
         }
         catch (err) {
             // A caller-initiated abort (not our timeout) propagates untouched so
@@ -175,32 +194,23 @@ export class PipelexApiClient {
             if (userSignal)
                 userSignal.removeEventListener("abort", onUserAbort);
         }
+        let body;
+        let utf8 = true;
+        try {
+            body = STRICT_UTF8.decode(bytes);
+        }
+        catch {
+            utf8 = false;
+            body = LENIENT_UTF8.decode(bytes);
+        }
         return {
             status: response.status,
             statusText: response.statusText,
             headers: response.headers,
             body,
+            utf8,
         };
     }
-    /**
-     * 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 +220,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 +281,67 @@ 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 UTF-8, or 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) {
+        if (!res.utf8)
+            throw this.unreadableAnswer(method, path, res, "a body that is not UTF-8");
+        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 +383,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 +426,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,
@@ -312,7 +443,8 @@ export class PipelexApiClient {
             ...hosted,
             ...extensions,
         };
-        const startedAt = Date.now();
+        // Timed on the monotonic clock, which a change of the system's time does not move.
+        const startedAt = performance.now();
         try {
             const res = await this.requestRaw("POST", this.url("execute"), {
                 body: request,
@@ -323,7 +455,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)
@@ -331,8 +463,8 @@ export class PipelexApiClient {
             // The hosted gateway terminates synchronous requests at ~30s. A run that
             // exceeds that comes back as a gateway 503/504 (or a client abort) —
             // translate it into a clear, actionable error pointing at start+poll.
-            const elapsedMs = Date.now() - startedAt;
-            if (isGatewayTimeout(err, elapsedMs)) {
+            const elapsedMs = performance.now() - startedAt;
+            if (isGatewayCutOff(err, elapsedMs)) {
                 throw new PipelineExecuteTimeoutError(elapsedMs, { cause: err });
             }
             throw err;
@@ -361,9 +493,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 = {
@@ -380,16 +512,19 @@ export class PipelexApiClient {
             ...extensions,
         };
         const url = this.url("start");
-        // `start` returns a 202 fast, so the poll timeout normally fits — with two
-        // exceptions that get the blocking-execute ceiling instead. A method bundle
-        // can make the request *body* multi-megabyte, and the whole upload is
+        // `start` returns a 202 fast, so the poll timeout normally fits — with
+        // exceptions that get the blocking-execute ceiling instead. A method bundle,
+        // inline as `mthds_contents` or in `files`/`bundle_b64`, can make the
+        // request *body* multi-megabyte, and the whole upload is
         // charged against this budget — the same payload must not time out on the
         // durable path yet succeed on the fallback. And a `method_ref` start makes
         // the server FETCH the package before the ack (provenance rides the 202),
         // whose clone timeout runs well past 30s on a cold cache — aborting it here
         // would surface as `ApiUnreachableError`, blaming the network for a healthy
         // server that is still cloning.
-        const needsLongCeiling = hasBundlePayload(options) || nonEmptyString(options.method_ref) !== undefined;
+        const needsLongCeiling = hasBundlePayload(options) ||
+            (options.mthds_contents?.length ?? 0) > 0 ||
+            nonEmptyString(options.method_ref) !== undefined;
         const res = await this.requestRaw("POST", url, {
             body: request,
             timeoutMs: needsLongCeiling ? DEFAULT_REQUEST_TIMEOUT_MS : POLL_REQUEST_TIMEOUT_MS,
@@ -401,7 +536,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 +615,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 +647,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 +659,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 +773,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 +784,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 +797,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 +911,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 +927,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 +980,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);
         }
@@ -857,8 +994,18 @@ export class PipelexApiClient {
      * Whether the configured server serves the durable run lifecycle, decided
      * via the `GET /v1/version` handshake and cached for the client's lifetime. A
      * bare `pipelex-api` runner has no run store; anything else is assumed hosted.
-     * When the handshake itself fails, assume hosted (the SDK default) and let the
-     * start call surface the real error.
+     *
+     * The rule, the one the Python SDK follows: an answer that is not a usable
+     * version means assume hosted (the SDK default), and let the start surface the
+     * real error; no answer at all propagates, uncached. An answer is anything the
+     * server sent back: a non-2xx status, a body that is not JSON, not UTF-8 or no
+     * version, and a body that arrived but could not be decoded, such as a broken
+     * gzip stream, which `requestRaw` reports as an `ApiUnreachableError` carrying
+     * the decompressor's code (see `isUndecodableBody`).
+     *
+     * @throws {ApiUnreachableError} The handshake got no answer. Nothing is cached,
+     *   so the next call asks again, and no start is sent to a host that did not
+     *   answer: sending it would wait a second time for the same silence.
      */
     async supportsRunLifecycle() {
         if (this.lifecycleAvailable === undefined) {
@@ -867,7 +1014,11 @@ export class PipelexApiClient {
                 const impl = info.implementation;
                 this.lifecycleAvailable = !(typeof impl === "string" && impl === BARE_RUNNER_IMPLEMENTATION);
             }
-            catch {
+            catch (error) {
+                // No answer at all propagates. A body that arrived and could not be decoded is an answer,
+                // and so is every other failure here: a non-2xx status, or a body that is no version.
+                if (error instanceof ApiUnreachableError && !isUndecodableBody(error))
+                    throw error;
                 this.lifecycleAvailable = true;
             }
         }
@@ -880,11 +1031,27 @@ export class PipelexApiClient {
      *   path that survives the gateway's ~30s synchronous ceiling.
      * - **Bare runner** (no run store): the blocking `POST /v1/execute`, which
      *   has no gateway cap off-platform and returns the native `pipe_output`.
+     *
+     * `pollOptions` are the wait's options, plus `onStarted`, called once with the
+     * start acknowledgement as soon as the durable run exists, so the caller holds
+     * the run's id while it waits; never on the blocking path, which has none to
+     * give; and `onStarting`, called right before each request that may create a
+     * run, so the caller knows until then that none exists (see
+     * `StartAndWaitForResultOptions`).
+     *
+     * `pollOptions.signal` is also read before the run is created: a caller that aborts while the
+     * version handshake is in flight gets its abort, and neither the start nor the blocking execute
+     * is sent. Once one of them is sent, the abort stops only the wait.
      */
     async startAndWaitForResult(options, pollOptions) {
         // Before the run starts: a RangeError after it would carry no run id to re-poll by.
         assertWaitOptions(pollOptions);
-        if (await this.supportsRunLifecycle()) {
+        const { onStarted, onStarting, ...waitOptions } = pollOptions ?? {};
+        const hosted = await this.supportsRunLifecycle();
+        // The handshake may have outlasted the caller's patience: an abort that landed during it
+        // creates no run.
+        throwIfAborted(waitOptions.signal);
+        if (hosted) {
             // A runner can look hosted yet lack the durable routes — `implementation`
             // is an extension field, so a compliant bare runner that omits it is
             // misdetected here. Such a runner raises `RunLifecycleUnavailableError`
@@ -893,16 +1060,21 @@ export class PipelexApiClient {
             // the durable attempt.
             let ack;
             try {
+                onStarting?.();
                 ack = await this.start(options);
             }
             catch (err) {
                 if (!(err instanceof RunLifecycleUnavailableError))
                     throw err;
                 this.lifecycleAvailable = false;
+                throwIfAborted(waitOptions.signal);
+                onStarting?.();
                 return this.executeBlocking(options);
             }
-            return this.waitForResult(ack.pipeline_run_id, pollOptions);
+            onStarted?.(ack);
+            return this.waitForResult(ack.pipeline_run_id, waitOptions);
         }
+        onStarting?.();
         return this.executeBlocking(options);
     }
     // ── Pipelex product surface (hosted management routes) ─────────────────
@@ -944,8 +1116,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 +1168,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 +1208,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 +1317,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 +1350,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 +1380,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 +1454,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 +1510,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) {
@@ -1395,6 +1573,42 @@ function isValidBaseUrl(value) {
         return false;
     return !parsed.search && !parsed.hash;
 }
+/**
+ * A refused base URL as its refusal may show it: the scheme and the host, then the names of the
+ * parts beyond them that the URL carried, never their text. Credentials, a query and a path are
+ * exactly where a secret travels in a URL, and the refusal reaches logs and, through an app that
+ * relays an error's message, a browser. A value that is not an http or https URL is not shown at
+ * all, since nothing says which of its characters are a secret: `localhost:8081`, with no scheme,
+ * parses as a URL whose scheme is `localhost:`.
+ */
+function describeRefusedBaseUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return "(not shown: it is not an absolute URL)";
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return "(not shown: it is not an http or https URL)";
+    }
+    const parts = [];
+    if (parsed.username || parsed.password)
+        parts.push("credentials");
+    if (parsed.pathname !== "/" && parsed.pathname !== "")
+        parts.push("a path");
+    if (parsed.search)
+        parts.push("a query");
+    if (parsed.hash)
+        parts.push("a fragment");
+    const shown = `"${parsed.protocol}//${parsed.host}"`;
+    if (parts.length === 0)
+        return shown;
+    const named = parts.length === 1
+        ? parts[0]
+        : `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+    return `${shown} with ${named} (not shown)`;
+}
 // The protocol's own request fields — `extra` is for extension args only.
 // `files` / `bundle_b64` are reserved too: they are named run-source options,
 // so smuggling them through `extra` (which merges last into the body) would
@@ -1458,7 +1672,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 +1722,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 +1759,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.");
     }
 }
@@ -1556,19 +1787,52 @@ function withValidateMarkdownRender(render) {
     return [...formats];
 }
 // The hosted gateway caps synchronous requests at 30s. A failure at/after this
-// threshold on the blocking execute is the timeout, not a transient outage —
-// the threshold guards against mislabelling a fast 503 (runner genuinely down)
-// as a timeout.
+// threshold is the gateway's cut-off, not a transient outage — the threshold
+// guards against mislabelling a fast 503 (runner genuinely down) as a timeout.
+// The one source of the threshold in this SDK: `isGatewayCutOff` reads it.
 const GATEWAY_TIMEOUT_THRESHOLD_MS = 28_000;
-function isGatewayTimeout(err, elapsedMs) {
+/**
+ * Whether a request that failed `elapsedMs` after it was sent was cut off by the hosted gateway's
+ * ~30-second limit on a request it waits on, rather than refused.
+ *
+ * It is when, after at least ~28 seconds, the failure is a `503` or `504` answer, or the client's
+ * own time limit (`ApiUnreachableError` with the code `ABORT_TIMEOUT`). A fast `503` is the API
+ * saying the request was not handled, and any other unreachable host is never the gateway's
+ * cut-off, however long it took. The fetch API cannot say whether `ABORT_TIMEOUT` ran out before
+ * the connection was made, so it is read as the gateway's; with Node's own dispatcher it never
+ * does past the threshold, since undici gives up a connection that does not come after ten
+ * seconds (`UND_ERR_CONNECT_TIMEOUT`), the TLS handshake included. The Python SDK's
+ * `is_gateway_cut_off` reads the same failures, its `ABORT_TIMEOUT` being httpx's read or write
+ * timeout.
+ *
+ * The blocking `execute` turns such a failure into a `PipelineExecuteTimeoutError`. A caller timing
+ * a request that may create a run, such as `start` from `startAndWaitForResult`'s `onStarting`,
+ * reads it to know the server may still be handling the request the gateway gave up on.
+ */
+export function isGatewayCutOff(error, elapsedMs) {
     if (elapsedMs < GATEWAY_TIMEOUT_THRESHOLD_MS)
         return false;
-    if (err instanceof ApiResponseError)
-        return err.status === 503 || err.status === 504;
-    if (err instanceof ApiUnreachableError)
-        return err.code === "ABORT_TIMEOUT";
+    if (error instanceof ApiResponseError)
+        return error.status === 503 || error.status === 504;
+    if (error instanceof ApiUnreachableError)
+        return error.code === "ABORT_TIMEOUT";
     return false;
 }
+/**
+ * The codes Node's fetch gives a body that arrived and could not be decoded. It decodes a
+ * `Content-Encoding` while it reads the body, after the status and the headers, and a body that
+ * does not decode fails the read with the decompressor's own code: zlib's `Z_…` for `gzip` and
+ * `deflate`, brotli's `ERR__ERROR_…` for `br`, zstd's `ZSTD_error_…` for `zstd`.
+ */
+const UNDECODABLE_BODY_CODE = /^(Z_|ERR__ERROR_|ZSTD_error_)/;
+/**
+ * Whether an `ApiUnreachableError` is an answer whose body could not be decoded, rather than no
+ * answer at all. The Python SDK's twin is the `ApiUnreachableError` whose cause is httpx's
+ * `DecodingError`.
+ */
+function isUndecodableBody(error) {
+    return error.code !== undefined && UNDECODABLE_BODY_CODE.test(error.code);
+}
 function extractNetworkErrorCode(err) {
     if (err instanceof DOMException && err.name === "TimeoutError") {
         return "ABORT_TIMEOUT";
@@ -1634,21 +1898,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 +1945,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 +1990,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 +2008,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;