@pipelex/sdk 0.38.0 → 0.39.0

package/README.md

@@ -134,7 +134,7 @@ 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, returning `undefined` for what is not an SDK error, such as a bug in the calling code or your own abort. "Retryable" means a retry can succeed, not that it is safe: a start answered with a `500` may already have created a run.
+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, returning `undefined` for what is not an SDK error, 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)).
 
 ```ts
 import { errorVerdictOf } from "@pipelex/sdk";
@@ -152,7 +152,7 @@ try {
 
 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.
 
-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 inference details. 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 report is the runner's VERBOSE one, provider text included, so what a person sees is 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`. (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:
 
 ```ts
 import { RunFailedError } from "@pipelex/sdk";

package/dist/cli/run.js

@@ -8,7 +8,7 @@
  * as soon as the run exists; and the main output reaches stdout once the run completes, however
  * long that takes.
  */
-import { ApiResponseError, ApiUnreachableError, MissingMainStuffError, PipelineExecuteTimeoutError, RunFailedError, isGatewayCutOff, renderInputsTemplate, } from "../index.js";
+import { MissingMainStuffError, RunFailedError, renderInputsTemplate, runMayHaveStartedOf, } from "../index.js";
 import { parseFlags } from "./args.js";
 import { readBundle } from "./bundle.js";
 import { makeClient, readPollInterval } from "./environment.js";
@@ -75,7 +75,7 @@ export async function runCommandRun(args, io) {
                 onStarting: () => {
                     // Only once a request that may create a run is about to leave: an interrupt before
                     // it, during the version handshake included, starts nothing, and the command says so.
-                    stage = { kind: "starting", since: performance.now() };
+                    stage = { kind: "starting" };
                 },
                 onStarted: (ack) => {
                     if (io.interrupt.aborted)
@@ -122,120 +122,17 @@ function waitedOnRun(stage, error) {
         return undefined;
     return stage.runId;
 }
-/**
- * Whether a transport failure proves the request never left, so that no run was created by it: it
- * names a step of the connection's set-up, which no request follows. That is the name lookup or
- * the connection itself failing (the system calls `getaddrinfo` and `connect`: an unknown host, a
- * refused connection, no route to the host or the network, the system's connect time limit),
- * undici's own connect time limit, which covers the TLS handshake, and a server certificate the
- * TLS handshake refused. Several addresses each failing so, which Node reports together as an
- * `AggregateError`, prove it too. A host that drops packets is a connection that never comes:
- * undici gives it up after ten seconds (`UND_ERR_CONNECT_TIMEOUT`), before the time limit of any
- * request the command sends, as the Python command meets httpx's connect timeout first and reads
- * it the same way.
- *
- * Anything else may have come once the request had left, the Python command reading the same
- * failures the same way. A reset (`ECONNRESET`) comes from a `read` whether the connection dropped
- * during the TLS handshake or after the request, and so does an `EHOSTUNREACH` met once connected,
- * so neither proves anything; nor does another TLS failure, which may come after the handshake;
- * nor does the SDK's own time limit (`ABORT_TIMEOUT`), which fetch cannot place before or after
- * the connection was made. Every request the command sends has a limit longer than undici's
- * connect limit, so with Node's own dispatcher it runs out only once the request has left.
- */
-function provesNothingSent(error) {
-    // The SDK keeps fetch's own failure as `cause`, and undici gives the transport's under it.
-    const fetchFailure = error.cause;
-    return fetchFailure instanceof Error && isConnectionSetupFailure(fetchFailure.cause);
-}
-function isConnectionSetupFailure(failure) {
-    if (failure instanceof AggregateError) {
-        return failure.errors.length > 0 && failure.errors.every(isConnectionSetupFailure);
-    }
-    if (typeof failure !== "object" || failure === null)
-        return false;
-    const { code, syscall } = failure;
-    if (typeof code === "string" && CONNECTION_SETUP_CODES.has(code))
-        return true;
-    return typeof syscall === "string" && CONNECTION_SETUP_CALLS.has(syscall);
-}
-/** The system calls that resolve the host's name and open the connection. */
-const CONNECTION_SETUP_CALLS = new Set(["getaddrinfo", "connect"]);
-/**
- * The codes only a step of the connection's set-up gives: the name lookup's and the connect call's
- * own (set even where Node reports several addresses together, without a system call), undici's
- * connect time limit, Node's limit on one attempt among several addresses, Node's own check of the
- * host's name, and every code Node gives a server certificate the TLS handshake refused.
- */
-const CONNECTION_SETUP_CODES = new Set([
-    "ECONNREFUSED",
-    "ENOTFOUND",
-    "EAI_AGAIN",
-    "UND_ERR_CONNECT_TIMEOUT",
-    "ERR_SOCKET_CONNECTION_TIMEOUT",
-    "ERR_TLS_CERT_ALTNAME_INVALID",
-    "ERR_TLS_CERT_ALTNAME_FORMAT",
-    // Node names the verdicts of OpenSSL's certificate check from a fixed table, the "X509 certificate
-    // error codes" of its `tls` docs, and gives every other verdict, such as an unhandled critical
-    // extension or a CA certificate that may not sign certificates, the code `UNSPECIFIED`. The
-    // error carries nothing else that marks it, so these codes are the mark: the table as Node 24
-    // compiles it, in its order, then its default. The Python command reads every
-    // `ssl.SSLCertVerificationError` the same way.
-    "UNABLE_TO_GET_ISSUER_CERT",
-    "UNABLE_TO_GET_CRL",
-    "UNABLE_TO_DECRYPT_CERT_SIGNATURE",
-    "UNABLE_TO_DECRYPT_CRL_SIGNATURE",
-    "UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY",
-    "CERT_SIGNATURE_FAILURE",
-    "CRL_SIGNATURE_FAILURE",
-    "CERT_NOT_YET_VALID",
-    "CERT_HAS_EXPIRED",
-    "CRL_NOT_YET_VALID",
-    "CRL_HAS_EXPIRED",
-    "ERROR_IN_CERT_NOT_BEFORE_FIELD",
-    "ERROR_IN_CERT_NOT_AFTER_FIELD",
-    "ERROR_IN_CRL_LAST_UPDATE_FIELD",
-    "ERROR_IN_CRL_NEXT_UPDATE_FIELD",
-    "OUT_OF_MEM",
-    "DEPTH_ZERO_SELF_SIGNED_CERT",
-    "SELF_SIGNED_CERT_IN_CHAIN",
-    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
-    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
-    "CERT_CHAIN_TOO_LONG",
-    "CERT_REVOKED",
-    "INVALID_CA",
-    "PATH_LENGTH_EXCEEDED",
-    "INVALID_PURPOSE",
-    "CERT_UNTRUSTED",
-    "CERT_REJECTED",
-    "HOSTNAME_MISMATCH",
-    "UNSPECIFIED",
-]);
 /**
  * Whether a failure met once a request that may create a run was sent, and before the API named
- * the run, leaves it unknown whether one was created: its answer was lost to a time limit, a
- * connection that closed once the request had left or a gateway that cut the request off, or it
- * came back unreadable, or a gateway answered that it lost or never got the server's answer
- * (`502`, `504`, RFC 9110). A gateway cuts a request off at ~30 seconds, whether a blocking
- * execute or a start the server is still handling, such as one fetching a `method_ref`'s package:
- * the SDK's `isGatewayCutOff` tells it, past its threshold, from the time since `onStarting`. Any
- * other answer from the API, a `503` that came back before that saying the request was not handled
- * included, and a failure that proves nothing was sent, say no run was created.
+ * the run, leaves it unknown whether one was created. The SDK decides it on the error it raises
+ * (`runMayHaveStarted`): its answer was lost to a time limit, a connection that closed once the
+ * request had left or a gateway that cut the request off, it came back unreadable, or the server
+ * or a gateway failed while handling it. A failure that proves nothing was sent, and an answer
+ * refusing the request before anything ran, say no run was created.
  */
 function mayHaveStarted(stage, error) {
-    if (stage.kind !== "starting")
-        return false;
-    if (error instanceof PipelineExecuteTimeoutError)
-        return true;
-    if (error instanceof ApiUnreachableError)
-        return !provesNothingSent(error);
-    if (!(error instanceof ApiResponseError))
-        return false;
-    if (error.status >= 200 && error.status < 300)
-        return true;
-    return (GATEWAY_LOST_ANSWER.has(error.status) || isGatewayCutOff(error, performance.now() - stage.since));
+    return stage.kind === "starting" && runMayHaveStartedOf(error);
 }
-/** The gateway statuses that say the server's answer was lost or never came (RFC 9110). */
-const GATEWAY_LOST_ANSWER = new Set([502, 504]);
 /** The line under a failure that leaves it unknown whether a run was created. */
 export const RUN_MAY_HAVE_STARTED_LINE = "A run may have started on the server without the command learning of it, so check before starting it again.";
 /** The line under a failure met while waiting on a run that exists. */

package/dist/cli/run.js.map

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

package/dist/cli/script.d.ts

@@ -15,7 +15,7 @@ import type { CommandIO } from "./io.js";
  * update notice and npm 12's run notices off the script's stderr, which carries the command's
  * own lines, while npm's warnings and errors still print.
  */
-export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.38.0";
+export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.39.0";
 export declare const SCRIPT_WRITER = "@pipelex/sdk";
 export declare const SCRIPT_NEEDS = "Node 22.12 or later";
 /** Run `pipelex-sdk script` and return its exit code. */

package/dist/client.d.ts

@@ -161,7 +161,8 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * DNS/connect/TLS/timeout failures as `ApiUnreachableError`; a caller-driven
      * abort (Ctrl-C / agent walk-away) propagates as-is so the poll loop can stop
      * cleanly. Non-2xx interpretation is left to the caller. `url` is a fully
-     * resolved absolute URL.
+     * resolved absolute URL. `mayStartRun` marks a request that may create a run,
+     * whose `ApiUnreachableError` then says whether it may have (see `RunCreation`).
      */
     private requestRaw;
     /**
@@ -230,6 +231,7 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * `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.
+     * On a request that may create a run, the run may have started: the server accepted it.
      */
     private unreadableAnswer;
     /**
@@ -249,6 +251,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * error. Hosted does not emit 202 today, but the protocol permits it;
      * raising a typed error (with the `pipeline_run_id` + `Location` + `Retry-After`
      * hints) beats a generic parse failure on an unexpected body shape.
+     *
+     * The 202 must name the run it accepted, as `start`'s acknowledgement must: one whose body is
+     * not JSON, or names no run (an empty id included), leaves the caller a run it cannot follow, so it is an answer the
+     * SDK cannot read, which may have started a run, never a `RunStillRunningError` without an id.
+     * The Python SDK reads the same answers the same way.
      */
     private throwIfExecuteDegraded;
     /**
@@ -538,12 +545,17 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * Fetch a run's status by bare id — `GET /v1/runs/{pipeline_run_id}/status`.
      *
      * 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. 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).
+     * status on read. `degraded: true` means the read is not a plain fresh reading,
+     * and `degradation.reason` says why (see `DegradationReason`):
+     * `status_unavailable` when the platform could not reach the workflow engine
+     * and `status` is the last one recorded, `workflow_task_failing` when `status`
+     * is live and the run is stuck, its workflow task failing until the platform
+     * ends it at `degradation.ends_at`. `retry_after_seconds` carries the server's
+     * `Retry-After` hint when present, and `request_id` the id to quote to support.
+     * A failed run's stored report, `error`, and the `degradation` are each
+     * checked field by field (see `RunErrorReport` and `RunDegradation`), so
+     * neither ever fails the read. Throws `RunLifecycleUnavailableError` when the
+     * lifecycle routes are absent (a bare runner).
      */
     getRunStatus(runId: string, options?: {
         signal?: AbortSignal;
@@ -609,6 +621,13 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * `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.
+     *
+     * An error from the start, or from the blocking execute, says whether that request may still
+     * have started a run whose id never reached the caller (`runMayHaveStarted`); when it may have,
+     * it is not retryable, since calling this method again could pay for the run twice: look the run
+     * up in the run history first. An error from the wait, once `onStarted` has named the run,
+     * started nothing, so its `runMayHaveStarted` is false, and its `retryable` is about waiting
+     * again on that id with `waitForResult`, never about calling this method again.
      */
     startAndWaitForResult(options: PipelexStartOptions, pollOptions?: StartAndWaitForResultOptions): Promise<RunResults>;
     /** The authenticated user's profile — `GET /v1/me`. */
@@ -956,6 +975,9 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * answers with, which states the kind of every input at every depth, so a file
      * position is a fact of the method, never a guess from the value's shape. It
      * needs an API serving `POST /v1/pipe-io`. See `docs/input-preparation.md`.
+     *
+     * With `allowUploads: false` it uploads nothing and reads no file: a value that
+     * would need an upload throws `UploadNotAllowedError`, naming the input.
      */
     prepareInputs(request: PrepareInputsRequest): Promise<PreparedInputs>;
     /**
@@ -1050,8 +1072,9 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
  * `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.
+ * The blocking `execute` turns such a failure into a `PipelineExecuteTimeoutError`. Whether a
+ * failed `start` or `execute` may have started a run needs no timing: the error says it as
+ * `runMayHaveStarted`, which reads every `503` but the platform's coded one as a run that may
+ * have started, however quickly it came back.
  */
 export declare function isGatewayCutOff(error: unknown, elapsedMs: number): boolean;

package/dist/client.js

@@ -2,7 +2,7 @@
 // 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, throwIfAborted, } from "./runs.js";
+import { assertArtifactSelection, assertWaitOptions, pollUntilResult, readRunDegradation, 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";
@@ -29,6 +29,7 @@ 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");
+const STARTS_RUN = Object.freeze({ mayStartRun: true });
 /** 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}`.
@@ -155,7 +156,8 @@ export class PipelexApiClient {
      * DNS/connect/TLS/timeout failures as `ApiUnreachableError`; a caller-driven
      * abort (Ctrl-C / agent walk-away) propagates as-is so the poll loop can stop
      * cleanly. Non-2xx interpretation is left to the caller. `url` is a fully
-     * resolved absolute URL.
+     * resolved absolute URL. `mayStartRun` marks a request that may create a run,
+     * whose `ApiUnreachableError` then says whether it may have (see `RunCreation`).
      */
     async requestRaw(method, url, options = {}) {
         const hasBody = options.body !== undefined;
@@ -203,7 +205,7 @@ export class PipelexApiClient {
             // is classified from the controller rather than from `err`: a browser errors a
             // body stream cut short by that abort with a generic AbortError instead.
             const code = extractNetworkErrorCode(controller.signal.aborted ? controller.signal.reason : err);
-            throw new ApiUnreachableError(`Could not reach Pipelex API at ${this.baseUrl} (${code ?? "network error"})`, this.baseUrl, code, { cause: err });
+            throw new ApiUnreachableError(`Could not reach Pipelex API at ${this.baseUrl} (${code ?? "network error"})`, this.baseUrl, code, { cause: err, mayStartRun: options.mayStartRun === true });
         }
         finally {
             clearTimeout(timer);
@@ -306,16 +308,16 @@ export class PipelexApiClient {
         }
         return res;
     }
-    throwApiResponseError(method, endpoint, res) {
-        this.throwApiResponseErrorAt(method, `/${API_PREFIX}/${endpoint}`, res);
+    throwApiResponseError(method, endpoint, res, run = {}) {
+        this.throwApiResponseErrorAt(method, `/${API_PREFIX}/${endpoint}`, res, run);
     }
     /** 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);
+    readObjectAnswer(method, endpoint, res, run = {}) {
+        return this.readObjectAnswerAt(method, `/${API_PREFIX}/${endpoint}`, res, run);
     }
     /**
      * The JSON body of a 2xx answer, naming the route by its `path` from the origin as a refusal
@@ -324,14 +326,15 @@ export class PipelexApiClient {
      * 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");
+    readAnswerAt(method, path, res, run = {}) {
+        if (!res.utf8) {
+            throw this.unreadableAnswer(method, path, res, "a body that is not UTF-8", undefined, run);
+        }
         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);
+            throw this.unreadableAnswer(method, path, res, res.body ? "a body that is not JSON" : "an empty body where JSON was expected", err, run);
         }
     }
     /**
@@ -339,10 +342,10 @@ export class PipelexApiClient {
      * 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);
+    readObjectAnswerAt(method, path, res, run = {}) {
+        const answer = this.readAnswerAt(method, path, res, run);
         if (!isPlainObject(answer)) {
-            throw this.unreadableAnswer(method, path, res, "a body that is not an object");
+            throw this.unreadableAnswer(method, path, res, "a body that is not an object", undefined, run);
         }
         return answer;
     }
@@ -351,20 +354,29 @@ export class PipelexApiClient {
      * `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.
+     * On a request that may create a run, the run may have started: the server accepted it.
      */
-    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) } });
+    unreadableAnswer(method, path, res, what, cause, run = {}) {
+        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) },
+            mayStartRun: run.mayStartRun === true,
+        });
     }
     /**
      * 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) {
+    throwApiResponseErrorAt(method, path, res, run = {}) {
         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} ${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 });
+        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,
+            mayStartRun: run.mayStartRun === true,
+        });
     }
     /**
      * Translate a "route absent" 404 (a bare pipelex-api with no platform block)
@@ -386,23 +398,21 @@ export class PipelexApiClient {
      * error. Hosted does not emit 202 today, but the protocol permits it;
      * raising a typed error (with the `pipeline_run_id` + `Location` + `Retry-After`
      * hints) beats a generic parse failure on an unexpected body shape.
+     *
+     * The 202 must name the run it accepted, as `start`'s acknowledgement must: one whose body is
+     * not JSON, or names no run (an empty id included), leaves the caller a run it cannot follow, so it is an answer the
+     * SDK cannot read, which may have started a run, never a `RunStillRunningError` without an id.
+     * The Python SDK reads the same answers the same way.
      */
     throwIfExecuteDegraded(res) {
         if (res.status !== 202)
             return;
-        let runId = "";
-        try {
-            const parsed = JSON.parse(res.body);
-            if (parsed && typeof parsed === "object") {
-                const candidate = parsed.pipeline_run_id;
-                if (typeof candidate === "string")
-                    runId = candidate;
-            }
-        }
-        catch {
-            // Non-JSON 202 body — keep runId empty; the error message covers it.
+        const ack = this.readObjectAnswer("POST", "execute", res, STARTS_RUN);
+        const runId = ack.pipeline_run_id;
+        if (typeof runId !== "string" || runId === "") {
+            throw this.unreadableAnswer("POST", `/${API_PREFIX}/execute`, res, "a body that is not the answer the route returns", undefined, STARTS_RUN);
         }
-        throw new RunStillRunningError(`execute() was accepted asynchronously (202): run ${runId || "<unknown>"} is still ` +
+        throw new RunStillRunningError(`execute() was accepted asynchronously (202): run ${runId} is still ` +
             "running server-side. Poll its results (hosted) or use start().", runId, parseRetryAfter(res.headers), res.headers.get("location"));
     }
     // ── Health ────────────────────────────────────────────────────────
@@ -472,14 +482,19 @@ export class PipelexApiClient {
         try {
             const res = await this.requestRaw("POST", this.url("execute"), {
                 body: request,
+                ...STARTS_RUN,
             });
             this.throwIfExecuteDegraded(res);
             if (res.status < 200 || res.status >= 300) {
-                this.throwApiResponseError("POST", "execute", res);
+                this.throwApiResponseError("POST", "execute", res, STARTS_RUN);
             }
             // 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(this.readObjectAnswer("POST", "execute", res));
+            const answer = this.readObjectAnswer("POST", "execute", res, STARTS_RUN);
+            if (!isCompletedRunAnswer(answer)) {
+                throw this.unreadableAnswer("POST", `/${API_PREFIX}/execute`, res, "a body that is not the answer the route returns", undefined, STARTS_RUN);
+            }
+            return new PipelexExecuteResult(answer);
         }
         catch (err) {
             if (err instanceof RunStillRunningError)
@@ -553,15 +568,23 @@ export class PipelexApiClient {
         const res = await this.requestRaw("POST", url, {
             body: request,
             timeoutMs: needsLongCeiling ? DEFAULT_REQUEST_TIMEOUT_MS : POLL_REQUEST_TIMEOUT_MS,
+            ...STARTS_RUN,
         });
         // A bare runner with no run store 404s here just as it does on the result
         // routes — surface the same clear `RunLifecycleUnavailableError` (and let
         // `startAndWaitForResult` fall back to the blocking `execute`).
         this.throwIfLifecycleUnavailable(res, url);
         if (res.status < 200 || res.status >= 300) {
-            this.throwApiResponseError("POST", "start", res);
+            this.throwApiResponseError("POST", "start", res, STARTS_RUN);
+        }
+        const ack = this.readObjectAnswer("POST", "start", res, STARTS_RUN);
+        // The acknowledgement's one job is to name the run: without its id, the run the server
+        // accepted is lost to the caller, as surely as behind a body that is not JSON, and an empty id
+        // names no run either. Worded as the Python SDK words an answer its model refuses.
+        if (typeof ack.pipeline_run_id !== "string" || ack.pipeline_run_id === "") {
+            throw this.unreadableAnswer("POST", `/${API_PREFIX}/start`, res, "a body that is not the answer the route returns", undefined, STARTS_RUN);
         }
-        return this.readObjectAnswer("POST", "start", res);
+        return ack;
     }
     /**
      * Parse, validate, and dry-run an MTHDS bundle — `POST /v1/validate`.
@@ -971,12 +994,17 @@ export class PipelexApiClient {
      * Fetch a run's status by bare id — `GET /v1/runs/{pipeline_run_id}/status`.
      *
      * 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. 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).
+     * status on read. `degraded: true` means the read is not a plain fresh reading,
+     * and `degradation.reason` says why (see `DegradationReason`):
+     * `status_unavailable` when the platform could not reach the workflow engine
+     * and `status` is the last one recorded, `workflow_task_failing` when `status`
+     * is live and the run is stuck, its workflow task failing until the platform
+     * ends it at `degradation.ends_at`. `retry_after_seconds` carries the server's
+     * `Retry-After` hint when present, and `request_id` the id to quote to support.
+     * A failed run's stored report, `error`, and the `degradation` are each
+     * checked field by field (see `RunErrorReport` and `RunDegradation`), so
+     * neither ever fails the read. Throws `RunLifecycleUnavailableError` when the
+     * lifecycle routes are absent (a bare runner).
      */
     async getRunStatus(runId, options = {}) {
         const endpoint = `${RUNS}/${encodeURIComponent(runId)}/status`;
@@ -989,7 +1017,7 @@ export class PipelexApiClient {
         if (res.status < 200 || res.status >= 300) {
             this.throwApiResponseError("GET", endpoint, res);
         }
-        const run = withCheckedReport(this.readObjectAnswer("GET", endpoint, res));
+        const run = withCheckedDegradation(withCheckedReport(this.readObjectAnswer("GET", endpoint, res)));
         const retryAfter = parseRetryAfter(res.headers);
         return retryAfter !== null ? { ...run, retry_after_seconds: retryAfter } : run;
     }
@@ -1104,6 +1132,13 @@ export class PipelexApiClient {
      * `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.
+     *
+     * An error from the start, or from the blocking execute, says whether that request may still
+     * have started a run whose id never reached the caller (`runMayHaveStarted`); when it may have,
+     * it is not retryable, since calling this method again could pay for the run twice: look the run
+     * up in the run history first. An error from the wait, once `onStarted` has named the run,
+     * started nothing, so its `runMayHaveStarted` is false, and its `retryable` is about waiting
+     * again on that id with `waitForResult`, never about calling this method again.
      */
     async startAndWaitForResult(options, pollOptions) {
         // Before the run starts: a refusal after it would carry no run id to re-poll by.
@@ -1632,6 +1667,9 @@ export class PipelexApiClient {
      * answers with, which states the kind of every input at every depth, so a file
      * position is a fact of the method, never a guess from the value's shape. It
      * needs an API serving `POST /v1/pipe-io`. See `docs/input-preparation.md`.
+     *
+     * With `allowUploads: false` it uploads nothing and reads no file: a value that
+     * would need an upload throws `UploadNotAllowedError`, naming the input.
      */
     async prepareInputs(request) {
         return prepareInputsImpl(this, request);
@@ -2063,9 +2101,10 @@ const GATEWAY_TIMEOUT_THRESHOLD_MS = 28_000;
  * `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.
+ * The blocking `execute` turns such a failure into a `PipelineExecuteTimeoutError`. Whether a
+ * failed `start` or `execute` may have started a run needs no timing: the error says it as
+ * `runMayHaveStarted`, which reads every `503` but the platform's coded one as a run that may
+ * have started, however quickly it came back.
  */
 export function isGatewayCutOff(error, elapsedMs) {
     if (elapsedMs < GATEWAY_TIMEOUT_THRESHOLD_MS)
@@ -2125,6 +2164,25 @@ function isMissingRoute404(body) {
         return true;
     return !("code" in parsed);
 }
+/**
+ * Whether a 2xx answer to `execute` is the completed run the route returns, as far as the SDK reads
+ * it: a string `pipeline_run_id`, and a `pipe_output` object whose `working_memory` carries its
+ * `root` and `aliases` objects and whose own `pipeline_run_id` is a string, the envelope the Python
+ * SDK's model of the answer requires. Anything less is an answer the SDK cannot read, rather than
+ * a result that fails with a bare `TypeError` once its output is lifted. The stuffs inside `root`,
+ * which the Python model also checks, are left to the read of the main stuff, whose
+ * `MissingMainStuffError` names the run.
+ */
+function isCompletedRunAnswer(answer) {
+    const { pipeline_run_id: runId, pipe_output: pipeOutput } = answer;
+    if (typeof runId !== "string" || !isPlainObject(pipeOutput))
+        return false;
+    const workingMemory = pipeOutput["working_memory"];
+    return (typeof pipeOutput["pipeline_run_id"] === "string" &&
+        isPlainObject(workingMemory) &&
+        isPlainObject(workingMemory["root"]) &&
+        isPlainObject(workingMemory["aliases"]));
+}
 /** Parse the `Retry-After` header (seconds form, which the platform uses). */
 function parseRetryAfter(headers) {
     const raw = headers.get("retry-after");
@@ -2181,6 +2239,15 @@ function withCheckedReport(record) {
         return record;
     return { ...record, error: readRunErrorReport(record.error) };
 }
+/**
+ * A status read with its `degradation` checked by `readRunDegradation`. Only when the read carries
+ * the key, so a platform that predates it still leaves it absent; `degraded` is left as sent.
+ */
+function withCheckedDegradation(run) {
+    if (!Object.hasOwn(run, "degradation"))
+        return run;
+    return { ...run, degradation: readRunDegradation(run.degradation) };
+}
 function knownRunStatus(value) {
     return typeof value === "string" && KNOWN_RUN_STATUSES.includes(value)
         ? value