@pipelex/sdk 0.37.0 → 0.39.0

package/dist/error-models.d.ts

@@ -4,9 +4,10 @@
  *
  * **The runner owns these shapes; this SDK follows them.** A run that fails reports why as
  * the runner's `ErrorReport` (`pipelex.base_exceptions`), which the hosted platform stores
- * whole on the run row as `error` and serves as it was stored: on the status read
- * (`RunRead.error`), on the run records (`PipelineRun.error`), and inside the problem
- * document of the results read's `409`, where the client lifts it onto the failed arm of
+ * whole on the run row as `error` and serves through the runner's STRICT disclosure: on the
+ * status read (`RunRead.error`), on the run records (`PipelineRun.error`,
+ * `RunHistoryItem.error`), and inside the problem document of the results read's `409`, where
+ * the client lifts it onto the failed arm of
  * `RunResultState` and onto `RunFailedError.error`. The same classification fields
  * (`error_domain`, `user_action`, …) ride a runner-rendered problem document as extension
  * members, which is why `ApiResponseError` types its members with the models declared here.
@@ -26,10 +27,19 @@
  * `providerMetadata`, `migration`, `validationErrors` and `errors` hold to their types as a stored
  * report's do.
  *
- * **Nothing else is stripped.** The platform serves the runner's VERBOSE report, so `message` and
- * `provider_metadata` can hold a provider's raw text. Deciding what of it a person should see
- * is each consumer's presentation, not this SDK's; the report arrives here whole, members this
- * SDK does not name included.
+ * **The platform serves the STRICT projection; this SDK strips nothing further.** The run row
+ * keeps the runner's VERBOSE report as the operators' record, and every read that hands it to a
+ * caller serves the rule the hosted runner applies to an error on `execute`: `error_type`,
+ * `title`, `type_uri`, `error_domain`, `error_category`, `retryable` and `validation_errors`
+ * pass through; `message` and `user_action` pass through only when `caller_facing_message` is
+ * `true`, which the served report then keeps, and otherwise `message` is the placeholder
+ * `An internal error occurred.` while `user_action` and the flag are absent; `provider_metadata`
+ * keeps only `status_code` and `retry_after_seconds`; `model`, `provider` and `migration` are
+ * absent. The reports the platform writes itself are caller-facing copy, so they keep their
+ * message and their next step. A platform run locally with `ERROR_DISCLOSURE=verbose` serves the
+ * report whole, which is why the types still name every member the runner writes. Deciding what
+ * a person should see is each consumer's presentation; the report arrives here as served,
+ * members this SDK does not name included.
  */
 import type { ValidationErrorItem } from "./models.js";
 /**
@@ -51,7 +61,10 @@ export interface UserAction {
  * What the inference provider's SDK said about a failed call — the runner's
  * `ProviderErrorMetadata`. Present on a report whose failure came back from a model provider.
  * `message` is the provider SDK's own text, relayed raw; the provider's response body never
- * crosses the wire, because the runner excludes it from every serialization.
+ * crosses the wire, because the runner excludes it from every serialization. A hosted run read
+ * keeps only `status_code` and `retry_after_seconds`, the client hints; the other members reach a
+ * caller only from a server that discloses errors VERBOSE, such as a platform run locally with
+ * `ERROR_DISCLOSURE=verbose`.
  *
  * **The hosted store turns its numbers into strings.** A report read back from the platform's
  * run store carries `status_code` and `retry_after_seconds` as JSON strings (`"404"`,
@@ -103,8 +116,19 @@ export interface MigrationErrorBlock {
  * failure's report carries, and how its `message` names the failing pipe, is the runner's to
  * decide; read them as given.
  *
- * A report is `null` where the run has none — a cancelled, terminated or timed-out run, or one
- * the platform finalized itself — so the absence of a report says nothing about why.
+ * The runner writes the report of a run that fails while it runs. A run the platform ends or
+ * settles itself carries one the platform wrote in the same shape, as caller-facing copy:
+ * `WorkflowTaskKeptFailingError` for a workflow task that kept failing (the run ends `FAILED`,
+ * not `TERMINATED`), `RunTimedOutError` for a timeout and `RunWorkflowNotFoundError` for a
+ * workflow that vanished. A `CANCELLED`, `TERMINATED` or `TIMED_OUT` run holds a report when a
+ * completion callback carried one, and a `TIMED_OUT` run otherwise holds the platform's timeout
+ * report. A report is `null` on a completed run and where a run has none — one whose start
+ * failed, a blocking `execute` run, whose answer carried its reason, one cancelled, terminated or
+ * given its status by hand with no completion callback carrying a report, one that ended before
+ * the platform wrote reports of its own — so the absence of a report says nothing about why.
+ *
+ * What the platform serves of a report is the runner's STRICT projection (see the module
+ * comment), so the members the projection drops are absent on a hosted read.
  */
 export interface RunErrorReport {
     /**
@@ -113,8 +137,8 @@ export interface RunErrorReport {
      */
     error_type?: string | null;
     /**
-     * What went wrong, as the runner wrote it. On the VERBOSE report the platform serves, it can
-     * carry a provider's raw text.
+     * What went wrong. The platform serves the author's copy only when `caller_facing_message` is
+     * `true`, and the placeholder `An internal error occurred.` otherwise.
      */
     message?: string | null;
     /** A stable human label for the error class (`LLM completion`). */
@@ -134,22 +158,38 @@ export interface RunErrorReport {
     error_category?: string | null;
     /** Whether retrying the same run can succeed. Absent or `null` means unknown, never "no". */
     retryable?: boolean | null;
-    /** The next step the runner advises. */
+    /** The next step the runner advises. The platform serves it only beside caller-facing copy. */
     user_action?: UserAction | null;
-    /** The model the failing call used, when the failure is an inference failure. */
+    /**
+     * The model the failing call used, when the failure is an inference failure. Absent on a
+     * hosted read, whose STRICT projection drops it.
+     */
     model?: string | null;
-    /** The provider the failing call reached, when the failure is an inference failure. */
+    /**
+     * The provider the failing call reached, when the failure is an inference failure. Absent on
+     * a hosted read, whose STRICT projection drops it.
+     */
     provider?: string | null;
-    /** What the provider's SDK said, when the failure came back from a provider. */
+    /**
+     * What the provider's SDK said, when the failure came back from a provider. A hosted read
+     * keeps only its `status_code` and `retry_after_seconds`.
+     */
     provider_metadata?: ProviderErrorMetadata | null;
-    /** True when `message` was written as caller-facing copy. The runner emits it only when true. */
+    /**
+     * True when `message` was written as caller-facing copy. The runner emits it only when true,
+     * and the platform keeps it on a caller-facing report and leaves it out otherwise, so it is how
+     * a consumer tells the author's copy from the placeholder.
+     */
     caller_facing_message?: boolean | null;
     /**
      * The structured diagnostics of a bundle that failed validation — the same items the
      * validate report and a `422`'s `ApiResponseError.validationErrors` carry.
      */
     validation_errors?: ValidationErrorItem[] | null;
-    /** A pending configuration migration that explains the failure. */
+    /**
+     * A pending configuration migration that explains the failure. Absent on a hosted read, whose
+     * STRICT projection drops it.
+     */
     migration?: MigrationErrorBlock | null;
     /** Fields a newer runner adds, reachable before this SDK names them. */
     [extension: string]: unknown;
@@ -207,6 +247,12 @@ export interface ProblemDetails {
 }
 /** Whether a value is a plain object: an object that is neither `null` nor an array. */
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Drop each of `fields` from `record` when it is present and fails `fits`. `null` always fits,
+ * since every field of these shapes allows it. Internal: the run status read's degradation
+ * (`readRunDegradation` in `runs.ts`) is checked with it too.
+ */
+export declare function dropUnfit(record: Record<string, unknown>, fields: readonly string[], fits: (value: unknown) => boolean): void;
 /**
  * `provider_metadata`, its named string fields kept as strings and `status_code` and
  * `retry_after_seconds` as a number or a string; its other members are relayed as sent.

package/dist/error-models.js

@@ -4,9 +4,10 @@
  *
  * **The runner owns these shapes; this SDK follows them.** A run that fails reports why as
  * the runner's `ErrorReport` (`pipelex.base_exceptions`), which the hosted platform stores
- * whole on the run row as `error` and serves as it was stored: on the status read
- * (`RunRead.error`), on the run records (`PipelineRun.error`), and inside the problem
- * document of the results read's `409`, where the client lifts it onto the failed arm of
+ * whole on the run row as `error` and serves through the runner's STRICT disclosure: on the
+ * status read (`RunRead.error`), on the run records (`PipelineRun.error`,
+ * `RunHistoryItem.error`), and inside the problem document of the results read's `409`, where
+ * the client lifts it onto the failed arm of
  * `RunResultState` and onto `RunFailedError.error`. The same classification fields
  * (`error_domain`, `user_action`, …) ride a runner-rendered problem document as extension
  * members, which is why `ApiResponseError` types its members with the models declared here.
@@ -26,10 +27,19 @@
  * `providerMetadata`, `migration`, `validationErrors` and `errors` hold to their types as a stored
  * report's do.
  *
- * **Nothing else is stripped.** The platform serves the runner's VERBOSE report, so `message` and
- * `provider_metadata` can hold a provider's raw text. Deciding what of it a person should see
- * is each consumer's presentation, not this SDK's; the report arrives here whole, members this
- * SDK does not name included.
+ * **The platform serves the STRICT projection; this SDK strips nothing further.** The run row
+ * keeps the runner's VERBOSE report as the operators' record, and every read that hands it to a
+ * caller serves the rule the hosted runner applies to an error on `execute`: `error_type`,
+ * `title`, `type_uri`, `error_domain`, `error_category`, `retryable` and `validation_errors`
+ * pass through; `message` and `user_action` pass through only when `caller_facing_message` is
+ * `true`, which the served report then keeps, and otherwise `message` is the placeholder
+ * `An internal error occurred.` while `user_action` and the flag are absent; `provider_metadata`
+ * keeps only `status_code` and `retry_after_seconds`; `model`, `provider` and `migration` are
+ * absent. The reports the platform writes itself are caller-facing copy, so they keep their
+ * message and their next step. A platform run locally with `ERROR_DISCLOSURE=verbose` serves the
+ * report whole, which is why the types still name every member the runner writes. Deciding what
+ * a person should see is each consumer's presentation; the report arrives here as served,
+ * members this SDK does not name included.
  */
 // ── Checking a stored report, and a problem document's nested members ─
 //
@@ -66,9 +76,10 @@ export function isPlainObject(value) {
 }
 /**
  * Drop each of `fields` from `record` when it is present and fails `fits`. `null` always fits,
- * since every field of these shapes allows it.
+ * since every field of these shapes allows it. Internal: the run status read's degradation
+ * (`readRunDegradation` in `runs.ts`) is checked with it too.
  */
-function dropUnfit(record, fields, fits) {
+export function dropUnfit(record, fields, fits) {
     for (const field of fields) {
         if (!Object.hasOwn(record, field))
             continue;

package/dist/error-models.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-models.js","sourceRoot":"","sources":["../src/error-models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAuLH,yEAAyE;AACzE,EAAE;AACF,+FAA+F;AAC/F,2CAA2C;AAE3C,6FAA6F;AAC7F,MAAM,oBAAoB,GAAG;IAC3B,YAAY;IACZ,SAAS;IACT,OAAO;IACP,UAAU;IACV,cAAc;IACd,gBAAgB;IAChB,OAAO;IACP,UAAU;CACF,CAAC;AAEX,8EAA8E;AAC9E,MAAM,qBAAqB,GAAG,CAAC,WAAW,EAAE,uBAAuB,CAAU,CAAC;AAE9E,gDAAgD;AAChD,MAAM,sBAAsB,GAAG;IAC7B,UAAU;IACV,oBAAoB;IACpB,SAAS;IACT,YAAY;IACZ,qBAAqB;CACb,CAAC;AAEX,qGAAqG;AACrG,MAAM,uBAAuB,GAAG,CAAC,aAAa,EAAE,qBAAqB,CAAU,CAAC;AAEhF,gFAAgF;AAChF,MAAM,yBAAyB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAU,CAAC;AAEvE,wFAAwF;AACxF,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,SAAS,SAAS,CAChB,MAA+B,EAC/B,MAAyB,EACzB,IAAiC;IAEjC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;YAAE,SAAS;QAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC;AAED,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAW,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC;AACxE,MAAM,SAAS,GAAG,CAAC,KAAc,EAAW,EAAE,CAAC,OAAO,KAAK,KAAK,SAAS,CAAC;AAC1E,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAAW,EAAE,CACnD,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC;AAEzD,kGAAkG;AAClG,SAAS,cAAc,CAAC,KAA8B;IACpD,OAAO,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;QACvE,CAAC,CAAE,EAAE,GAAG,KAAK,EAA4B;QACzC,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAA8B;IACjE,MAAM,QAAQ,GAA4B,EAAE,GAAG,KAAK,EAAE,CAAC;IACvD,SAAS,CAAC,QAAQ,EAAE,sBAAsB,EAAE,QAAQ,CAAC,CAAC;IACtD,SAAS,CAAC,QAAQ,EAAE,uBAAuB,EAAE,gBAAgB,CAAC,CAAC;IAC/D,OAAO,QAAiC,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAA8B;IAC1D,MAAM,SAAS,GAA4B,EAAE,GAAG,KAAK,EAAE,CAAC;IACxD,SAAS,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC3C,SAAS,CAAC,SAAS,EAAE,CAAC,aAAa,EAAE,iBAAiB,CAAC,EAAE,SAAS,CAAC,CAAC;IACpE,IAAI,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,SAAS,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAClE,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC;YAAE,SAAS,CAAC,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;;YACvF,OAAO,SAAS,CAAC,KAAK,CAAC;IAC9B,CAAC;IACD,OAAO,SAAgC,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,aAAa,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AACrF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAA8B;IAC3D,MAAM,IAAI,GAA4B,EAAE,GAAG,KAAK,EAAE,CAAC;IACnD,SAAS,CAAC,IAAI,EAAE,yBAAyB,EAAE,QAAQ,CAAC,CAAC;IACrD,OAAO,IAAkB,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,MAAM,GAA4B,EAAE,GAAG,KAAK,EAAE,CAAC;IACrD,SAAS,CAAC,MAAM,EAAE,oBAAoB,EAAE,QAAQ,CAAC,CAAC;IAClD,SAAS,CAAC,MAAM,EAAE,qBAAqB,EAAE,SAAS,CAAC,CAAC;IACpD,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,cAAc,CAAC,CAAC;IAClD,UAAU,CAAC,MAAM,EAAE,mBAAmB,EAAE,oBAAoB,CAAC,CAAC;IAC9D,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;IAC/C,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,IAAI,MAAM,CAAC,iBAAiB,KAAK,IAAI,EAAE,CAAC;QACpF,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,EAAE,CAAC;YAC5C,MAAM,CAAC,iBAAiB,GAAG,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;QAC/E,CAAC;aAAM,CAAC;YACN,OAAO,MAAM,CAAC,iBAAiB,CAAC;QAClC,CAAC;IACH,CAAC;IACD,OAAO,MAAwB,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU,CACjB,MAA+B,EAC/B,KAAa,EACb,IAAiD;IAEjD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,OAAO;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO;IAC3B,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5D,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;;QACxC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"error-models.js","sourceRoot":"","sources":["../src/error-models.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -2,8 +2,9 @@
  * Pipelex SDK errors — the argument, transport, run-lifecycle, input-preparation and artifact
  * errors `PipelexApiClient` raises. Every one derives from `PipelexRequestError`, itself a
  * `PipelineRequestError` (the protocol base, re-exported from `mthds/protocol`), and so carries
- * a verdict: `retryable` and `errorDomain`, always decided. The one exported error outside the
- * family, `CodegenLockError`, declares the same two members itself.
+ * a verdict: `retryable` and `errorDomain`, always decided, and `runMayHaveStarted`, which says
+ * whether a failed start or execute may still have started a run. The one exported error outside
+ * the family, `CodegenLockError`, declares the verdict's two members itself.
  */
 import { PipelineRequestError } from "mthds/protocol";
 import type { ValidationErrorItem } from "./models.js";
@@ -30,9 +31,11 @@ export declare function isErrorDomain(value: unknown): value is ErrorDomain;
  * The verdict an error carries: whether asking again can plausibly succeed (`retryable`), and who
  * can fix the failure (`errorDomain`). Both are always decided.
  *
- * "Retryable" says a retry can succeed, never that it is safe: it says nothing about whether the
- * first attempt had an effect. A start answered with a `500` may already have created a run, so a
- * caller that must not start a run twice decides that for itself.
+ * "Retryable" says a retry can succeed, and on a request that may create a run, that it cannot
+ * start a second one: a failed `start` or `execute` that may still have started a run (an error
+ * whose `runMayHaveStarted` is true) is never retryable, whatever the server or the fallback table
+ * says, since asking again could pay for the run twice. Everywhere else it says nothing about
+ * whether the first attempt had an effect.
  */
 export interface ErrorVerdict {
     readonly retryable: boolean;
@@ -40,21 +43,35 @@ export interface ErrorVerdict {
 }
 /**
  * The base of every error this SDK raises over a request, carrying the verdict as two readonly
- * own properties: `retryable` and `errorDomain`. Each subclass passes its verdict to this
- * constructor, so a class that forgets one does not compile, and every class says its verdict
- * where it is defined.
+ * own properties, `retryable` and `errorDomain`, and a third, `runMayHaveStarted`. Each subclass
+ * passes its verdict to this constructor, so a class that forgets one does not compile, and every
+ * class says its verdict where it is defined.
+ *
+ * `runMayHaveStarted` is false unless the subclass passes it: only `ApiUnreachableError` and
+ * `ApiResponseError` built for a request that may create a run, and `PipelineExecuteTimeoutError`,
+ * ever carry it as true, and when they do, `retryable` is false whatever the verdict passed.
  *
  * It refines the standard's `PipelineRequestError`, so `instanceof PipelineRequestError` still
  * matches every SDK error. To read a verdict from anything a `catch` holds, use
- * `errorVerdictOf`, which also reads it off an error raised by another copy of this SDK.
+ * `errorVerdictOf`, which also reads it off an error raised by another copy of this SDK, and
+ * `runMayHaveStartedOf` for the third member.
  */
 export declare abstract class PipelexRequestError extends PipelineRequestError implements ErrorVerdict {
     /** Whether asking again can plausibly succeed. Always decided. */
     readonly retryable: boolean;
     /** Who can fix the failure: `input`, `config` or `runtime`. Always decided. */
     readonly errorDomain: ErrorDomain;
+    /**
+     * Whether the failed request may still have started a run whose id never reached the caller:
+     * a `start` or an `execute` (and so `startAndWaitForResult`'s start, or the blocking execute it
+     * falls back to) that failed in a way that does not prove the server started nothing. When it
+     * is true, `retryable` is false: look the run up in the run history before starting it again.
+     * False for every other request, a wait on a run already named included. Always decided.
+     */
+    readonly runMayHaveStarted: boolean;
     constructor(message: string, verdict: ErrorVerdict, options?: {
         cause?: unknown;
+        runMayHaveStarted?: boolean;
     });
 }
 /**
@@ -70,6 +87,16 @@ export declare abstract class PipelexRequestError extends PipelineRequestError i
  * for what it asks is a `RequestArgumentError`, which carries one.
  */
 export declare function errorVerdictOf(err: unknown): ErrorVerdict | undefined;
+/**
+ * Whether anything a `catch` holds is a failed run start that may still have started a run: true
+ * only for an `Error` carrying `runMayHaveStarted` as `true`.
+ *
+ * The check is structural, as `errorVerdictOf`'s is, so it reads an error raised by another copy
+ * of this SDK installed beside this one. Anything else is false: an error of a request that
+ * cannot start a run, an `mthds` error, which the standard's client never raises over a start of
+ * this SDK, and a value that is not an `Error`.
+ */
+export declare function runMayHaveStartedOf(err: unknown): boolean;
 /**
  * The SDK refused a call's arguments before sending any request: no run source given to
  * `execute()` or `start()`, run sources or method selectors that exclude each other, a selector
@@ -148,6 +175,35 @@ export declare class InvalidInputValueError extends InputPreparationError {
         cause?: unknown;
     });
 }
+/**
+ * What a value refused under `allowUploads: false` is, in a closed vocabulary a caller branches on
+ * rather than on the message: `local_path` — a string that is neither an `http(s)` URL nor a
+ * `pipelex-storage://` reference, which preparation would read from disk; `data_url` — a `data:`
+ * URL, which it would decode and upload; `bytes` — a `Blob`, `File`, `ArrayBuffer` or `Uint8Array`.
+ */
+export type UploadNotAllowedKind = "local_path" | "data_url" | "bytes";
+/**
+ * `prepareInputs` was called with `allowUploads: false`, and a value at a file input would need an
+ * upload: a local path, a `data:` URL or bytes. It is raised before anything is read from disk,
+ * decoded or sent to the upload route, so a server preparing inputs on a caller's behalf never
+ * reads a file of its own because the caller named it. `inputName` is the input the value belongs
+ * to, `inputPath` where it sits inside that input (`report.attachments[1]`, or the name alone for a
+ * top-level file), and `valueKind` what it is. The value itself is neither in the message nor on
+ * the error, since it is the caller's data. Its verdict is `input`, not retryable: the caller must
+ * pass an `http(s)` URL or a `pipelex-storage://` reference instead.
+ */
+export declare class UploadNotAllowedError extends InputPreparationError {
+    readonly inputName: string;
+    readonly inputPath: string;
+    readonly valueKind: UploadNotAllowedKind;
+    constructor(details: {
+        inputName: string;
+        inputPath: string;
+        valueKind: UploadNotAllowedKind;
+    }, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * The pipe I/O answer said the method does not load (`is_valid: false`), so its signature cannot
  * be read and no input can be prepared: the method, not the inputs, must change.
@@ -376,12 +432,19 @@ export declare class ArtifactAuthenticationError extends ArtifactOperationError
  * attempt can get through. With the code `ABORT_TIMEOUT`, the SDK's own request timeout, it is
  * `runtime` and retryable instead: the API took the request and did not answer in time, which is
  * no fault of the base URL.
+ *
+ * On a request that may create a run (`options.mayStartRun`, which the client sets on `start` and
+ * `execute`), `runMayHaveStarted` is true unless `cause`, the failure fetch threw, proves the
+ * request never left: the name lookup, the connection or the TLS handshake failed. A reset, a time
+ * limit or a body that could not be decoded proves nothing, so the run may have started and the
+ * error is not retryable.
  */
 export declare class ApiUnreachableError extends PipelexRequestError {
     readonly apiUrl: string;
     readonly code: string | undefined;
     constructor(message: string, apiUrl: string, code: string | undefined, options?: {
         cause?: unknown;
+        mayStartRun?: boolean;
     });
 }
 /**
@@ -391,7 +454,8 @@ export declare class ApiUnreachableError extends PipelexRequestError {
  * lifecycle (start + poll) instead.
  *
  * Its verdict is `input`, not retryable: asking again meets the same limit, and the caller fixes
- * it by starting the run and polling.
+ * it by starting the run and polling. `runMayHaveStarted` is always true: the gateway gave up on
+ * the request, and the run it carried goes on without its id reaching the caller.
  */
 export declare class PipelineExecuteTimeoutError extends PipelexRequestError {
     readonly elapsedMs: number;
@@ -407,15 +471,21 @@ export declare class PipelineExecuteTimeoutError extends PipelexRequestError {
  *
  * - `status` is the run's terminal status, read from the problem's `run_status` member, or from
  *   its `detail` sentence on a platform that predates the member.
- * - `error` is the run's stored error report, typed whole as `RunErrorReport`: the runner's
- *   `error_type`, `message`, `title`, `type_uri`, `error_domain`, `error_category`,
- *   `retryable`, `user_action`, `model`, `provider`, `provider_metadata`, `validation_errors`
- *   and anything newer through its index signature. Branch on `error.error_domain`,
- *   `error.type_uri` and `error.retryable`; show `error.user_action` as the next step. It is
- *   the runner's VERBOSE report, so `message` and `provider_metadata` can hold a provider's raw
- *   text — deciding what a person sees is the consumer's. `null` when the run ended with no
- *   stored report (a cancelled, terminated or timed-out run, or one the platform finalized
- *   itself).
+ * - `error` is the run's stored error report as the platform serves it, typed whole as
+ *   `RunErrorReport`: the runner's `error_type`, `message`, `title`, `type_uri`, `error_domain`,
+ *   `error_category`, `retryable`, `user_action`, `provider_metadata`, `caller_facing_message`,
+ *   `validation_errors` and anything newer through its index signature. Branch on
+ *   `error.error_domain`, `error.type_uri` and `error.retryable`; show `error.user_action` as the
+ *   next step. The platform serves the runner's STRICT projection, so `message` is the author's
+ *   copy only when `caller_facing_message` is `true` and the placeholder
+ *   `An internal error occurred.` otherwise, `user_action` comes only with caller-facing copy,
+ *   `provider_metadata` keeps only `status_code` and `retry_after_seconds`, and `model`,
+ *   `provider` and `migration` are absent; deciding what a person sees is still the consumer's.
+ *   A run the platform ended or settled itself carries the caller-facing report the platform
+ *   wrote, in the same shape. A cancelled, terminated or timed-out run carries a report when a
+ *   completion callback carried one, and a timed-out run otherwise the platform's timeout report.
+ *   `null` when the run ended with no stored report (one whose start failed, or one cancelled,
+ *   terminated or given its status by hand with no completion callback carrying a report).
  * - The error's own `message` is the problem's `detail`, which names the status and then the
  *   report's message (`Run finished with status FAILED: <message>`), so printing the error
  *   already tells the reason.
@@ -535,13 +605,21 @@ export declare class PagingNotTerminatingError extends PipelexRequestError {
 export type MethodErrorCode = "method_update_conflict" | "method_being_deleted" | "method_not_published" | "method_version_not_found";
 /**
  * The last constructor argument of `ApiResponseError`: the error's `cause`, the problem
- * document's typed members, and the decoded document whole. The same shape as `mthds`'s
- * `ApiResponseErrorOptions`, plus `problemDocument`.
+ * document's typed members, the decoded document whole, and whether the request that met the
+ * answer may create a run. The same shape as `mthds`'s `ApiResponseErrorOptions`, plus
+ * `problemDocument` and `mayStartRun`.
  */
 export interface ApiResponseErrorOptions {
     cause?: unknown;
     problem?: ProblemDetails;
     problemDocument?: Record<string, unknown>;
+    /**
+     * The request was a `start` or an `execute`, so the answer is read for whether it may have
+     * started a run (see `ApiResponseError.runMayHaveStarted`). The client sets it on those two
+     * routes alone; a consumer building the error by hand sets it to get the verdict the client
+     * would give.
+     */
+    mayStartRun?: boolean;
 }
 /**
  * A response that DID come back from the API and that the SDK cannot hand back as a result: a
@@ -568,6 +646,14 @@ export interface ApiResponseErrorOptions {
  *   stored report that says nothing is not, since the caller or the environment must change,
  *   while `runtime` takes the fallback's. Nothing on the error says which a value came from:
  *   `problemDocument` keeps what the server sent.
+ * - **A run that may have started.** On a `start` or an `execute`, `runMayHaveStarted` says
+ *   whether the answer leaves a run possibly started without its id reaching the caller: any
+ *   `2xx` the SDK could not read, a `408`, and every `5xx` but a `501` and the platform's `503`
+ *   coded `pipeline_start_unavailable`, which says the runner was never reached. Then
+ *   `retryable` is false, whatever the server sent: asking again could start a second run. A
+ *   runner's own failure of a blocking execute reads the same, since the SDK cannot tell a run
+ *   that ended from one that goes on, and its `retryable` stays readable on `problemDocument`.
+ *   On every other route it is false.
  * - **The branch fields.** `errorDomain`, and `type`, the stable URI naming the error class.
  *   Branch on these, never on the HTTP status or on the wording of a message; they are the
  *   fields that mean the same on both surfaces.
@@ -636,7 +722,13 @@ export declare class ApiResponseError extends PipelexRequestError {
     readonly model: string | undefined;
     /** The body's `provider`: the provider an inference failure reached. */
     readonly provider: string | undefined;
-    /** The body's `provider_metadata`: what the provider's SDK said, raw text included. */
+    /**
+     * The body's `provider_metadata`: what the provider's SDK said. On the hosted API it comes
+     * from the runner's problem document, which the hosted runner renders under its STRICT
+     * disclosure, so it keeps only `status_code` and `retry_after_seconds`; a runner that
+     * discloses errors VERBOSE, as a self-hosted one does when `ERROR_DISCLOSURE` is unset, sends
+     * it whole, the provider's raw text included.
+     */
     readonly providerMetadata: ProviderErrorMetadata | undefined;
     /** The body's `migration`: a pending configuration migration that explains the failure. */
     readonly migration: MigrationErrorBlock | undefined;