@pipelex/sdk 0.52.0 → 0.53.0

package/docs/method-trees.md

@@ -33,7 +33,7 @@ const verdict = await client.validate({
 
 **A directory is listed by the standard's lister.** The client loads the `mthds` package's `listMethodTree` when a call gives a `directory`, and lists it under the MTHDS standard's membership rule and Manifest Discovery: the tree is rooted at the nearest `METHODS.toml` at or above the directory, else at the directory itself, and holds every file the rule keeps. Hidden entries, `node_modules`, `__pycache__`, what a `.gitignore` or the manifest's `exclude` keeps out, and **a run's inputs file** (`inputs.json`, `inputs.toml`) never travel with the method. A tree holding a symbolic link or a special file is refused rather than followed. The directory is listed under the limits the deployment announces (below), so a tree the deployment would refuse for its size is refused while it is listed, before any file is hashed. Every refusal is a `RequestArgumentError` naming the call and the directory, whose `cause` is `mthds`'s `MethodTreeError`, with its `code` (`not_found`, `symbolic_link`, `limit_exceeded`, `empty_tree` and the rest). Listing needs Node: the lister comes from the Node host ([architecture.md](./architecture.md#the-node-host)), so a bundle built for the browser holds none of it, and a `directory` given outside Node is refused with `RequestArgumentError` before the version handshake, so before any request, and a browser gives `contents`, `tree` or `files`.
 
-**A map in memory.** A text in `contents` is encoded in UTF-8, and a text a file cannot hold, one carrying a lone surrogate, is refused, as is a value that is neither a string nor a `Uint8Array`. The keys are sent as they are, and the platform refuses one that is not a tree path with the `422` `invalid_method_files` naming it.
+**A map in memory.** A text in `contents` is encoded in UTF-8, and a text a file cannot hold, one carrying a lone surrogate, is refused, as is a value that is neither a string nor a `Uint8Array`. The keys are sent as they are, and the platform refuses one that is not a tree path with a `422` `method.package_invalid` whose `params` name its `path`.
 
 **One form, and never an empty tree.** Two forms at once are refused with a `RequestArgumentError` before anything is read or sent. A `files` map, `contents` or a `tree` holding no file is refused too on the run routes and on `validate`, as the standard refuses it: a tree holds at least one file. On the crate routes and in `prepareInputs`, an empty map is absent instead, so it never reaches the wire as a second selector, and in a save `files: null` empties the draft. An empty `directory` string is absent everywhere.
 
@@ -46,42 +46,41 @@ A tree given as a `directory`, `contents` or `tree` is sent by the rule the `mth
 
 A `files` map is sent as given, with no handshake. A run's `start` carrying a tree, a run that names a `method_ref`, and a start whose `extra` carries a method bundle (`mthds_contents` or `bundle_b64`, as the `pipelex-sdk` command sends one) get the client's request ceiling rather than the 30-second start budget, since the body can be large. On the crate routes, a request whose `files` carry more than `INLINE_TREE_MAX_BYTES` inline, as a tree sent to an API keeping no blob store or a `files` map given as is may, gets the request ceiling too rather than the 30-second budget of a static route ([crate-routes.md](./crate-routes.md)). A save carrying a tree (`createMethod`, `writeDraft`), inline or by hash, gets the request ceiling as well, rather than the 30-second budget of a save sending none, since a tree sent inline to an API keeping no blob store can be large and its whole upload is charged against the budget.
 
-**A refusal of the tree's size is sent once more.** When the API refuses a tree the client prepared, a `directory`, `contents` or `tree`, as past one of its limits (a `422` coded `method_tree_too_large`, or `method.package_invalid` naming a limit, or of type `MethodTreeTooLarge`), the handshake that announced the limits may be stale: the client forgets it, prepares the tree again on a fresh one and sends the request once more, as `mthds`'s client does. A `files` map given as is was not prepared from the handshake, so it is not sent again, and neither is a `start` under an idempotency key, since the platform binds the key to the refusal it stores.
+**A refusal of the tree's size is sent once more.** When the API refuses a tree the client prepared, a `directory`, `contents` or `tree`, as past one of its limits (a `422` `method.package_invalid` whose `params` carry `reason` `too_large` and an integer `limit`), the handshake that announced the limits may be stale: the client forgets it, prepares the tree again on a fresh one and sends the request once more, as `mthds`'s client does. A `files` map given as is was not prepared from the handshake, so it is not sent again, and neither is a `start` under an idempotency key, since the platform binds the key to the refusal it stores.
 
 **Stopping a call.** A call that takes a `signal` (`validate`, `startAndWaitForResult`, the crate routes, `prepareInputs`) reads it before each step a `directory`, `contents` or `tree` costs and hands it to the step's request, so an abort stops the version handshake, the directory's listing, the blob route, a file's read and an upload already under way, and nothing further starts.
 
 A `MethodTree` reads a file again whenever its bytes are sent, inline or as an upload, and checks it against the hash its listing recorded, so a file changed since the listing is refused by `mthds` rather than sent as another tree than the one listed. Apart from listing a directory, sending a tree reads no Node module: hashing is Web Crypto's, and Base64 is written by the SDK.
 
-**What is uploaded is what the listing names.** Before each upload the client hashes the bytes a tree's `readFile` gives and refuses them, with a `RequestArgumentError`, unless they have the size and the SHA-256 the tree lists for them: a blob is stored under its hash for the whole organization, so a hand-built `MethodTreeSource` whose `readFile` disagrees with its listing never stores other bytes under that hash. An answer of `POST /v1/blobs/missing` asking for a blob the tree does not hold is the platform's fault, not the caller's: it is an `ApiResponseError` of an answer the SDK cannot read, verdict `runtime` and not retryable, thrown before any upload. An upload that fails throws `MethodFileTransferError` with `operation` `upload`, and the request is not sent or the method not saved ([below](#when-a-transfer-fails)).
+**What is uploaded is what the listing names.** Before each upload the client hashes the bytes a tree's `readFile` gives and refuses them, with a `RequestArgumentError`, unless they have the size and the SHA-256 the tree lists for them: a blob is stored under its hash for the whole organization, so a hand-built `MethodTreeSource` whose `readFile` disagrees with its listing never stores other bytes under that hash. An answer of `POST /v1/blobs/missing` asking for a blob the tree does not hold is the platform's fault, not the caller's: it is an `ApiResponseError` of an answer the SDK cannot read, `client.response_unreadable`, thrown before any upload. An upload that fails throws `MethodFileTransferError` with `operation` `upload`, and the request is not sent or the method not saved ([below](#when-a-transfer-fails)).
 
-**A blob that went missing.** A request whose hash entries name a blob the API does not hold is refused with a `422` `missing_blobs` listing them all, which also releases a start's idempotency key. A request built from a `directory`, `contents` or `tree` uploads every blob it names first, so it meets this only if a blob was removed between the upload and the request. The client answers it as `mthds`'s client does: a `422` problem coded `request.blobs_missing`, whose `params.missing_blobs` names blobs the tree holds, has those blobs asked of the blob route again, uploaded and the request sent once more, while the platform's `missing_blobs` code is not read as one and is thrown, so sending the same call again asks the blob route afresh and uploads what is missing.
+**A blob that went missing.** A request whose hash entries name a blob the API does not hold is refused with a `422` `request.blobs_missing` whose `params.missing_blobs` lists them all, which also releases a start's idempotency key. A request built from a `directory`, `contents` or `tree` uploads every blob it names first, so it meets this only if a blob was removed between the upload and the request. The client answers it as `mthds`'s client does: when the listed blobs are ones the tree holds, it asks the blob route for them again, uploads them and sends the request once more; any other answer is thrown, so sending the same call again asks the blob route afresh and uploads what is missing.
 
 On the crate routes, `read_scope` is the scope the blob route is asked under, so the blobs are uploaded into the store the request's hash entries are read from; the hosted platform reads the caller's organization whatever the request says ([crate-routes.md](./crate-routes.md#the-shared-envelope)).
 
 ## The files a step reads
 
-A file a step reads, such as a `PipeDocGen` step's `template_file` (the Word, Excel or PowerPoint template it fills, or the HTML template it prints as a PDF), is a file of the tree like any other, at the tree path the step names from the root. A `directory` sends it with the bundles; a `contents` or `files` map carries it under its tree path. A step that names a file the tree does not hold cannot load: on `validate`, `pipeIo`, `resolve` and `codegen` that is an `is_valid: false` verdict whose validation error says the file is missing, `prepareInputs` throws it as a `MethodLoadError`, and on `execute` and `start` it is a `422` `ValidateBundleError`, whose `validationErrors` say the same.
+A file a step reads, such as a `PipeDocGen` step's `template_file` (the Word, Excel or PowerPoint template it fills, or the HTML template it prints as a PDF), is a file of the tree like any other, at the tree path the step names from the root. A `directory` sends it with the bundles; a `contents` or `files` map carries it under its tree path. A step that names a file the tree does not hold cannot load: on `validate`, `pipeIo`, `resolve` and `codegen` that is an `is_valid: false` verdict whose problem item says the file is missing (`method.resource_missing`), `prepareInputs` throws it as a `MethodLoadError`, and on `execute` and `start` it is a `422` problem whose `errors` say the same.
 
 ### The template check's warnings
 
-A dry run hands an office template file of the tree to the document engine's template check. An error finding fails the step's dry run, and so the verdict, as a `dry_run` validation error on the step. A warning finding, such as a field of the template that matches no input, rides the valid verdict's `warnings` as a `template_check_warning` item:
+A dry run hands an office template file of the tree to the document engine's template check. An error finding fails the step's dry run, and so the verdict, as a problem item on the step. A warning finding, such as a field of the template that matches no input, rides the valid verdict's `warnings` as a problem item coded `pipelex.docgen.template_warning`:
 
 | Member | Value |
 | --- | --- |
-| `category` | `dry_run` |
-| `error_type` | `template_check_warning` |
-| `pipe_code`, `domain_code` | The `PipeDocGen` step |
-| `template_file` | The template file as the step names it; `null` for a step of the server's own library, whose path is never shown |
-| `template_location` | The place in the file the finding names, in the engine's words (a defined name, a table, a cell, a shape, a tag); `null` when it names none |
-| `message` | The finding in words |
+| `code` | `pipelex.docgen.template_warning` |
+| `location.pipe` | The `PipeDocGen` step |
+| `params.template` | The template file as the step names it |
+| `params.finding` | The finding in the engine's words |
+| `detail` | The sentence a person reads, naming the template and the finding |
 
-The warnings come in families, always in this order: `optional_force_redundant`, `input_presence_vacuous`, the `hint_*` lints, then `template_check_warning`. None of them flips `is_valid`.
+The warnings come in families, always in this order: `method.optional_force_redundant`, `method.input_presence_vacuous`, the hint lints (`method.hint_invalid`), then `pipelex.docgen.template_warning`. None of them flips `is_valid`.
 
 ```ts
 if (verdict.is_valid) {
   for (const warning of verdict.warnings) {
-    if (warning.error_type === "template_check_warning") {
-      console.warn(`${warning.template_file ?? "?"} ${warning.template_location ?? ""}: ${warning.message}`);
+    if (warning.code === "pipelex.docgen.template_warning") {
+      console.warn(`${warning.location?.pipe ?? "?"}: ${warning.detail}`);
     }
   }
 }
@@ -127,11 +126,11 @@ The save is refused, with the `ApiResponseError` of its problem, when the platfo
 
 | Status and `code` | When |
 |---|---|
-| `422` `invalid_method_files` | The map breaks the standard's rules, a path that is not a tree path or two paths that collide among them; the problem's `tree_refusal` names the rule. |
-| `422` `method_tree_too_large` | The tree passes one of the deployment's limits, which the problem's `limit` names. |
-| `422` `blob_mismatch` | A hash entry states another size than the blob the organization holds under that hash. |
-| `422` `missing_blobs` | A hash entry names bytes the organization does not hold (above). |
-| `413` `payload_too_large` | The method would leave no room for the summary a publish adds. |
+| `422` `method.package_invalid` | The map breaks the standard's rules, a path that is not a tree path or two paths that collide among them; the problem names the path. |
+| `422` `method.package_invalid` | The tree passes one of the deployment's limits, which the problem's `params` name (`reason` `too_large` and the `limit`). |
+| `422` `request.invalid` | A hash entry states another size than the blob the organization holds under that hash. |
+| `422` `request.blobs_missing` | A hash entry names bytes the organization does not hold (above). |
+| `413` `request.too_large` | The method would leave no room for the summary a publish adds. |
 
 ## The deployment's limits
 
@@ -162,7 +161,7 @@ An empty draft lists no file and has a `draft_digest` of `null`. The listing pag
 
 **A link is a bearer credential.** Anyone holding it reads the file until it expires, so it belongs in no log, message or stored record; this SDK puts it in none of its errors, not even when the answer that carried it cannot be read. A read that fails because a link expired succeeds once the method is read again.
 
-A method whose draft names a tree the platform holds no record of answers `getMethod` with a `409` whose verdict is `runtime`, and a version stored before methods were trees and never rewritten as one names no tree to serve, so `getMethodVersion` answers it with `409` `conflict`, whose verdict is `runtime` too. An answer whose `files` is not a listing, each entry with its string `path`, `url` and `expires_at`, a `sha256` of 64 lower-case hex digits and a non-negative integer `size`, is an `ApiResponseError` naming the entry at fault. Such an answer, like any other the SDK cannot read from these two routes or from `POST /v1/blobs/missing`, reaches its error redacted: `responseBody` has every `url` member and every link's query replaced by `[redacted]`, and the error keeps no `cause`, since a parse failure can quote the body.
+A method whose draft names a tree the platform holds no record of answers `getMethod` with a `500` `runtime.unexpected`, and a version stored before methods were trees and never rewritten as one names no tree to serve, so `getMethodVersion` answers it with `500` `runtime.unexpected` too. An answer whose `files` is not a listing, each entry with its string `path`, `url` and `expires_at`, a `sha256` of 64 lower-case hex digits and a non-negative integer `size`, is an `ApiResponseError` naming the entry at fault. Such an answer, like any other the SDK cannot read from these two routes or from `POST /v1/blobs/missing`, reaches its error redacted: `responseBody` has every `url` member and every link's query replaced by `[redacted]`, and the error keeps no `cause`, since a parse failure can quote the body.
 
 ## Writing a tree to disk
 
@@ -179,16 +178,16 @@ Each file is downloaded through its link, at most eight at a time, with no crede
 
 ## When a transfer fails
 
-`MethodFileTransferError` is thrown when a file could not be moved between this machine and storage. `operation` says which way (`upload` for a request or a save that sends a tree by hash, `download` for `writeMethodTree`), `code` why, `sha256` which bytes, `path` the tree path when one is known, and `status` storage's HTTP status when it answered. Neither its message nor any member carries the link, nor storage's error body, which can echo the signed request, and it keeps no `cause`: the failure `fetch` throws for a request that got no answer can quote the URL, so only its network code (`ECONNREFUSED`, `ABORT_TIMEOUT`) reaches the message.
+`MethodFileTransferError` is thrown when a file could not be moved between this machine and storage. `operation` says which way (`upload` for a request or a save that sends a tree by hash, `download` for `writeMethodTree`), `reason` why, `sha256` which bytes, `path` the tree path when one is known, and `status` storage's HTTP status when it answered. Neither its message nor any member carries the link, nor storage's error body, which can echo the signed request, and it keeps no `cause`: the failure `fetch` throws for a request that got no answer can quote the URL, so only its network code (`ECONNREFUSED`, `ABORT_TIMEOUT`) reaches the message.
 
-| `code` | When | Retryable |
+| `reason` | When | Its problem |
 |---|---|---|
-| `unreachable` | Storage gave no answer: the connection failed or the time limit ran out. | yes |
-| `storage_error` | Storage timed out or throttled the request (`408`, `429`) or failed (a `5xx` other than `501`). | yes |
-| `refused` | Storage refused the request with any other status, an expired link among them. Read the method again for fresh links. | no |
-| `mismatch` | A download's bytes are not the file the listing names: another size, or another SHA-256. | yes |
+| `unreachable` | Storage gave no answer: the connection failed or the time limit ran out. | `runtime.unavailable` |
+| `storage_error` | Storage timed out or throttled the request (`408`, `429`) or failed (a `5xx` other than `501`). | `runtime.unavailable` |
+| `refused` | Storage refused the request with any other status, an expired link among them. Read the method again for fresh links. | `client.response_unreadable` naming the status, `runtime.unsupported` for a `501` |
+| `mismatch` | A download's bytes are not the file the listing names: another size, or another SHA-256. | `client.response_unreadable` |
 
-Its `errorDomain` is always `runtime`. An upload to a target that asks for a create-only write (`If-None-Match`) and answers `412` is not a failure: the bytes are already stored.
+An upload to a target that asks for a create-only write (`If-None-Match`) and answers `412` is not a failure: the bytes are already stored.
 
 ## What changed from the source fields
 

package/docs/organization-branding.md

@@ -56,21 +56,19 @@ The write sends no `Idempotency-Key`, as `renameOrganization` sends none. A late
 
 ## When a write is refused
 
-A refused write changes nothing, whichever part of it was refused, and throws an `ApiResponseError` whose `code` is the platform's; only a `503` leaves it unknown whether the write landed:
+A refused write changes nothing, whichever part of it was refused, and throws an `ApiResponseError` whose `problem` is the platform's problem document; only a `503` leaves it unknown whether the write landed:
 
 | Status | `code` | When |
 |---|---|---|
-| `403` | `forbidden` | `orgId` is not the caller's active organization. |
-| `403` | `role_not_permitted` | The caller is not the organization's admin. |
-| `404` | `not_found` | The organization does not exist. |
-| `409` | `conflict` | The organization is a personal workspace, which has no branding. |
-| `422` | `validation_failed` | A colour is not `#rrggbb`, the body holds a key the route does not take, or a logo was refused. |
-| `400` | `invalid_storage_uri` | A logo's URI is not a storage URI. |
-| `403` | `forbidden` | A logo's URI is a file of another organization. |
-| `500` | `storage_backend_failed` | The platform's storage failed while reading or copying a logo. Its verdict is `runtime` and retryable, and nothing was written. |
-| `503` | `service_unavailable` | The platform's database failed or could not be reached, so the write may have landed or not. Its verdict is `runtime` and retryable: the same `input` sent again is safe, and `getBranding` reads what the branding holds. |
-
-**A refusal about a logo or a colour names it in `errors`**, the platform's field-level list, so the settings screen shows each sentence under the control it concerns rather than in a toast. Each entry's `field` is the slot, `square_logo` or `wide_logo`, or the colour's dotted key, such as `colors.action` or `dark_colors.header`; its `detail` is the sentence to show. A logo the platform read and refused carries a `LogoRefusalCode`, one entry per broken rule, both slots answered in one refusal:
+| `403` | `auth.forbidden` | The caller is not the organization's admin. |
+| `403` | `pipelex.org.mismatch` | `orgId` is not the caller's active organization, or a logo's URI is a file of another organization. |
+| `404` | `pipelex.org.not_found` | The organization does not exist. |
+| `409` | `pipelex.org.not_manageable` | The organization is a personal workspace, which has no branding. |
+| `422` | `request.invalid` | A colour is not `#rrggbb`, the body holds a key the route does not take, or a logo was refused. |
+| `422` | `pipelex.storage.uri_invalid` | A logo's URI is not a storage URI. |
+| `503` | `runtime.unavailable` | The platform's storage failed while reading or copying a logo, or its database failed or could not be reached, so the write may have landed or not. Its `retry` is `yes`: the same `input` sent again is safe, and `getBranding` reads what the branding holds. |
+
+**A refusal about a logo or a colour names it in its problem's `errors`**, one problem item per refused logo or colour, so the settings screen shows each sentence under the control it concerns rather than in a toast. Each item's `location.field` is the slot, `square_logo` or `wide_logo`, or the colour's dotted key, such as `colors.action` or `dark_colors.header`; its `detail` is the sentence to show. A logo the platform read and refused carries one item per broken rule, both slots answered in one refusal, each item's `code` one `LogoRefusalCode` names:
 
 | `code` | Example `detail` |
 |---|---|
@@ -85,16 +83,16 @@ A refused write changes nothing, whichever part of it was refused, and throws an
 | `logo_not_wide` | The wide logo is 600 × 500 px, 1.2 times as wide as it is tall; a wide logo must be at least 1.5 times as wide as it is tall. |
 | `logo_too_short` | The wide logo is 240 × 48 px; a wide logo must be at least 64 px tall. |
 
-The two refusals of a logo URI that come before any file is read, `invalid_storage_uri` and another organization's `forbidden`, name the slot the same way, with the platform's code in the entry. A colour's entry carries pydantic's code, such as `string_pattern_mismatch`. Reading one slot's sentences is the same filter in every case:
+The two refusals of a logo URI that come before any file is read, `pipelex.storage.uri_invalid` and another organization's `pipelex.org.mismatch`, name the slot the same way, with the refusal's code on the item. Reading one slot's sentences is the same filter in every case:
 
 ```ts
 try {
   await client.updateOrganizationBranding(orgId, { square_logo: uri });
 } catch (err) {
   if (!(err instanceof ApiResponseError)) throw err;
-  const underSquare = (err.errors ?? [])
-    .filter((entry) => entry.field === "square_logo")
-    .map((entry) => entry.detail);
+  const underSquare = (err.problem.errors ?? [])
+    .filter((item) => item.location?.field === "square_logo")
+    .map((item) => item.detail);
   // Show `underSquare` under the square logo's slot; an error naming no field goes in a toast.
 }
 ```

package/docs/run-results.md

@@ -43,7 +43,7 @@ const results = await client.waitForResult(runId, { artifacts: ["working_memory"
 
 **Absent versus null.** With a selection, an artifact the caller did not name is absent from the result, reading `undefined`, while one it named that the run never wrote is `null`. So `undefined` means "not asked for" and `null` means "asked for, not there". That is also why `main_stuff` is declared optional: it is never null on a completed run, but it is absent from a read that left it out, and `MissingMainStuffError` is thrown only by a read that asked for it — one with no selection, or one naming `main_stuff`.
 
-An empty selection or a name outside the list is a `RequestArgumentError` thrown before any request, `input` and not retryable, the same refusal the platform would answer with a `400`. `waitForResult` and `startAndWaitForResult` take the same `artifacts` in their poll options and send it on every poll; `startAndWaitForResult` refuses a bad selection before it starts the run. Against a bare runner the selection has nothing to narrow: the blocking fallback returns every artifact the runner sent. `downloadArtifacts` given a `run_id` asks for its scope's artifact alone.
+An empty selection or a name outside the list is a `RequestArgumentError` thrown before any request, `client.argument_invalid`, the same refusal the platform would answer with a `400`. `waitForResult` and `startAndWaitForResult` take the same `artifacts` in their poll options and send it on every poll; `startAndWaitForResult` refuses a bad selection before it starts the run. Against a bare runner the selection has nothing to narrow: the blocking fallback returns every artifact the runner sent. `downloadArtifacts` given a `run_id` asks for its scope's artifact alone.
 
 ## `pipeline_run_id` — the durable handle
 
@@ -79,7 +79,7 @@ It is never called on the blocking path, a bare runner's `POST /v1/execute` or t
 
 **Knowing whether a run may exist.** `onStarting`, the other callback `StartAndWaitForResultOptions` takes, is called right before each request that may create a run is sent: `POST /v1/start`, and the blocking `POST /v1/execute` of a bare runner or of the fallback to it, so it is called twice when a runner that looked hosted refuses the start. Until it is called no run exists, and once the `signal` has aborted it is not called and no such request is sent, so a caller that stops waiting before then can say that no run was started; from then until `onStarted`, a run may exist that the API has not yet named. It runs synchronously and its return value is ignored; an exception it throws propagates before the request is sent. The `pipelex-sdk` command words its interrupt message by it ([`cli.md`](cli.md)).
 
-**A failed start says whether a run may exist.** An error from the start, or from the blocking execute, carries `runMayHaveStarted`: `true` when the request may have created a run although the call failed, so a person looks the run up in the run history before starting it again, and then its `retryable` is `false` ([`errors.md`](errors.md#a-failed-run-start--runmayhavestarted)). Once `onStarted` has been called the run exists and the caller holds its id, so an error while the composite waits started nothing: its `runMayHaveStarted` is `false`, and its `retryable` is about waiting again on that id with `waitForResult`, never about calling `startAndWaitForResult` again, which would start a second run.
+**A failed start says whether a run may exist.** An error from the start, or from the blocking execute, whose request may have created a run although the call failed is `client.outcome_unknown`, its `retry` being `outcome_unknown`, so a person looks the run up in the run history before starting it again ([`errors.md`](errors.md#a-run-that-may-have-started--outcome_unknown)). Once `onStarted` has been called the run exists and the caller holds its id, so an error while the composite waits started nothing: its `retry` is about waiting again on that id with `waitForResult`, never about calling `startAndWaitForResult` again, which would start a second run.
 
 ## A degraded status — `degraded` and `degradation`
 
@@ -90,7 +90,7 @@ It is never called on the blocking path, a bare runner's `POST /v1/execute` or t
 | `reason` | What holds | `status` | What to tell the person |
 |---|---|---|---|
 | `status_unavailable` | The platform could not reach the workflow engine. | The last one recorded. | Nothing about the run, which may be fine: the status is not fresh, and the next read comes after `retry_after_seconds`. |
-| `workflow_task_failing` | The workflow task that drives the run has failed `failed_attempts` times in a row since `failing_since`, so the run is not making progress. | Live. | The run is stuck. The workflow engine keeps retrying, and if the task is still failing at `ends_at` the platform ends the run `FAILED`, with a `WorkflowTaskKeptFailingError` report ([errors.md](./errors.md#a-failed-run--runerrorreport)). |
+| `workflow_task_failing` | The workflow task that drives the run has failed `failed_attempts` times in a row since `failing_since`, so the run is not making progress. | Live. | The run is stuck. The workflow engine keeps retrying, and if the task is still failing at `ends_at` the platform ends the run `FAILED`, with a problem of its own ([errors.md](./errors.md#a-failed-run--runfailederror)). |
 
 ```ts
 const run = await client.getRunStatus(runId);
@@ -138,7 +138,7 @@ const results = await client.waitForResult(runId, {
 - **`startAndWaitForResult` honours it on the durable path only.** Its blocking fallback, a bare runner's `POST /v1/execute`, has no run to read, so `onProgress` is never called there.
 - **The callback runs synchronously** and its return value is ignored. An exception it throws propagates out of the wait, as one thrown by `onPoll` does, and the run keeps going on the server.
 
-**Reading it yourself: `getRunProgress(runId)`.** It returns the snapshot as the platform answered it, the `RunProgress`. A pending run, and a run that has written no progress event yet, answer with no invocation. When the workflow engine cannot be reached the read still answers `200`: its `degradation` reads `status_unavailable`, its `status` is the last one recorded and no invocation carries a health annotation. A run that does not exist, or belongs to another organization, is the platform's `404`, an `ApiResponseError`, and a server without the route, a bare runner or a hosted API older than it, is a `RunLifecycleUnavailableError`. The members the freshness rule and a timeline lean on are checked: an answer whose `version` is not a non-negative integer, whose `pipeline_run_id`, `mode`, `status`, `assembled_at` or `summary` is not a string, whose `invocations` is not a list, or one of whose invocations misses its path, pipe identity, status or times, is an `ApiResponseError` for an answer the SDK cannot read. The snapshot's `degradation` and each invocation's are checked field by field as the status read's are, and one whose `reason` is not a string is dropped, so neither fails the read. Members the SDK does not name are relayed as sent.
+**Reading it yourself: `getRunProgress(runId)`.** It returns the snapshot as the platform answered it, the `RunProgress`. A pending run, and a run that has written no progress event yet, answer with no invocation. When the workflow engine cannot be reached the read still answers `200`: its `degradation` reads `status_unavailable`, its `status` is the last one recorded and no invocation carries a health annotation. A run that does not exist, or belongs to another organization, is the platform's `404`, an `ApiResponseError`, and a server without the route, a bare runner or a hosted API older than it, is a `RunLifecycleUnavailableError`. The members the freshness rule and a timeline lean on are checked: an answer whose `version` is not a non-negative integer, whose `pipeline_run_id`, `mode`, `status`, `assembled_at` or `summary` is not a string, whose `invocations` is not a list, or one of whose invocations misses its path, pipe identity, status or times, is an `ApiResponseError` for an answer the SDK cannot read. The snapshot's `degradation` and each invocation's are checked field by field as the status read's are, and one whose `reason` is not a string is dropped; an invocation's `last_failure` is kept only when its `problem` is a problem document (`isProblem` in `mthds/protocol`), and its `at` only when it is a string. So no health annotation fails the read. Members the SDK does not name are relayed as sent.
 
 ### The snapshot
 
@@ -169,7 +169,7 @@ An **invocation** is one run of one pipe inside the run, named by its `path`: th
 | `batch` | `ProgressBatch`, optional | On a `PipeBatch` that has fanned out, `{ total, done, running, failed }`: `done` counts the items succeeded or skipped, and an item scheduled or canceled is in none of the three. |
 | `condition` | `ProgressCondition`, optional | On a `PipeCondition` that has resolved, `{ selected_outcome }`, the key its value matched, or `null` for its default outcome. |
 | `attempts` | `number`, optional | Health: how many times its work has been tried, present only when more than once. |
-| `last_failure` | `ProgressFailure`, optional | Health: `{ message, at? }`, the latest failure of its work. `message` keeps the disclosure of a run's error report: the failure's own text only when it was written for the caller, `An internal error occurred.` otherwise. |
+| `last_failure` | `ProgressFailure`, optional | Health: `{ problem, at? }`, the latest failure of its work. `problem` is the standard's `Problem`, in the caller's view as the run reads serve a failed run's problem: the problem that ended the invocation when it is `failed`, and otherwise the problem of the latest failure of an attempt its engine is trying again, `runtime.unexpected` for a failure only the engine observed. Branch on its `code`, never on the wording of its `detail`. `at` is when it failed, absent when not recorded. |
 | `degradation` | `RunDegradation`, optional | Health: the run is stuck here, in the run status's own words — the status read's `degradation`, `workflow_task_failing`, placed on the run's root or on the batch item whose execution keeps failing to advance. |
 
 The health annotations are what the workflow engine reports, so an absent one means that nothing was observed, never that the engine looked and found all well. They reuse the run status's `RunDegradation` rather than a shape of their own, so the code that shows a degraded status shows a stuck invocation too.
@@ -221,14 +221,14 @@ switch (state.state) {
     console.log(`not finished — poll again in ${state.retry_after_seconds ?? 2}s`);
     break;
   case "failed":
-    // `message` already names the reason; `error` is the run's stored report, or null.
+    // `problem` is `run.failed`; `error` is the run's own problem, or null.
     console.error(`run ended as ${state.status}: ${state.message}`);
-    if (state.error?.user_action) console.error(`next step: ${state.error.user_action.detail}`);
+    if (state.error) console.error(`${state.error.code}: ${state.error.next_step.detail}`);
     break;
 }
 ```
 
-`getRunResult` is the single-shot lookup and returns that discriminated state. `waitForResult(runId)` drives the same lookup in a loop, honouring the server's `Retry-After`, and returns the `RunResults` directly — throwing `RunFailedError` on a terminal non-completed status and `RunTimeoutError` when the budget runs out. The `failed` arm and `RunFailedError` carry the same facts: the run's `status`, the `message` naming the reason, and `error`, the run's stored error report, typed as `RunErrorReport` and `null` when the run ended without one. [`errors.md`](./errors.md#a-failed-run--runerrorreport) describes the report field by field.
+`getRunResult` is the single-shot lookup and returns that discriminated state. `waitForResult(runId)` drives the same lookup in a loop, honouring the server's `Retry-After`, and returns the `RunResults` directly — throwing `RunFailedError` on a terminal non-completed status and `RunTimeoutError` when the budget runs out. The `failed` arm and `RunFailedError` carry the same facts: the run's `status`, the `message` naming the reason, `problem`, the platform's `run.failed` document, and the run's own problem, which `run.failed` nests as `run_error`: the arm's `error`, `null` when the run ended without one, and the error's `runError`. [`errors.md`](./errors.md#a-failed-run--runfailederror) describes both.
 
 ## `working_memory` — every named stuff of the run
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipelex/sdk",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "TypeScript SDK for the Pipelex hosted API — execute methods, manage runs, and call the product surface.",
   "license": "MIT",
   "repository": {

package/dist/error-models.d.ts

@@ -1,302 +0,0 @@
-/**
- * Error-report wire models — a failed run's stored report, and the typed members of a
- * problem document.
- *
- * **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 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.
- *
- * Every field is optional and every interface keeps an index signature, for the reason
- * `TokensUsageRecord` gives: the runner adds fields without asking this SDK, and a field this
- * version does not name still reaches the caller. The enum-ish fields (`error_domain`,
- * `error_category`, `user_action.kind`) are open sets on the wire and stay `string`, never
- * frozen unions, so a value the runner adds is not an SDK break; their known values are listed
- * where they are declared.
- *
- * **A stored report is checked, not cast.** Every read that hands one back runs it through
- * `readRunErrorReport`, which keeps each named field only when it has the type declared here and
- * reads it as absent otherwise, as the Python twin does: a report written by an older runner, or
- * stored by hand, cannot hand a consumer a number where a string is typed. The client checks the
- * nested members of a problem document with the same readers, so `ApiResponseError`'s
- * `providerMetadata`, `migration`, `validationErrors` and `errors` hold to their types as a stored
- * report's do.
- *
- * **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";
-/**
- * The next step an error advises — the runner's `UserAction`, carried as `user_action` on a
- * stored report and on a runner's problem document. `kind` names the category of advice, so a
- * consumer can render consistent guidance; `detail` is the advice itself, in words (a billing
- * URL, a retry hint, the model to change).
- *
- * Known `kind` values: `wait_and_retry`, `check_billing`, `check_credentials`, `change_input`,
- * `change_model`, `contact_support`, `unknown`. The set is the runner's, so it is typed open.
- * It is the hosted plane's own member, which predates the standard's problem document: there the
- * next step is the problem's `next_step`, whose `kind` is a closed list of its own.
- */
-export interface UserAction {
-    kind: string;
-    detail: string;
-}
-/**
- * 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. 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"`,
- * `"1.5"`), because the store hands its numbers back as decimals that the platform serializes
- * as strings. A problem document rendered by a runner carries them as numbers. Both are typed,
- * so read them with `Number(...)` when you need the value.
- */
-export interface ProviderErrorMetadata {
-    provider?: string | null;
-    sdk_exception_type?: string | null;
-    message?: string | null;
-    /** The provider's HTTP status, when it answered one. */
-    status_code?: number | string | null;
-    /** The provider's own request id — what its support desk asks for. */
-    request_id?: string | null;
-    retry_after_seconds?: number | string | null;
-    provider_error_code?: string | null;
-    [extension: string]: unknown;
-}
-/**
- * A pending configuration migration that explains the failure — the runner's
- * `MigrationErrorBlock`. Present only on a configuration failure whose raiser scanned the
- * host's configuration directories; a consumer branches on its presence. `plans` is carried
- * opaquely: it is the shape `pipelex-agent migrate --dry-run --format json` emits, which no
- * published package declares.
- */
-export interface MigrationErrorBlock {
-    /** The command that applies whatever can be applied without a decision. */
-    remedy?: string | null;
-    /** Whether running `remedy` would rewrite any file. */
-    would_write?: boolean | null;
-    /** Whether something here is a person's to resolve rather than the tool's. */
-    needs_attention?: boolean | null;
-    plans?: Record<string, unknown>[] | null;
-    [extension: string]: unknown;
-}
-/**
- * Why a run failed — the runner's `ErrorReport`, typed with every field it carries.
- *
- * The one type for a failed run's report wherever the SDK hands it back: `RunPublic.error`
- * (and so `RunRead.error` on the status read), `PipelineRun.error` on the run records, `error`
- * on the failed arm of `RunResultState` (the results read's `409`), and `RunFailedError.error`
- * when `waitForResult`, `startAndWaitForResult` or an artifact download throws for a run that
- * ended without a result.
- *
- * **Branch on `error_domain`, `type_uri` and `retryable`**, never on the wording of `message`.
- * `error_type` is the runner's open-ended exception class name: finer than `error_domain`,
- * useful in a support line, but not a closed set to match against. Which fault's identity a run
- * failure's report carries, and how its `message` names the failing pipe, is the runner's to
- * decide; read them as given.
- *
- * 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 {
-    /**
-     * The runner's exception class name (`LLMCompletionError`, `PipeRunError`, …) — an open
-     * set, for display and support, not for branching.
-     */
-    error_type?: string | null;
-    /**
-     * 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`). */
-    title?: string | null;
-    /** The stable URI naming the error class — a branch field, and where its documentation lives. */
-    type_uri?: string | null;
-    /**
-     * Who can fix it, the coarse branch field. Known values: `input` (the caller — a malformed
-     * bundle, a bad input), `config` (a configuration change — a model not served, a missing
-     * secret), `runtime` (nobody beforehand — a provider outage during execution).
-     */
-    error_domain?: string | null;
-    /**
-     * A finer classification of an inference failure, when the runner has one. Known values:
-     * `transient`, `configuration`, `content`, `capacity`, `ambiguous`, `unknown`.
-     */
-    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 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. 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. 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. 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,
-     * 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. 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;
-}
-/**
- * One field-level failure of a request — an item of the platform problem document's
- * `errors[]`. `field` is the dotted path to the offending attribute, `code` a stable sub-code
- * (`invalid_format`, `out_of_range`, …), `detail` optional human text.
- */
-export interface FieldError {
-    field?: string | null;
-    code?: string | null;
-    detail?: string | null;
-    [extension: string]: unknown;
-}
-/**
- * The members of an RFC 9457 problem document that `ApiResponseError` exposes beyond its
- * message, as the client parsed them: the standard's own `type`, `title` and `instance`, the
- * request id, and the extension members the runner and the platform add to classify the
- * failure. Every member is optional — a server sends what it knows, and a body that is not a
- * problem document carries none of them.
- *
- * These are the hosted plane's members, which predate the standard's problem document: the
- * standard's reading of the same answer is `ApiResponseError.problem`, and the two never share a
- * slot, so the platform's field-level `errors` here and the problem items of `problem.errors`
- * stay apart.
- */
-export interface ProblemDetails {
-    /** RFC 9457 `type` — the stable URI of the error class. */
-    type?: string;
-    /** RFC 9457 `title` — the short human label of the error class. */
-    title?: string;
-    /** RFC 9457 `instance` — the occurrence (a request path or a request URN). */
-    instance?: string;
-    /** The request's correlation id: the body's `request_id`, else the `X-Request-ID` response header. */
-    requestId?: string;
-    /** The body's `error_domain` — `input`, `config` or `runtime`. */
-    errorDomain?: string;
-    /** The body's `error_category` — the finer classification of an inference failure. */
-    errorCategory?: string;
-    /** The body's `retryable` — whether retrying the same request can plausibly succeed. */
-    retryable?: boolean;
-    /** The body's `user_action` — what the caller should do next. */
-    userAction?: UserAction;
-    /** The body's `model` — the model an inference failure used. */
-    model?: string;
-    /** The body's `provider` — the provider an inference failure reached. */
-    provider?: string;
-    /** The body's `provider_metadata` — what the provider's SDK said. */
-    providerMetadata?: ProviderErrorMetadata;
-    /** The body's `migration` — a pending configuration migration that explains the failure. */
-    migration?: MigrationErrorBlock;
-    /** The platform's field-level `errors[]`. */
-    errors?: FieldError[];
-}
-/** 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.
- */
-export declare function readProviderMetadata(value: Record<string, unknown>): ProviderErrorMetadata;
-/**
- * `migration`, its `remedy` kept as a string, `would_write` and `needs_attention` as booleans, and
- * `plans` as an array keeping only its objects; its other members are relayed as sent.
- */
-export declare function readMigration(value: Record<string, unknown>): MigrationErrorBlock;
-/**
- * A validation item is kept when it is an object with a string `category` and `message`, its other
- * members relayed as sent. It checks a problem document's items and a stored report's only:
- * `validate()` and the crate routes hand their reports' items back unchecked.
- */
-export declare function isValidationItem(value: unknown): value is ValidationErrorItem;
-/**
- * An item of a platform problem document's `errors[]`, its `field`, `code` and `detail` kept when
- * they are strings and its other members relayed as sent.
- */
-export declare function readFieldError(value: Record<string, unknown>): FieldError;
-/**
- * A failed run's stored report, checked field by field — the one way every read in this SDK
- * hands a report back.
- *
- * - A value that is not a plain object reads as `null`, no report.
- * - Each string field (`error_type`, `message`, `title`, `type_uri`, `error_domain`,
- *   `error_category`, `model`, `provider`) is kept when it is a string, an empty one included, and
- *   is absent otherwise. Deciding that a blank field says nothing is presentation, left to each
- *   consumer.
- * - `retryable` and `caller_facing_message` are kept when they are booleans.
- * - `user_action` is kept whole or not at all: an object whose `kind` and `detail` are both
- *   strings, which is what `UserAction` promises. (The Python twin keeps a partial action, its
- *   stored-report action being a lenient type of its own; this is the one place the two differ.)
- * - `provider_metadata` is kept when it is an object, with each named field checked: the strings
- *   as strings, `status_code` and `retry_after_seconds` as a number or a string, since the hosted
- *   store serves its numbers as strings.
- * - `migration` is kept when it is an object: `remedy` as a string, `would_write` and
- *   `needs_attention` as booleans, and `plans` as an array keeping only its objects.
- * - `validation_errors` is kept when it is an array, keeping each item that is an object with a
- *   string `category` and a string `message`.
- * - `null` is kept wherever the type allows it, which is every named field; and members this SDK
- *   does not name, in the report and in each nested object, are relayed as sent.
- *
- * Internal: every report a consumer meets comes through one of the reads that apply it.
- */
-export declare function readRunErrorReport(value: unknown): RunErrorReport | null;