Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

feature/Pipelex-error-registry · L-261015-fa959c (#1442)

Louis Choquelbbb7e2e0edce
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md
index a4bf6075a..9932f37e0 100644
--- a/.claude/skills/release/SKILL.md
+++ b/.claude/skills/release/SKILL.md
@@ -53,6 +53,7 @@ The same goes for the server's two artifacts. A failed `publish-api-to-pypi` is
- **Also stamped:**
- **`.badges/tests.json`** — set `"message"` to what `make test-count` prints, leaving every other field alone, then run `make check-test-badge` to confirm the two agree. A mismatch is a CI failure on the pull request.
- **`docs/api-server/openapi/pipelex-api.openapi.yaml`** — `make -C api openapi-export`. The API server in `api/` takes the library's version, and its committed OpenAPI artifact carries it as `info.version`, so the bump moves the artifact and `make agent-check`, whose `api-agent-check` runs `openapi-check`, fails until it is re-exported. The only change it should show is that one line; anything more is a wire change that belongs in the changelog.
+ - **`pipelex/errors/registry/pipelex-error-registry.json` and `docs/errors/index.md`** — `make generate-error-registry`. The error registry's snapshot is published under the library's version, a pre-release's in its SemVer form (`0.88.0rc1` as `0.88.0-rc.1`), and the Error Codes index names that version, so the bump leaves both stale: the registry's freshness tests fail in `make agent-test`, and the release workflow refuses to publish a snapshot whose version is not the release's. The only change they should show is the version; anything more means the registry's source changed without its outputs being regenerated. `docs/contribute/error-registry.md` describes the registry's version.
- **`.test_durations`** — `make store-test-durations`, the per-test timing map `pytest-split` uses to balance the CI test shards. The refresh is incremental: it collects the suite and measures only the tests missing from the map, so it takes seconds on a quiet release and writes no diff at all when nothing was missing. Read the coverage line it prints before judging how long it should take — past roughly 40% of the suite missing it falls back to re-measuring everything, which takes minutes; treat a long run as a hang only when it reported few tests missing. Include the file in the commit only when it changed. `make store-test-durations-force` is **not** part of the release flow; it is for when recorded values are no longer comparable to each other because the machine or the suite changed shape. The rationale is `docs/contribute/test-duration-map.md`.
- **`pipelex/migration/ledgers/*.toml` and `pipelex/migration/goldens/`** — only when the migration gate below finds an unaccounted schema change, and then written by the `add-migration` skill, never by hand.
@@ -76,7 +77,7 @@ The same goes for the server's two artifacts. A failed `publish-api-to-pypi` is
## The release commit
-`pyproject.toml`, `CHANGELOG.md`, `uv.lock`, `.badges/tests.json`, `docs/api-server/openapi/pipelex-api.openapi.yaml`, `.test_durations` when `make store-test-durations` changed it, whatever `make agent-check` rewrote, and the `pipelex/migration/ledgers/*.toml` and `pipelex/migration/goldens/` files the `add-migration` skill wrote when it ran. By name.
+`pyproject.toml`, `CHANGELOG.md`, `uv.lock`, `.badges/tests.json`, `docs/api-server/openapi/pipelex-api.openapi.yaml`, `pipelex/errors/registry/pipelex-error-registry.json`, `docs/errors/index.md`, `.test_durations` when `make store-test-durations` changed it, whatever `make agent-check` rewrote, and the `pipelex/migration/ledgers/*.toml` and `pipelex/migration/goldens/` files the `add-migration` skill wrote when it ran. By name.
## CI on the release pull request
@@ -101,6 +102,6 @@ Everything that runs on every pull request gates it too, including the server's
- **The first release that ships the server explains the image's version jump.** The `pipelex/pipelex-api` image was released on its own until `0.33.2`, from the `Pipelex/pipelex-api` repository; its next tag is this release's version. `[Unreleased]` already says so in its `The Pipelex API server ships with pipelex` entry: keep that sentence when folding the entry, and say it in the pull request body. Releases after that one need no such note.
- **A server change is an entry in this changelog.** `api/CHANGELOG.md` stops at `0.33.2` and is never extended.
- **The migration gate feeds back into the bump.** A breaking entry found by the cross-check above turns a patch into a minor, so the bump is not final until that gate has run.
-- **The pre-release track is a different flow, not this play.** `pre-release/vX.Y.Z(a|b|rc)N` is a *base* branch that work merges into: `prerelease-version-check.yml` validates the PEP 440 form against the branch name, `publish-pypi.yml` also fires on a merge into it, marks the GitHub Release a pre-release and publishes the server's wheel and image as well, the image under its own tag with `latest` left on the last stable release, and `deploy-docs.yml` fires on the push to it as well — though its pre-release branch calls `make docs-deploy-specific-version`, a name with no recipe behind it (the recipe is `docs-deploy-specific-version-pre-release`), so that step succeeds and publishes nothing. A `release/vX.Y.Z` branch therefore never carries a pre-release version: `version-check.yml` fails on the mismatch with the branch name, and `guard-branches.yml` refuses a `release/vX.Y.Z(a|b|rc)N` head into `main` outright.
+- **The pre-release track is a different flow, not this play.** `pre-release/vX.Y.Z(a|b|rc)N` is a *base* branch that work merges into: `prerelease-version-check.yml` validates the PEP 440 form against the branch name, `publish-pypi.yml` also fires on a merge into it, marks the GitHub Release a pre-release and publishes the server's wheel and image as well, the image under its own tag with `latest` left on the last stable release, and `deploy-docs.yml` fires on the push to it as well, publishing the docs under the `pre-release` alias with `make docs-deploy-specific-version-pre-release`. A `release/vX.Y.Z` branch therefore never carries a pre-release version: `version-check.yml` fails on the mismatch with the branch name, and `guard-branches.yml` refuses a `release/vX.Y.Z(a|b|rc)N` head into `main` outright.
- **The changelog heading carries the `v`** — `## [vX.Y.Z] - YYYY-MM-DD`, which is exactly what `changelog-check.yml` greps for and what `publish-pypi.yml` slices the GitHub Release notes out of. No `[Unreleased]` heading is left behind; the next change re-creates one.
- **`.worktreeinclude` names the gitignored files a fresh worktree needs** — `.env`, the `.pipelex/` overrides and `.pipelex-dev/test_profiles_override.toml` — and `wt add` provisions them. A gate that fails in `_pipelex--release` on a missing local config means that file is short: add it there rather than hand-copying the file every release.
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index 7e76d78fd..ff628597d 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -50,5 +50,5 @@ jobs:
make docs-deploy-stable
elif [[ "${{ github.ref }}" == refs/heads/pre-release/* ]]; then
echo "Deploying pre-release docs..."
- make docs-deploy-specific-version
+ make docs-deploy-specific-version-pre-release
fi
diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
index 6f262f430..ed7922e66 100644
--- a/.github/workflows/publish-pypi.yml
+++ b/.github/workflows/publish-pypi.yml
@@ -106,6 +106,25 @@ jobs:
echo "head_sha=$HEAD_SHA"
} >> "$GITHUB_OUTPUT"
echo "Shipping $NAME $VERSION from $HEAD_SHA"
+ # The Pipelex error registry is published with every release under the release's
+ # version (docs/contribute/error-registry.md). Its snapshot carries the version it
+ # was generated with, so a release whose snapshot was not regenerated after the
+ # version bump stops here, before anything is published under the wrong number.
+ # The registry format writes a version as SemVer, so a pre-release's PEP 440 number
+ # is written in its SemVer form, 0.88.0rc1 as 0.88.0-rc.1, by the same stdlib-only
+ # module the generator composes the snapshot with.
+ - name: Verify the error registry carries the release's version
+ env:
+ VERSION: ${{ steps.project.outputs.version }}
+ run: |
+ set -euo pipefail
+ ERROR_REGISTRY=pipelex/errors/registry/pipelex-error-registry.json
+ EXPECTED_VERSION=$(python3 -I pipelex/cli/dev_cli/commands/error_registry/registry_version.py "$VERSION")
+ REGISTRY_VERSION=$(jq -r '.version' "$ERROR_REGISTRY")
+ if [ "$REGISTRY_VERSION" != "$EXPECTED_VERSION" ]; then
+ echo "::error::$ERROR_REGISTRY carries the version $REGISTRY_VERSION, not $EXPECTED_VERSION, the registry's form of $VERSION. Run make generate-error-registry after the version bump."
+ exit 1
+ fi
# A recovery re-run — the one the signing fallback in `github-release`
# prescribes — must attach and sign the exact bytes this version published,
# because PyPI's copies of them are immutable. Rebuilding cannot promise
@@ -713,6 +732,16 @@ jobs:
"v$VERSION" dist/*.whl dist/*.tar.gz
--repo "$GITHUB_REPOSITORY"
--clobber
+ # The Pipelex error registry's snapshot, from the release commit, which the
+ # build job checked carries this version.
+ - name: Upload the error registry to GitHub Release
+ env:
+ GITHUB_TOKEN: ${{ github.token }}
+ run: >-
+ gh release upload
+ "v$VERSION" pipelex/errors/registry/pipelex-error-registry.json
+ --repo "$GITHUB_REPOSITORY"
+ --clobber
- name: Sign the dists with Sigstore
id: sign
# A Sigstore trust-root refresh is outside our control and must not fail a
diff --git a/.test_durations b/.test_durations
index b861cbaeb..56af8b33e 100644
--- a/.test_durations
+++ b/.test_durations
@@ -9248,22 +9248,6 @@
"tests/unit/pipelex/errors/test_error_identity_snapshot.py::TestErrorIdentitySnapshot::test_committed_snapshot_matches_the_live_error_classes": 0.1291,
"tests/unit/pipelex/errors/test_error_identity_snapshot.py::TestErrorIdentitySnapshot::test_enumerated_identity_set_is_not_empty": 1.2155,
"tests/unit/pipelex/errors/test_error_identity_snapshot.py::TestErrorIdentitySnapshot::test_no_identity_field_contains_the_column_separator": 0.0141,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_a_class_declaring_retryable_shows_it_and_one_declaring_nothing_does_not": 0.0653,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_authored_marker_detection_ignores_marker_inside_other_content": 0.0005,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_authored_marker_preserves_hand_edited_page": 0.0557,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_emits_one_page_per_loaded_subclass_plus_index_and_macros": 1.2081,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_force_load_aggregates_non_import_error_failures": 0.2465,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_force_load_walk_continues_past_first_failure": 0.0288,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_index_links_each_emitted_macro_page": 0.0725,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_kebab_slug_collision_raises": 0.0019,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_macro_pages_link_every_class": 0.0996,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_macro_slugs_are_wired_into_mkdocs_nav": 0.0011,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_orphan_authored_page_is_preserved_not_deleted": 0.0021,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_orphan_generated_page_is_deleted": 0.0023,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_orphan_unmarked_file_is_left_alone": 0.0014,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_report_total_sums_four_populations": 0.0007,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_reserved_slug_collision_raises": 0.002,
- "tests/unit/pipelex/errors/test_error_pages_generator.py::TestErrorPagesGenerator::test_run_is_idempotent": 0.1344,
"tests/unit/pipelex/errors/test_validation_error_types.py::TestValidationErrorTypeRegistry::test_an_unregistered_error_type_is_refused": 1.3125,
"tests/unit/pipelex/errors/test_validation_error_types.py::TestValidationErrorTypeRegistry::test_every_registered_type_is_accepted_by_its_wire_value[DryRunError]": 0.0145,
"tests/unit/pipelex/errors/test_validation_error_types.py::TestValidationErrorTypeRegistry::test_every_registered_type_is_accepted_by_its_wire_value[batch_item_name_collision]": 0.0008,
@@ -16232,7 +16216,6 @@
"tests/unit/pipelex/test_pipelex_error_title_and_type_uri.py::TestPipelexErrorTitleAndTypeUri::test_to_error_report_populates_title_and_type_uri": 0.8928,
"tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py::TestPipelexErrorTypeUriUniqueness::test_all_derived_type_uris_are_unique": 0.119,
"tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py::TestPipelexErrorTypeUriUniqueness::test_all_pipelex_error_subclasses_have_unique_type_uris": 1.1115,
- "tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py::TestPipelexErrorTypeUriUniqueness::test_every_declared_type_uri_under_the_error_docs_names_an_existing_page": 0.0113,
"tests/unit/pipelex/test_registry_models_split.py::TestRegistryModelsSplit::test_every_pipe_kind_declares_the_factory_that_gets_looked_up_for_it": 0.9532,
"tests/unit/pipelex/test_registry_models_split.py::TestRegistryModelsSplit::test_every_registered_model_is_live_in_the_booted_class_registry": 0.1094,
"tests/unit/pipelex/test_registry_models_split.py::TestRegistryModelsSplit::test_no_two_registered_models_share_a_class_name": 0.0011,
diff --git a/AGENTS.md b/AGENTS.md
index ef4abf1cf..6a24dd8eb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -83,10 +83,16 @@
.venv/bin/pipelex-dev generate-mthds-schema
```
- - **`generate-error-pages`**: Regenerate the per-class error reference pages under `docs/errors/` — one Markdown page per `PipelexError` subclass, which is what each error's `type_uri` dereferences to. Run after adding or renaming an error class. Pages a maintainer claims with a `<!-- pipelex:authored -->` marker are preserved across runs. Also available as `make generate-error-pages` (alias `make gep`).
+ - **`generate-error-registry`**: Write every file derived from the Pipelex error registry, `pipelex/errors/registry/pipelex-error-registry.yaml`: its JSON snapshot, its typed codes in `pipelex/errors/registry/pipelex_codes.py`, and one page per code under `docs/errors/`. Run after adding or changing a code in the registry, and after a version bump, since the snapshot carries the version. A source the format's schema, the typed model or the registry's rules refuse writes nothing. Also available as `make generate-error-registry` (alias `make ger`). See `docs/contribute/error-registry.md`.
```bash
- .venv/bin/pipelex-dev generate-error-pages
+ .venv/bin/pipelex-dev generate-error-registry
+ ```
+
+ - **`check-error-registry`**: Check the error registry against the MTHDS standard, and that every file derived from it is what `generate-error-registry` writes, without writing anything. Also available as `make check-error-registry` (alias `make cer`).
+
+ ```bash
+ .venv/bin/pipelex-dev check-error-registry
```
- **`generate-error-identity`**: Regenerate the committed `(error_type, title, type_uri)` snapshot of every `PipelexError` subclass at `tests/data/errors/error_identity.txt`. `error_type` is the bare class name and consumers outside this repo branch on it, so a rename is a silent wire break — the snapshot turns it into a reviewable diff, gated by `tests/unit/pipelex/errors/test_error_identity_snapshot.py`. Run after adding, renaming or removing an error class. Also available as `make generate-error-identity` (alias `make gei`).
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e9c4414f1..bcccbf0c8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,10 +2,25 @@
## [Unreleased]
+### Added
+
+- **The Pipelex error registry**: the codes Pipelex emits beyond the MTHDS core registry, under the `pipelex` extension prefix the core registry registers to it, are authored in one public file in the MTHDS error registry format, `pipelex/errors/registry/pipelex-error-registry.yaml`, each declaring its title, domain, retry verdict, steps, typed parameters, templates and status. The package ships its JSON snapshot, `pipelex-error-registry.json`, published under Pipelex's version, a pre-release's written in the SemVer form the registry format requires (`0.88.0rc1` as `0.88.0-rc.1`), which `load_pipelex_error_registry()` reads into a typed model, and every release attaches the snapshot to its GitHub release.
+- **`pipelex.errors.registry.pipelex_codes`**: `PipelexErrorCode`, a member per code of the Pipelex error registry, and for each code a closed, frozen and strict parameters model typed as the registry declares, with the code and its operator-only parameters as class attributes, `PIPELEX_ERROR_PARAMS` mapping each code to its model.
+- **A documentation page per error code**: docs.pipelex.com documents each code of the Pipelex error registry on its own page, under the Error Codes index at `errors/`, and its type URI, `https://docs.pipelex.com/errors/<code>`, leads to that page once a release documenting the code is the latest.
+- **`pipelex-dev generate-error-registry` and `pipelex-dev check-error-registry`** (`make ger`, `make cer`): generate the registry's snapshot, its typed Python and its pages from the source, refusing a source the format's JSON Schema, the typed model or the registry's rules refuse, or check that every derived file is what the generator writes; `pipelex-dev write-error-type-redirects` writes the redirects that make a code's type URI resolve, which every documentation deploy runs.
+
### Changed
- **`Jinja2TemplateSecurityError` is a `SecurityError` (Breaking)**: the template sandbox's refusal at render time now derives from `SecurityError`, like `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, instead of `ToolError`, so a host catching `SecurityError` catches it too and an `except ToolError` no longer does; it stays a type of its own, apart from `Jinja2TemplateRenderError`, and its `error_type`, title and classification are unchanged.
+### Fixed
+
+- **Pre-release documentation is published**: a push to a `pre-release/` branch deploys its documentation under the `pre-release` alias of docs.pipelex.com, where the deploy workflow called a make target with no recipe and published nothing.
+
+### Removed
+
+- **The per-class error pages (Breaking)**: the generated page every `PipelexError` class had under `docs/errors/`, `pipelex-dev generate-error-pages` (`make gep`) and `pipelex.errors.error_pages_generator` are gone; a class-derived `type_uri` names no page any more, and docs.pipelex.com sends such a URL to the Error Codes index.
+
## [v0.89.0] - 2026-10-17
### Added
diff --git a/CLAUDE.md b/CLAUDE.md
index 1c69078ae..452befd01 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,7 +12,7 @@
- **`make test-ts-gates` (`ttg`) after touching anything under `pipelex/codegen/emitters/`, or moving the pinned prettier version.** `make agent-test` does not cover the TypeScript emission: the two gates that read the emitted TypeScript as TypeScript need a node toolchain and skip silently without one. This target provisions a pinned prettier and zod into `.ts-toolchain/` (npm, node >= 22.6) and makes those gates fail instead of skip, as CI does. See `docs/contribute/typescript-emission-gates.md`.
- **`make cleanderived`** when linters or pytest collection get confused after files were erased or moved.
- **`CLAUDE.md` and `AGENTS.md` are generated.** Edit the sources in `pipelex/kit/agent_rules/` (assembled per `pipelex/kit/index.toml`) and run `make rules`; `make check-rules` is the CI gate, and `make agent-check` does not include it.
-- **`pipelex-dev`** (`.venv/bin/pipelex-dev --help`) holds the internal generators, most with a `make` alias. `generate-mthds-schema` (`gms`) after modifying `mthds_schema_generator.py`. `generate-error-pages` (`gep`) and `generate-error-identity` (`gei`) after adding, renaming or removing an error class: consumers outside this repo branch on `error_type`, so a rename is a silent wire break that the committed snapshot turns into a reviewable diff. `refresh-graph-ui-sri --mthds-ui-version <v> [--elkjs-version <v>]` when bumping the pinned mthds-ui or elkjs. `trace-input-semantics` when changing the structure blueprint, the structure generator, the schema render or the contract builder (`docs/contribute/trace-input-semantics.md`). `generate-projection-corpus` to rewrite the fixture corpus committed byte-identically in `mthds-js` and `mthds-python` (`docs/contribute/generate-projection-corpus.md`). `drift` carries the drift-contract commands above.
+- **`pipelex-dev`** (`.venv/bin/pipelex-dev --help`) holds the internal generators, most with a `make` alias. `generate-mthds-schema` (`gms`) after modifying `mthds_schema_generator.py`. `generate-error-identity` (`gei`) after adding, renaming or removing an error class: consumers outside this repo branch on `error_type`, so a rename is a silent wire break that the committed snapshot turns into a reviewable diff. `generate-error-registry` (`ger`) after changing the error registry, `pipelex/errors/registry/pipelex-error-registry.yaml`, or bumping the version, and `check-error-registry` (`cer`) to check its snapshot, typed codes and pages without writing them (`docs/contribute/error-registry.md`). `refresh-graph-ui-sri --mthds-ui-version <v> [--elkjs-version <v>]` when bumping the pinned mthds-ui or elkjs. `trace-input-semantics` when changing the structure blueprint, the structure generator, the schema render or the contract builder (`docs/contribute/trace-input-semantics.md`). `generate-projection-corpus` to rewrite the fixture corpus committed byte-identically in `mthds-js` and `mthds-python` (`docs/contribute/generate-projection-corpus.md`). `drift` carries the drift-contract commands above.
## Standards related to developing the Pipelex codebase
diff --git a/Makefile b/Makefile
index 42a951ad7..d23891822 100644
--- a/Makefile
+++ b/Makefile
@@ -125,8 +125,10 @@ make up-migration-schemas - Regenerate the migration fingerprint and default
make umig - Shorthand -> up-migration-schemas
make up-migration-schemas-force - Same, over a head golden recording material the models lost
make umigf - Shorthand -> up-migration-schemas-force
-make generate-error-pages - Generate one docs page per PipelexError subclass under docs/errors/
-make gep - Shorthand -> generate-error-pages
+make generate-error-registry - Write the error registry's snapshot, typed codes and docs/errors/ pages from its source
+make ger - Shorthand -> generate-error-registry
+make check-error-registry - Check the error registry against the MTHDS standard, and its derived files
+make cer - Shorthand -> check-error-registry
make generate-error-identity - Regenerate the committed PipelexError wire-identity snapshot
make gei - Shorthand -> generate-error-identity
make regenerate-test-models - Regenerate test model fixtures from backend configs
@@ -197,7 +199,7 @@ make docs-serve-versioned - Serve versioned docs locally with mike
make docs-list - List deployed documentation versions
make docs-deploy VERSION=x.y.z - Deploy docs as version x.y.z (local, no push)
make docs-deploy-stable - Deploy stable docs with 'latest' alias (CI only)
-make docs-deploy-specific-version - Deploy docs for the current version with 'pre-release' alias (CI only)
+make docs-deploy-specific-version-pre-release - Deploy docs for the current version with 'pre-release' alias (CI only)
make docs-deploy-root - Deploy root assets (404.html, robots.txt, index.html) to gh-pages
make docs-delete VERSION=x.y.z - Delete a deployed documentation version
@@ -239,11 +241,11 @@ export HELP
test-durations td test-durations-serial tds test-time tt test-time-serial tts \
merge-check-ruff-lint merge-check-ruff-format merge-check-mypy merge-check-pyright merge-check-plxt-format merge-check-plxt-lint \
li check-unused-imports fix-unused-imports check-TODOs check-uv \
- docs docs-check docs-serve-versioned docs-list docs-deploy docs-deploy-stable docs-deploy-specific-version docs-delete \
+ docs docs-check docs-serve-versioned docs-list docs-deploy docs-deploy-stable docs-deploy-specific-version-pre-release docs-delete \
generate-mthds-schema generate-mthds-schema-quiet gms check-mthds-schema cms \
generate-corpus-vocabulary generate-corpus-vocabulary-quiet \
check-ledger cl check-migration-schemas cmig up-migration-schemas up-migration-schemas-force umig umigf \
- generate-error-pages generate-error-pages-quiet gep \
+ generate-error-registry generate-error-registry-quiet ger check-error-registry cer \
generate-error-identity generate-error-identity-quiet gei \
up \
test-count check-test-badge \
@@ -510,15 +512,22 @@ umig: up-migration-schemas
umigf: up-migration-schemas-force
@echo "> done: umigf = up-migration-schemas-force"
-generate-error-pages: env
- $(call PRINT_TITLE,"Generating per-class error documentation pages")
- $(VENV_PIPELEX_DEV) generate-error-pages
+generate-error-registry: env
+ $(call PRINT_TITLE,"Writing every file derived from the error registry")
+ $(VENV_PIPELEX_DEV) generate-error-registry
-generate-error-pages-quiet: env
- $(VENV_PIPELEX_DEV) generate-error-pages --quiet
+generate-error-registry-quiet: env
+ $(VENV_PIPELEX_DEV) generate-error-registry --quiet
-gep: generate-error-pages
- @echo "> done: gep = generate-error-pages"
+ger: generate-error-registry
+ @echo "> done: ger = generate-error-registry"
+
+check-error-registry: env
+ $(call PRINT_TITLE,"Checking the error registry and its derived files")
+ $(VENV_PIPELEX_DEV) check-error-registry
+
+cer: check-error-registry
+ @echo "> done: cer = check-error-registry"
generate-error-identity: env
$(call PRINT_TITLE,"Regenerating the PipelexError wire-identity snapshot")
@@ -1163,16 +1172,16 @@ Sitemap: https://$(SITE_DOMAIN)/sitemap.xml
endef
export ROOT_ROBOTS_TXT
-docs: env generate-error-pages-quiet
+docs: env generate-error-registry-quiet
$(call PRINT_TITLE,"Serving documentation with mkdocs")
$(VENV_MKDOCS) serve -a 127.0.0.1:8000 -f "$(CURDIR)/mkdocs.yml" --watch "$(CURDIR)/docs" -s
-docs-check: env generate-error-pages-quiet
+docs-check: env generate-error-registry-quiet
$(call PRINT_TITLE,"Checking documentation build with mkdocs")
$(VENV_MKDOCS) build --strict
docs-serve-versioned: export PATH := $(VIRTUAL_ENV)/bin:$(PATH)
-docs-serve-versioned: env generate-error-pages-quiet
+docs-serve-versioned: env generate-error-registry-quiet
$(call PRINT_TITLE,"Serving versioned documentation with mike")
$(VENV_MIKE) serve
@@ -1182,19 +1191,19 @@ docs-list: env
$(VENV_MIKE) list
docs-deploy: export PATH := $(VIRTUAL_ENV)/bin:$(PATH)
-docs-deploy: env generate-error-pages-quiet
+docs-deploy: env generate-error-registry-quiet
$(call PRINT_TITLE,"Deploying documentation version $(if $(VERSION),$(VERSION),$(DOCS_VERSION))")
$(VENV_MIKE) deploy $(if $(VERSION),$(VERSION),$(DOCS_VERSION))
docs-deploy-stable: export PATH := $(VIRTUAL_ENV)/bin:$(PATH)
-docs-deploy-stable: env generate-error-pages-quiet
+docs-deploy-stable: env generate-error-registry-quiet
$(call PRINT_TITLE,"Deploying stable documentation $(DOCS_VERSION) with latest alias")
$(VENV_MIKE) deploy --push --update-aliases $(DOCS_VERSION) latest
$(VENV_MIKE) set-default --push latest
$(MAKE) docs-deploy-root
docs-deploy-specific-version-pre-release: export PATH := $(VIRTUAL_ENV)/bin:$(PATH)
-docs-deploy-specific-version-pre-release: env generate-error-pages-quiet
+docs-deploy-specific-version-pre-release: env generate-error-registry-quiet
$(call PRINT_TITLE,"Deploying documentation $(DOCS_VERSION) with pre-release alias")
$(VENV_MIKE) deploy --push --update-aliases $(DOCS_VERSION) pre-release
$(MAKE) docs-deploy-root
@@ -1205,10 +1214,14 @@ docs-deploy-specific-version-pre-release: env generate-error-pages-quiet
# Mike does NOT rewrite sitemap URLs for aliases — latest/sitemap.xml contains
# versioned URLs like /0.20.9/page/, identical to the version directory. The sed
# rewrites any semver path segment (including pre-release suffixes like -rc1) to /latest/.
+# `pipelex-dev write-error-type-redirects` writes errors/<code>/index.html at the root for every
+# error code latest/ documents, so that a problem's type URI, https://$(SITE_DOMAIN)/errors/<code>,
+# reaches the code's page under /latest/ (docs/contribute/error-registry.md). While latest/ documents
+# no code it writes no stub at all, so errors/ is staged only when the checkout holds it.
# WARNING: Do NOT insert comments inside the shell continuation chain below.
# Lines starting with # after a \ continuation become shell comments that silently
# truncate the command.
-docs-deploy-root:
+docs-deploy-root: env
ifeq ($(SITE_DOMAIN),)
$(error SITE_DOMAIN is empty — docs/CNAME is missing or blank. Cannot generate root assets with valid URLs)
endif
@@ -1223,10 +1236,12 @@ endif
sed 's|/[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*[^/]*/|/latest/|g' "$$TMPDIR/latest/sitemap.xml" > "$$TMPDIR/sitemap.xml" && \
if [ -f "$$TMPDIR/latest/llms.txt" ]; then cp "$$TMPDIR/latest/llms.txt" "$$TMPDIR/llms.txt"; fi && \
if [ -f "$$TMPDIR/latest/llms-full.txt" ]; then cp "$$TMPDIR/latest/llms-full.txt" "$$TMPDIR/llms-full.txt"; fi && \
+ $(VENV_PIPELEX_DEV) write-error-type-redirects --site-root "$$TMPDIR" --quiet && \
cd "$$TMPDIR" && \
git add 404.html robots.txt index.html sitemap.xml && \
(git add -A llms.txt llms-full.txt 2>/dev/null || true) && \
- (git diff --cached --quiet || git commit -m "Update root assets (404.html, robots.txt, index.html, sitemap.xml, llms.txt)") && \
+ if [ -d errors ]; then git add -A errors; fi && \
+ (git diff --cached --quiet || git commit -m "Update root assets (404.html, robots.txt, index.html, sitemap.xml, llms.txt, error type redirects)") && \
git push origin gh-pages
docs-delete: export PATH := $(VIRTUAL_ENV)/bin:$(PATH)
diff --git a/api/pipelex_api/error_uri.py b/api/pipelex_api/error_uri.py
index 99593e234..8d7e49e0a 100644
--- a/api/pipelex_api/error_uri.py
+++ b/api/pipelex_api/error_uri.py
@@ -27,8 +27,12 @@ def error_type_uri(error_type: str) -> str:
"""Return the RFC 7807 `type` URI for an error type name.
`EnvVarNotFoundError` -> `https://docs.pipelex.com/latest/errors/env-var-not-found-error/`.
- The trailing slash matches the canonical docs URL form, exactly as
- `PipelexError.type_uri()` produces it upstream.
+ The URI is derived from the class name, trailing slash included, exactly as
+ `PipelexError.type_uri()` derives it upstream, so the two share one shape on
+ the wire. No page lives at it: the per-class error pages are retired, and the
+ docs site's 404 page sends such a URI to the Error Codes index. The type URI
+ stays class-derived until every raise carries its code from the error
+ registry, whose type URI names the code's page.
"""
return f"{URLs.error_docs_base}/{pascal_case_to_kebab(error_type)}/"
diff --git a/docs/404.html b/docs/404.html
index 18be74a8e..ff074114c 100644
--- a/docs/404.html
+++ b/docs/404.html
@@ -136,7 +136,15 @@
'cookbook/using-inference-plugins': 'under-the-hood/writing-an-inference-plugin',
};
+ // The retired per-class error pages, `errors/<kebab-class-name>/`, which a class-derived `type`
+ // URI still names: send them to the error codes' index. A code's page is several segments deep,
+ // so this never catches one.
+ const retiredErrorPage = /^\/errors\/[a-z0-9]+(?:-[a-z0-9]+)*\/?$/;
+
function rewritePath(p) {
+ if (retiredErrorPage.test(p)) {
+ return '/errors/';
+ }
for (const [oldPrefix, newPrefix] of Object.entries(pathRewrites)) {
if (p.includes(oldPrefix)) {
return p.replace(oldPrefix, newPrefix);
diff --git a/docs/api-server/error-responses.md b/docs/api-server/error-responses.md
index 436e081ea..5e466569f 100644
--- a/docs/api-server/error-responses.md
+++ b/docs/api-server/error-responses.md
@@ -32,7 +32,7 @@ A failure response looks like this:
- `error_domain` — one of `input`, `config`, `runtime`. See [Status codes](#status-codes). Absent for domain-less pipelex errors (some pipelex tool errors, e.g. `EnvVarNotFoundError`, do not classify a domain — the HTTP status still defaults to **500**).
- `retryable` — whether retrying the same request can plausibly succeed. Always emitted for API-authored 4xx/5xx (always `false`). For pipelex-originated errors, present only when the source error populates it — `true` only when the originating error explicitly classifies itself as transient (e.g. inference provider rate limits), `false` when it declares itself a deterministic refusal of what the caller sent (e.g. `BundleResourceNotNamedError`, `BundleResourcePathError`, as for the API-authored `InvalidResourcePath`); absent on pipelex errors that don't set it (e.g. `EnvVarNotFoundError`, `PipelexConfigError`).
- `request_id` — server-correlated identifier for the request. Echoed from inbound `X-Request-ID` if provided, otherwise generated. Use this when reporting issues.
-- `error_category` — finer classification when the originating error provides one (currently used by inference errors — see [`InferenceErrorCategory`](https://docs.pipelex.com/latest/errors/) upstream).
+- `error_category` — finer classification when the originating error provides one (currently used by inference errors — see `InferenceErrorCategory` in the [Error Model](../under-the-hood/error-model.md#inferenceerrorcategory)).
- `user_action` — structured suggestion of what the caller should do next, when the error can author one.
- `model`, `provider`, `provider_metadata` — populated when the failure originated in an upstream inference call. **Stripped under STRICT disclosure** (see [Disclosure modes](#disclosure-modes)).
- `tree_refusal` — on a **422** `InvalidMethodFiles`, the MTHDS standard's refusal of a method tree the request sent: `{"code": "<refusal code>", "names": [...]}`, the code one of the standard's tree refusal codes, such as `invalid_tree_path`, `duplicate_key`, `excluded_name` or `malformed_entry`, and `names` the keys, paths or addresses it refuses. A name holding a code point UTF-8 cannot encode, such as a lone surrogate a JSON escape can carry, is written with that code point backslash-escaped. See [Pipe Run](pipe-run.md#sending-a-method-as-a-tree).
@@ -205,16 +205,16 @@ An unclassified failure is the one error a caller cannot diagnose from a request
## The `type` URI
-`type` is a stable URI pointing at the per-class documentation page upstream:
+`type` is a stable URI derived from the originating error's class:
```
https://docs.pipelex.com/latest/errors/<kebab-class-name>/
```
-Every `PipelexError` subclass resolves to a live page (the trailing slash is canonical — pipelex emits it to match the MkDocs `use_directory_urls: true` form). The page describes the class, the typical cause, and how to recover.
-
API-authored errors (`ValidationError`, `BadRequest`, `Unauthenticated`, etc.) follow the same convention with their own slugs.
+The per-class pages these URIs named are retired. Errors are moving to the codes of the MTHDS standard and of the Pipelex error registry, whose type URI is the code's page: `https://mthds.ai/errors/<code>` for a core code and `https://docs.pipelex.com/errors/<code>` for a `pipelex.` code, listed on the [Error Codes](../errors/index.md) page. Until a response carries its code, its class-derived `type` names no page of its own: the documentation site sends such a URL to the Error Codes index.
+
## Request correlation
Every response carries `X-Request-ID`. The middleware respects an inbound `X-Request-ID` header if present, otherwise mints one. It also binds that id onto the Pipelex runtime's log context for the duration of the request, so every record emitted underneath carries it as a `request_id` field — the server's own error lines and the runtime's lines from inside a run alike. Both run routes, `POST /v1/execute` and `POST /v1/start`, also put the id on the run's metadata, so when a run is dispatched to a worker, the lines the worker writes while it runs the run's workflow and activities carry the same id. What those lines look like, which fields they carry and where the id does not reach are in [Logging](logging.md).
diff --git a/docs/building-methods/concepts/python-classes.md b/docs/building-methods/concepts/python-classes.md
index 77f1b35bd..8b374149d 100644
--- a/docs/building-methods/concepts/python-classes.md
+++ b/docs/building-methods/concepts/python-classes.md
@@ -45,7 +45,7 @@ Classes inheriting from `StructuredContent` are automatically discovered and reg
**Best practice:** Keep your `StructuredContent` classes in dedicated modules (e.g., `*_struct.py` files) with minimal module-level code, or ensure module-level code is safe to execute during discovery.
!!! warning "Not available on the hosted API"
- Python structure classes are an open-source and self-hosted feature. Using one means importing its module, and the hosted API never imports a method's Python into its own process. It refuses any method whose Python declares a `StructuredContent` subclass, whether the method was sent inline, saved to the catalog or fetched by address. The refusal is a [`MethodStructuresRefusedError`](../../errors/method-structures-refused-error.md) naming each file and class. Python that only holds PipeFuncs is accepted, because PipeFuncs run in an isolated sandbox.
+ Python structure classes are an open-source and self-hosted feature. Using one means importing its module, and the hosted API never imports a method's Python into its own process. It refuses any method whose Python declares a `StructuredContent` subclass, whether the method was sent inline, saved to the catalog or fetched by address. The refusal is a `MethodStructuresRefusedError` naming each file and class. Python that only holds PipeFuncs is accepted, because PipeFuncs run in an isolated sandbox.
To run such a method on the hosted API, declare its types as MTHDS concepts with [inline structures](inline-structures.md). A PipeFunc can still return them: in the sandbox, Pipelex generates a `structures` module from the method's concepts, so the function imports the class it returns with `from structures import <domain>__<Concept>`.
diff --git a/docs/building-methods/pipes/pipe-operators/PipeJudge.md b/docs/building-methods/pipes/pipe-operators/PipeJudge.md
index 381f1a2c8..03a410e35 100644
--- a/docs/building-methods/pipes/pipe-operators/PipeJudge.md
+++ b/docs/building-methods/pipes/pipe-operators/PipeJudge.md
@@ -36,7 +36,7 @@ The output must be that native or a concept refining it, and `Dynamic` is neithe
**The verdict.** A yes/no question's verdict follows from its probability: yes when the probability of yes is at least the `threshold`, which defaults to `0.5`. A model that reports no probability gives its own verdict, and a declared threshold then cannot apply, which the run logs as a warning. A choice's verdict is the key of the option chosen, with the model's `confidence` and the `probabilities` of every option when it reports them. A rating's verdict is the index of the level chosen, `0` being the first level declared, with the model's `confidence`, the `probabilities` of every level keyed by its index written as text, and a continuous `position` on the scale, when it reports them. When the scale's levels carry labels, the verdict's `label` is the label of the level chosen, copied from the pipe's declaration.
-**A refusal fails the step.** A judgment model may decline to answer a question, and a refusal carries no verdict: it is never read as a no, as the first option or as the lowest level. A pipe asking one question has nowhere to leave its verdict absent, so the step fails with a [`JudgmentRefusedError`](../../../errors/judgment-refused-error.md) naming the pipe and the model; reword the question so it can be answered from the evidence, or give the step different evidence. A pipe asking several questions may leave a verdict absent instead, as the next section explains.
+**A refusal fails the step.** A judgment model may decline to answer a question, and a refusal carries no verdict: it is never read as a no, as the first option or as the lowest level. A pipe asking one question has nowhere to leave its verdict absent, so the step fails with a `JudgmentRefusedError` naming the pipe and the model; reword the question so it can be answered from the evidence, or give the step different evidence. A pipe asking several questions may leave a verdict absent instead, as the next section explains.
The [native concepts page](../../concepts/native-concepts.md) describes the fields of the three verdicts. A downstream pipe reads them like any other fields, for example a [`PipeCondition`](../pipe-controllers/PipeCondition.md) routing on `routing.choice`, or one gating on `approved.probability`.
@@ -84,7 +84,7 @@ levels = [{ label = "Minor" }, { label = "Major" }, { label = "Blocking" }]
**The questions share the evidence.** The prompt renders the evidence once, and every question is asked about it. A question may read a short parameter of its own, such as `$topic`, and every declared input must be read by the prompt or by at least one question.
-**A refusal leaves an optional field holding nothing.** When the model declines one question, the step leaves that question's field holding nothing if the field is optional, being neither `required` nor given a `default_value`, and logs a warning naming the question. When the field is `required` or carries a `default_value`, the step fails with a [`JudgmentRefusedError`](../../../errors/judgment-refused-error.md) naming the question, since a default filled in for it would read as a verdict the model never gave: reword the question, give the step different evidence, or make the field optional with no `default_value` so that a refusal leaves it holding nothing. Leaving a field optional with no default is how a method says that a refusal on that question is acceptable.
+**A refusal leaves an optional field holding nothing.** When the model declines one question, the step leaves that question's field holding nothing if the field is optional, being neither `required` nor given a `default_value`, and logs a warning naming the question. When the field is `required` or carries a `default_value`, the step fails with a `JudgmentRefusedError` naming the question, since a default filled in for it would read as a verdict the model never gave: reword the question, give the step different evidence, or make the field optional with no `default_value` so that a refusal leaves it holding nothing. Leaving a field optional with no default is how a method says that a refusal on that question is acceptable.
**A question depending on another's verdict is a later step.** The questions of one `PipeJudge` are answered independently over the same evidence, so none of them can read another's verdict. When one question only makes sense once another is answered, such as rating a problem's severity only when the message reports a problem at all, ask the second in a later `PipeJudge` of a [`PipeSequence`](../pipe-controllers/PipeSequence.md), behind a [`PipeCondition`](../pipe-controllers/PipeCondition.md) routing on the first verdict when the second should not always be asked.
diff --git a/docs/building-methods/pipes/pipe-operators/PipeLLM.md b/docs/building-methods/pipes/pipe-operators/PipeLLM.md
index e61d35ff5..9e6b667a3 100644
--- a/docs/building-methods/pipes/pipe-operators/PipeLLM.md
+++ b/docs/building-methods/pipes/pipe-operators/PipeLLM.md
@@ -257,7 +257,7 @@ When `model` is specified as a table (inline LLM setting), it accepts the follow
A setting the model it resolves to cannot take is refused when the method loads, before a run spends anything: validation runs the check the model's worker runs before every call, so a reasoning setting on a model that does not reason, a reasoning budget on a model taking only an effort, or a budget its `max_tokens` cannot hold is an `llm_setting_refused_by_model` error on the `model` or `model_to_structure` field holding the setting. The setting checked is the one the output is generated with: `model` for a single text, the structuring setting for anything else.
-A text the model cannot finish within `max_tokens`, or within its context window, fails the pipe with [`LLMCompletionTruncatedError`](../../../errors/llm-completion-truncated-error.md) rather than passing the partial text on as the pipe's output; a text the model refuses or a safety filter stops fails it with [`LLMCompletionRefusedError`](../../../errors/llm-completion-refused-error.md). The first names the output tokens used and the limit sent, so raising `max_tokens` or shortening the input is the fix; a model that reasons spends its reasoning from the same limit.
+A text the model cannot finish within `max_tokens`, or within its context window, fails the pipe with `LLMCompletionTruncatedError` rather than passing the partial text on as the pipe's output; a text the model refuses or a safety filter stops fails it with `LLMCompletionRefusedError`. The first names the output tokens used and the limit sent, so raising `max_tokens` or shortening the input is the fix; a model that reasons spends its reasoning from the same limit.
!!! tip "More on Reasoning"
For provider-specific behavior and model-specific examples, see [Reasoning Controls](../../../under-the-hood/reasoning-controls.md).
diff --git a/docs/building-methods/pipes/running-on-the-hosted-api.md b/docs/building-methods/pipes/running-on-the-hosted-api.md
index 5f3cffa53..0a980f749 100644
--- a/docs/building-methods/pipes/running-on-the-hosted-api.md
+++ b/docs/building-methods/pipes/running-on-the-hosted-api.md
@@ -104,7 +104,7 @@ except ApiUnreachableError as exc:
`start_and_wait` sends more than the start, so tell its requests apart with its two callbacks. `on_starting` is called right before each request that may create a run is sent, and `on_started` with the acknowledgement once the run exists. A failure before `on_starting` was called started nothing, a failure after `on_started` concerns a run whose id you hold, which `wait_for_result` follows, and only a failure in between needs its cause read as above.
-`pipelex run --hosted` and `pipelex-agent run --runner hosted` draw the same line, and report the second case as pipelex's own [`HostedRunOutcomeUnknownError`](../../errors/hosted-run-outcome-unknown-error.md). `PipelexAPIClient` never raises that error, so a program that calls the client directly reads the cause itself.
+`pipelex run --hosted` and `pipelex-agent run --runner hosted` draw the same line, and report the second case as pipelex's own `HostedRunOutcomeUnknownError`. `PipelexAPIClient` never raises that error, so a program that calls the client directly reads the cause itself.
## Related Documentation
diff --git a/docs/configuration/config-technical/inference-backend-config.md b/docs/configuration/config-technical/inference-backend-config.md
index ba49d1a9d..50d6877bb 100644
--- a/docs/configuration/config-technical/inference-backend-config.md
+++ b/docs/configuration/config-technical/inference-backend-config.md
@@ -685,7 +685,7 @@ The system loads configurations in this order:
Common error types:
- `ModelDeckNotFoundError`: Missing LLM deck configuration files
-- `ModelNotFoundError`: Referenced model not found in the deck
+- `ModelNotFoundError`: Referenced model not found in the deck. On your machine, the deck may be out of date: new aliases and presets are added to Pipelex over time, and the files under `.pipelex/inference/deck/` are not refreshed automatically. Delete them, or the whole `.pipelex/inference/` directory, and run `pipelex init inference` to regenerate them; if the model is still not found, check that one of the deck's files defines the handle, that the backend it routes to in `.pipelex/inference/routing_profiles.toml` is enabled in `.pipelex/inference/backends.toml`, and that you hold that backend's credentials. `pipelex run` gives this remedy in its error panel, and no message of the error carries it, since the message also reaches hosted callers, who have no local deck
- `LLMHandleNotFoundError`: Referenced model or alias not found
- `ModelChoiceNotFoundError`: Referenced preset/choice not found
diff --git a/docs/configuration/config-technical/network-config.md b/docs/configuration/config-technical/network-config.md
index 2b426dbac..c96157a79 100644
--- a/docs/configuration/config-technical/network-config.md
+++ b/docs/configuration/config-technical/network-config.md
@@ -21,7 +21,7 @@ The value above is the default.
With `is_fetch_ssrf_guard_enabled = true`, every download of a value's URL is checked when the connection opens, on the first request and on every redirect hop to a new host. The host is resolved, and the connection is refused when the name is `localhost` or a cloud metadata alias, or when any address it resolves to is not globally routable: private networks (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), loopback, link-local (including the `169.254.169.254` metadata endpoint), carrier-grade NAT, multicast, reserved and unspecified addresses, in IPv4 and IPv6. Pipelex then connects to the address it checked, so a DNS record that changes between the check and the connection cannot slip through.
-A refusal raises [`SsrfBlockedError`](../../errors/ssrf-blocked-error.md) and fails the pipe that needed the bytes. It is not treated as a failed download: where Pipelex would otherwise keep a generated image's remote URL after a download error, a refused URL fails the pipe instead. The error message names the host that was requested and never the address it resolved to.
+A refusal raises `SsrfBlockedError` and fails the pipe that needed the bytes. It is not treated as a failed download: where Pipelex would otherwise keep a generated image's remote URL after a download error, a refused URL fails the pipe instead. The error message names the host that was requested and never the address it resolved to.
A URL passed to a provider as a URL, for a model that fetches images itself, is not downloaded by Pipelex and is not checked by this guard.
diff --git a/docs/contribute/drift-contracts.md b/docs/contribute/drift-contracts.md
index c285cd4d5..586d4d6d6 100644
--- a/docs/contribute/drift-contracts.md
+++ b/docs/contribute/drift-contracts.md
@@ -8,7 +8,7 @@ Not every code↔doc relationship deserves a review contract. This repo distingu
| Tier | Mechanism | Judgment needed |
|---|---|---|
-| **Derived** | Regenerate and diff: `check-config-sync`, `check-mthds-schema`, `generate-error-pages`, `generate-error-identity` | None — the output is a pure function of its sources |
+| **Derived** | Regenerate and diff: `check-config-sync`, `check-mthds-schema`, `check-error-registry`, `generate-error-identity` | None — the output is a pure function of its sources |
| **Linkage** | Referential integrity of declared cross-references (the spec ↔ verifying-test back-link pair) | None — links either resolve or they don't |
| **Review** | Drift contracts: "this changed → that must be looked at, and the look recorded" | Yes — someone must judge whether the target still holds |
diff --git a/docs/contribute/error-registry.md b/docs/contribute/error-registry.md
new file mode 100644
index 000000000..597679f0c
--- /dev/null
+++ b/docs/contribute/error-registry.md
@@ -0,0 +1,95 @@
+---
+title: "The Error Registry"
+description: "How Pipelex's error codes are authored in one public registry file, in the MTHDS registry format, and how its JSON snapshot, its typed Python and its documentation pages are generated and checked from it."
+---
+
+# The Error Registry
+
+The MTHDS standard names every error a runner or a client can meet with a code, and publishes those codes as its core error registry. What the standard leaves to implementations, such as billing, organizations, the hosted catalog, Pipelex's storage, its own configuration and plugins, and the components it ships, Pipelex names with codes of its own under the `pipelex` extension prefix, which the core registry registers to Pipelex. This page describes how those codes are maintained.
+
+## One source, three derived outputs
+
+The Pipelex codes are authored in one public file, `pipelex/errors/registry/pipelex-error-registry.yaml`, in the [MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/). Each entry declares every member its code needs: its title, the domain whose actor must act, its retry verdict, the step for that actor and the step for any other reader, its typed parameters, the templates its sentences are written from, its HTTP status, and what its page says it means and what to do about it.
+
+Everything else is generated from that file, and never edited by hand:
+
+- `pipelex/errors/registry/pipelex-error-registry.json`, the registry's JSON snapshot. The `pipelex` package ships it, `load_pipelex_error_registry()` in `pipelex/errors/registry/registry_document.py` reads it into a typed model, and every release attaches it to the GitHub release as an asset.
+- `pipelex/errors/registry/pipelex_codes.py`, the typed Python of the codes: a `PipelexErrorCode` member per code, and a closed, frozen parameters model per code, `PIPELEX_ERROR_PARAMS` mapping each code to its model.
+- The documentation pages under `docs/errors/`: the [Error Codes](../errors/index.md) index and one page per code.
+
+Regenerate them all after changing the source:
+
+```bash
+make generate-error-registry # alias: make ger
+```
+
+The generator refuses to write anything from a source with a fault, and prints the faults. A file that does not load is such a fault, printed like the others: a source that is not valid YAML, holds a key twice, holds a key that is a sequence or a mapping, or writes a version, a vendored file that cannot be read or parsed, and a `pyproject.toml` version the registry cannot be published under. To check without writing, which is what the test suite does as well:
+
+```bash
+make check-error-registry # alias: make cer
+```
+
+The test suite fails when any derived file is not what the generator writes, so a change to the source cannot land without its outputs.
+
+### The registry's version
+
+The source carries no version. The snapshot takes Pipelex's own version, the `[project].version` of `pyproject.toml`, so the number is written in one place and every release publishes the registry under the release's number. A version bump therefore leaves the snapshot and the index page stale until they are regenerated, which the test suite reports: run `make generate-error-registry` after bumping the version. The release workflow refuses to attach a snapshot whose version is not the release's.
+
+The registry format writes a version as SemVer, while Pipelex's is a PEP 440 version, so a pre-release's number is written in its SemVer form: `0.88.0a1` becomes `0.88.0-a.1`, `0.88.0b2` becomes `0.88.0-b.2` and `0.88.0rc1` becomes `0.88.0-rc.1`, which SemVer orders as PEP 440 does, while a release's number, such as `0.88.0`, is written as it is. The generator and the release workflow's check both take the conversion from `pipelex/cli/dev_cli/commands/error_registry/registry_version.py`, which needs only the standard library so that the workflow runs it on a bare runner.
+
+## The typed codes
+
+Whoever raises a code builds its parameters with the model the registry generates, so that the parameters carry exactly the types the registry declares and none it does not:
+
+```python
+from pipelex.errors.registry.pipelex_codes import ConfigVariableMissingParams, PipelexErrorCode
+
+params = ConfigVariableMissingParams(variable="OPENAI_API_KEY", source="env")
+assert params.code == PipelexErrorCode.CONFIG_VARIABLE_MISSING
+assert params.operator_only_params == frozenset({"variable", "source"})
+```
+
+An `identifier` or a `caller_text` is a `str`, an `integer` an `int`, a `seconds` a `float` and a `bytes` an `int`, neither ever negative, a `sha256` a lowercase hexadecimal `str`, an `enum` the `Literal` of its values, and a `list` a `list` of its items' type, each item constrained as a parameter of that type is, so a list of `bytes` refuses a negative item. An optional parameter is its type or `None`. The models are strict, so a value of another type is refused rather than coerced: a line given as `"3"` or `True` is refused, while an integer is accepted where a number of seconds is declared. `operator_only_params` names the parameters that only whoever runs the runtime may read, which an implementation leaves out of every problem it answers to a caller.
+
+## The checks
+
+`make check-error-registry` and the test suite check the source in three passes, each run only on a document the previous one accepts:
+
+1. The format's JSON Schema, vendored from the standard, refuses a member missing, unknown or forbidden in its case, and a value outside its closed lists of domains, retry verdicts and step kinds.
+2. The typed model Pipelex reads the registry with refuses the same documents, so that the model can never accept one the schema would not. A member written as `null` is among them: the format leaves an optional member out rather than writing it as `null`, and the model refuses a `null` rather than reading it as an absent member. So is a value of another JSON type: the model is strict, so a status written `"402"` or an `optional` written `"true"` is refused rather than coerced, while a status written `402.0`, which JSON Schema counts as an integer, is read as `402`. The model refuses one thing more than the schema: a `see` reference whose path holds a segment made of dots alone, such as `..`, which the schema's pattern accepts and which would name a page outside the documentation.
+3. The rules a schema cannot state, which the standard applies to its own registry: a family or a code given twice, a code whose family is not declared, a family no code uses, a code or a family outside the `pipelex` prefix, a template naming a parameter its reader may not see, and a `see` reference to a documentation page that does not exist. A page under `docs/errors/` is the generator's, so a reference there must name a page this registry generates, which a new code may do before the page is written; a page anywhere else must be one this repository holds; and a page that resolves outside `docs/` is refused wherever it points. A template may name only a declared parameter that is not optional, and an operator-only parameter only in the actor's step of an `operator` code.
+
+To these, Pipelex adds the rules its own use of the registry needs:
+
+- the core registry registers the `pipelex` prefix under the base URL the pages are published at, `https://docs.pipelex.com/errors`;
+- every code a sentence names in backticks exists: a core code such as `provider.credential_refused` in the core registry, a `pipelex.` code in this one;
+- every parameter name can be a field of the generated parameters model, so it is neither a Python keyword, nor an attribute of a pydantic model, nor a builtin the model's annotations name, such as `int` or `str`, which the field would shadow;
+- distinct codes generate distinct names in the typed Python: the generated names drop the prefix and join the segments, so `pipelex.run_job.failed` and `pipelex.run.job_failed` would both be `RUN_JOB_FAILED` and `RunJobFailedParams`, and the check refuses such a pair rather than let one model replace the other;
+- every title and parameter description can be written into a docstring of the typed Python, so none holds a backslash or a closing quote, and every parameter's field fits on one line of the formatter's length.
+
+## The standard's vendored files
+
+The checks read two files of the standard, copied verbatim into `pipelex/cli/dev_cli/commands/error_registry/standard/`: the registry format's JSON Schema, `mthds-error-registry.schema.json`, and the core registry's snapshot, `mthds-error-registry.json`. `vendored.toml` beside them records the standard's repository, the commit and the version they were copied from, and the SHA-256 digest of each, which a test compares with the files. Nothing at run time reads these copies. To refresh them, copy both files from the standard's release, at the tag `v<version>` or from its release assets, and update the record.
+
+The development CLI, where the checks and the generators live, is not shipped in the wheel, so neither are these files nor `jsonschema`, which only the checks use.
+
+## The pages and the type URI
+
+A code's type URI is the registry's base URL, a slash, then the whole code: `https://docs.pipelex.com/errors/pipelex.billing.credit_exhausted`. Its page is `docs/errors/pipelex/billing/credit_exhausted.md`, one directory per segment but the last, as the MTHDS standard lays out the core codes' pages, which the versioned site serves at `/latest/errors/pipelex/billing/credit_exhausted/`.
+
+The type URI names no version, and the site is served by GitHub Pages from its `gh-pages` branch, with no server-side redirect of our own, so the documentation's deployment closes the gap. `make docs-deploy-root`, which every documentation deploy runs, calls `pipelex-dev write-error-type-redirects` on its checkout of the `gh-pages` branch: for every code whose page the `latest` version holds, it writes `errors/<code>/index.html` at the site's root, a page that redirects to the code's `/latest/` page, and it removes the stub of a code `latest` no longer documents. While `latest` documents at least one code, it also writes `errors/index.html`, which sends the base URL to the [Error Codes](../errors/index.md) index under `/latest/`; before a release that documents the codes is the latest, it writes no stub at all, removes a root stub it wrote earlier, and leaves the base URL to the site's `404.html`, which sends it to `/latest/errors/` as it sends any path without a version. It only ever removes a file that carries its stubs' marker. GitHub Pages answers a URL naming a directory without its trailing slash, as the type URI does, with a redirect to the same URL with the slash, whatever its last segment holds, and serves the stub there. A code's type URI therefore resolves once a release that documents it is the latest version.
+
+Before the error registry, every `PipelexError` class had a generated page at `errors/<kebab-class-name>/`, which its class-derived `type_uri` named. Those pages are retired, and the site's `404.html` sends such a URL to the [Error Codes](../errors/index.md) index.
+
+## Adding or changing a code
+
+1. Add or edit the entry in `pipelex/errors/registry/pipelex-error-registry.yaml`, declaring every member. A new family is declared under `families`, in the order the pages present them.
+2. Run `make generate-error-registry`, then read the diff of the snapshot, the typed codes and the code's page.
+3. Run `make check-error-registry`, or the tests under `tests/unit/pipelex/errors/registry/`.
+
+A registered prefix's codes follow the standard's versioning: a new code or family is an addition, while a changed domain, retry verdict, step kind, status or parameter type changes what the runtime emits and is a breaking change for whoever branches on it, noted as such in the changelog. A reworded title or template is neither.
+
+## Related
+
+- [Error Model](../under-the-hood/error-model.md#error-codes-and-the-pipelex-error-registry): how errors are classified and reported.
+- [Drift Contracts](drift-contracts.md): the derived checks, the registry's among them.
diff --git a/docs/contribute/inference-family-surface.md b/docs/contribute/inference-family-surface.md
index 03167d2ad..33ef82155 100644
--- a/docs/contribute/inference-family-surface.md
+++ b/docs/contribute/inference-family-surface.md
@@ -14,7 +14,7 @@ Most of the list is enforced by the type checker: the matches over the family en
2. **The family enums, together.** `InferenceFamily` in `pipelex/plugins/inference_backend_registry.py`, `ModelType` in `pipelex/cogt/model_backends/model_type.py`, `InferenceErrorFamily` in `pipelex/cogt/inference/error_render.py` with an entry in both its failure-class and not-found-class tables, and `ModelCategory` in `pipelex/cogt/models/model_listing.py`, which is what `pipelex-agent models` and `check-model` list from.
-3. **The error classes** in `pipelex/cogt/exceptions.py`: a job failure, a model-not-found (subclassing `ModelNotFoundError`) and a handle-not-found. Then regenerate the error pages and the identity snapshot (`make gep`, `make gei`); the snapshot test fails until you do.
+3. **The error classes** in `pipelex/cogt/exceptions.py`: a job failure, a model-not-found (subclassing `ModelNotFoundError`) and a handle-not-found. Then regenerate the identity snapshot (`make gei`); the snapshot test fails until you do. A code the family's errors need beyond those the error registry already declares is added to `pipelex/errors/registry/pipelex-error-registry.yaml`, followed by `make ger` to regenerate its outputs and `make cer` to check them ([The Error Registry](error-registry.md)).
4. **The job identity** in `pipelex/system/job_metadata.py`: a `JobCategory` member, a `UnitJobId` member and its display arm.
diff --git a/docs/errors/ambiguous-inputs-files-error.md b/docs/errors/ambiguous-inputs-files-error.md
deleted file mode 100644
index bd1a8e221..000000000
--- a/docs/errors/ambiguous-inputs-files-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Ambiguous inputs files"
-description: "Reference for the `AmbiguousInputsFilesError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Ambiguous inputs files
-
-Raised when a bundle directory holds both default inputs files on auto-detect.
-
-| Field | Value |
-|---|---|
-| `error_type` | `AmbiguousInputsFilesError` |
-| `title` | Ambiguous inputs files |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/ambiguous-inputs-files-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.cli.commands.run.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-| `user_action` | `change_input` — Pass --inputs explicitly to choose which inputs file to use |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/anthropic-factory-error.md b/docs/errors/anthropic-factory-error.md
deleted file mode 100644
index d9c0a9059..000000000
--- a/docs/errors/anthropic-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Anthropic factory"
-description: "Reference for the `AnthropicFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Anthropic factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `AnthropicFactoryError` |
-| `title` | Anthropic factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/anthropic-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.anthropic.anthropic_exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/anthropic-model-listing-error.md b/docs/errors/anthropic-model-listing-error.md
deleted file mode 100644
index cb0c7d54a..000000000
--- a/docs/errors/anthropic-model-listing-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Anthropic model listing"
-description: "Reference for the `AnthropicModelListingError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Anthropic model listing
-
-| Field | Value |
-|---|---|
-| `error_type` | `AnthropicModelListingError` |
-| `title` | Anthropic model listing |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/anthropic-model-listing-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.anthropic.anthropic_exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/anthropic-sdk-unsupported-error.md b/docs/errors/anthropic-sdk-unsupported-error.md
deleted file mode 100644
index 13702676b..000000000
--- a/docs/errors/anthropic-sdk-unsupported-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Anthropic SDK unsupported"
-description: "Reference for the `AnthropicSDKUnsupportedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Anthropic SDK unsupported
-
-| Field | Value |
-|---|---|
-| `error_type` | `AnthropicSDKUnsupportedError` |
-| `title` | Anthropic SDK unsupported |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/anthropic-sdk-unsupported-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.anthropic.anthropic_exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/anthropic-worker-configuration-error.md b/docs/errors/anthropic-worker-configuration-error.md
deleted file mode 100644
index 7de54be01..000000000
--- a/docs/errors/anthropic-worker-configuration-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Anthropic worker configuration"
-description: "Reference for the `AnthropicWorkerConfigurationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Anthropic worker configuration
-
-| Field | Value |
-|---|---|
-| `error_type` | `AnthropicWorkerConfigurationError` |
-| `title` | Anthropic worker configuration |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/anthropic-worker-configuration-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.anthropic.anthropic_exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/argument-type-error.md b/docs/errors/argument-type-error.md
deleted file mode 100644
index 107931208..000000000
--- a/docs/errors/argument-type-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Argument type"
-description: "Reference for the `ArgumentTypeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Argument type
-
-| Field | Value |
-|---|---|
-| `error_type` | `ArgumentTypeError` |
-| `title` | Argument type |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/argument-type-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.misc.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/async-execution-not-enabled-error.md b/docs/errors/async-execution-not-enabled-error.md
deleted file mode 100644
index f12933978..000000000
--- a/docs/errors/async-execution-not-enabled-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Async execution not enabled"
-description: "Reference for the `AsyncExecutionNotEnabledError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Async execution not enabled
-
-Raised when a route that depends on asynchronous execution is hit on a deployment that does not have an async execution backend enabled.
-
-| Field | Value |
-|---|---|
-| `error_type` | `AsyncExecutionNotEnabledError` |
-| `title` | Async execution not enabled |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/async-execution-not-enabled-error/` |
-| `error_domain` | `config` |
-| Defined in | `pipelex.pipe_run.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/authoring-and-language.md b/docs/errors/authoring-and-language.md
deleted file mode 100644
index b1a5e2cc5..000000000
--- a/docs/errors/authoring-and-language.md
+++ /dev/null
@@ -1,142 +0,0 @@
----
-title: "Authoring & language"
-description: "Pipelex error classes in the Authoring & language area, grouped by subsystem."
----
-
-<!-- pipelex:generated -->
-
-# Authoring & language
-
-Each error class below has a stable RFC 7807 `type` URI that dereferences to its
-own page. Classes are grouped by subsystem.
-
-## MTHDS parsing
-
-- [`BundleElaboratorError`](bundle-elaborator-error.md) — Bundle elaborator
-- [`MthdsParserError`](mthds-parser-error.md) — MTHDS parser
-
-## Core language
-
-- [`BundleResourceNotNamedError`](bundle-resource-not-named-error.md) — Bundle resource not named
-- [`BundleResourcePathError`](bundle-resource-path-error.md) — Bundle resource path
-- [`ConceptCodeError`](concept-code-error.md) — Concept code
-- [`ConceptError`](concept-error.md) — Concept error
-- [`ConceptFactoryError`](concept-factory-error.md) — Concept factory
-- [`ConceptLibraryConceptNotFoundError`](concept-library-concept-not-found-error.md) — Concept library concept not found
-- [`ConceptRefAmbiguousError`](concept-ref-ambiguous-error.md) — Concept ref ambiguous
-- [`ConceptRefineError`](concept-refine-error.md) — Concept refine
-- [`ConceptStringError`](concept-string-error.md) — Concept string
-- [`ConceptStructureGeneratorError`](concept-structure-generator-error.md) — Concept structure generator
-- [`ConceptStructureValidationError`](concept-structure-validation-error.md) — Concept structure validation
-- [`DateContentError`](date-content-error.md) — Date content
-- [`DomainCodeError`](domain-code-error.md) — Domain code
-- [`DomainFactoryError`](domain-factory-error.md) — Domain factory
-- [`ExplicitConceptIncompatibleError`](explicit-concept-incompatible-error.md) — Explicit concept incompatible
-- [`InputShapingError`](input-shaping-error.md) — Input shaping
-- [`InputStuffSpecNotFoundError`](input-stuff-spec-not-found-error.md) — Input stuff spec not found
-- [`InputStuffSpecsError`](input-stuff-specs-error.md) — Input stuff specs
-- [`InputStuffSpecsFactoryError`](input-stuff-specs-factory-error.md) — Input stuff specs factory
-- [`ListWhereSingularError`](list-where-singular-error.md) — List where singular
-- [`MethodFileUnavailableError`](method-file-unavailable-error.md) — Method file unavailable
-- [`MultiplicityCountMismatchError`](multiplicity-count-mismatch-error.md) — Multiplicity count mismatch
-- [`NativeConceptDefinitionError`](native-concept-definition-error.md) — Native concept definition
-- [`NullInputError`](null-input-error.md) — Null input
-- [`OptionalValueAbsentError`](optional-value-absent-error.md) — Optional value absent
-- [`PipeFactoryError`](pipe-factory-error.md) — Pipe factory
-- [`PipeInputError`](pipe-input-error.md) — Pipe input
-- [`PipeInputsFactoryError`](pipe-inputs-factory-error.md) — Pipe inputs factory
-- [`PipeLoadRefusalError`](pipe-load-refusal-error.md) — Pipe load refusal
-- [`PipeOperatorModelChoiceError`](pipe-operator-model-choice-error.md) — Pipe operator model choice
-- [`PipeRunError`](pipe-run-error.md) — Pipe run
-- [`PipeRunInputsError`](pipe-run-inputs-error.md) — Pipe run inputs
-- [`StructureClassError`](structure-class-error.md) — Structure class
-- [`StructureValidationError`](structure-validation-error.md) — Structure validation
-- [`StuffArtefactError`](stuff-artefact-error.md) — Stuff artefact
-- [`StuffArtefactReservedFieldError`](stuff-artefact-reserved-field-error.md) — Stuff artefact reserved field
-- [`StuffContentFactoryError`](stuff-content-factory-error.md) — Stuff content factory
-- [`StuffContentTypeError`](stuff-content-type-error.md) — Stuff content type
-- [`StuffContentValidationError`](stuff-content-validation-error.md) — Stuff content validation
-- [`StuffError`](stuff-error.md) — Stuff error
-- [`StuffFactoryError`](stuff-factory-error.md) — Stuff factory
-- [`StuffSpecError`](stuff-spec-error.md) — Stuff spec
-- [`StuffSpecFactoryError`](stuff-spec-factory-error.md) — Stuff spec factory
-- [`TreeModuleShadowingError`](tree-module-shadowing-error.md) — Tree module shadowing
-- [`TreePythonError`](tree-python-error.md) — Tree python
-- [`TreePythonHeldError`](tree-python-held-error.md) — Tree python held
-- [`UnknownInputNameError`](unknown-input-name-error.md) — Unknown input name
-- [`WorkingMemoryConsistencyError`](working-memory-consistency-error.md) — Working memory consistency
-- [`WorkingMemoryError`](working-memory-error.md) — Working memory
-- [`WorkingMemoryFactoryError`](working-memory-factory-error.md) — Working memory factory
-- [`WorkingMemoryStuffAttributeNotFoundError`](working-memory-stuff-attribute-not-found-error.md) — Working memory stuff attribute not found
-- [`WorkingMemoryStuffNotFoundError`](working-memory-stuff-not-found-error.md) — Working memory stuff not found
-- [`WorkingMemoryTypeError`](working-memory-type-error.md) — Working memory type
-- [`WorkingMemoryVariableError`](working-memory-variable-error.md) — Working memory variable
-- [`WrongScalarKindError`](wrong-scalar-kind-error.md) — Wrong scalar kind
-
-## Pipe operators
-
-- [`ConstructFieldBlueprintTypeError`](construct-field-blueprint-type-error.md) — Construct field blueprint type
-- [`ConstructFieldBlueprintValueError`](construct-field-blueprint-value-error.md) — Construct field blueprint value
-- [`PipeComposeError`](pipe-compose-error.md) — Pipe compose
-- [`PipeComposeFactoryError`](pipe-compose-factory-error.md) — Pipe compose factory
-- [`PipeDocGenFactoryError`](pipe-doc-gen-factory-error.md) — Pipe doc gen factory
-- [`PipeDocGenRunError`](pipe-doc-gen-run-error.md) — Pipe doc gen run
-- [`PipeDocGenTemplateCheckError`](pipe-doc-gen-template-check-error.md) — Pipe doc gen template check
-- [`PipeDocGenTemplateFileUncheckedError`](pipe-doc-gen-template-file-unchecked-error.md) — Pipe doc gen template file unchecked
-- [`PipeDocGenUndefinedValueError`](pipe-doc-gen-undefined-value-error.md) — Pipe doc gen undefined value
-- [`PipeExtractFactoryError`](pipe-extract-factory-error.md) — Pipe extract factory
-- [`PipeFuncExecutionError`](pipe-func-execution-error.md) — Pipe func execution
-- [`PipeFuncFunctionError`](pipe-func-function-error.md) — Pipe func function
-- [`PipeFuncTransportError`](pipe-func-transport-error.md) — Pipe func transport
-- [`PipeImgGenFactoryError`](pipe-img-gen-factory-error.md) — Pipe img gen factory
-- [`PipeImgGenRunError`](pipe-img-gen-run-error.md) — Pipe img gen run
-- [`PipeJudgeError`](pipe-judge-error.md) — Pipe judge
-- [`PipeJudgeInputCapabilityError`](pipe-judge-input-capability-error.md) — Pipe judge input capability
-- [`PipeLLMFactoryError`](pipe-llm-factory-error.md) — Pipe LLM factory
-- [`PipeOperatorModelAvailabilityError`](pipe-operator-model-availability-error.md) — Pipe operator model availability
-- [`PipeSearchError`](pipe-search-error.md) — Pipe search
-- [`PipeSearchFactoryError`](pipe-search-factory-error.md) — Pipe search factory
-- [`StructuredContentComposerTypeError`](structured-content-composer-type-error.md) — Structured content composer type
-- [`StructuredContentComposerValidationError`](structured-content-composer-validation-error.md) — Structured content composer validation
-- [`StructuredContentComposerValueError`](structured-content-composer-value-error.md) — Structured content composer value
-- [`WithImagesFilterError`](with-images-filter-error.md) — With images filter
-
-## Pipe controllers
-
-- [`BindingPathUnresolvedError`](binding-path-unresolved-error.md) — Binding path unresolved
-- [`BindingStepRunError`](binding-step-run-error.md) — Binding step run
-- [`PipeBatchFactoryError`](pipe-batch-factory-error.md) — Pipe batch factory
-- [`PipeConditionFactoryError`](pipe-condition-factory-error.md) — Pipe condition factory
-- [`PipeControllerError`](pipe-controller-error.md) — Pipe controller
-- [`PipeControllerOutputConceptMismatchError`](pipe-controller-output-concept-mismatch-error.md) — Pipe controller output concept mismatch
-- [`PipeParallelFactoryError`](pipe-parallel-factory-error.md) — Pipe parallel factory
-- [`PipeSequenceFactoryError`](pipe-sequence-factory-error.md) — Pipe sequence factory
-
-## Pipe signatures
-
-- [`PipeSignatureNotExecutableError`](pipe-signature-not-executable-error.md) — Pipe signature not executable
-
-## Libraries
-
-- [`ConceptLibraryError`](concept-library-error.md) — Concept library
-- [`ConceptLoadingError`](concept-loading-error.md) — Concept loading
-- [`CrateNormalizationError`](crate-normalization-error.md) — Crate normalization error
-- [`DomainLibraryError`](domain-library-error.md) — Domain library
-- [`DomainLoadingError`](domain-loading-error.md) — Domain loading
-- [`EmptyMethodTreeError`](empty-method-tree-error.md) — Empty method tree
-- [`EntryPipeAmbiguousError`](entry-pipe-ambiguous-error.md) — Entry pipe ambiguous
-- [`EntryPipeNotFoundError`](entry-pipe-not-found-error.md) — Entry pipe not found
-- [`HostLibraryRequirementsError`](host-library-requirements-error.md) — Host library requirements
-- [`HostLibraryTreeError`](host-library-tree-error.md) — Host library tree
-- [`LibraryError`](library-error.md) — Library error
-- [`LibraryLoadingError`](library-loading-error.md) — Library loading
-- [`MethodRequirementsError`](method-requirements-error.md) — Method requirements
-- [`MethodRequirementsFileError`](method-requirements-file-error.md) — Method requirements file
-- [`MethodRequirementsNotMetError`](method-requirements-not-met-error.md) — Method requirements not met
-- [`MethodTreeLoadError`](method-tree-load-error.md) — Method tree load
-- [`PipeFuncPackageSetUnstatedError`](pipe-func-package-set-unstated-error.md) — Pipe func package set unstated
-- [`PipeLibraryError`](pipe-library-error.md) — Pipe library
-- [`PipeLoadingError`](pipe-loading-error.md) — Pipe loading
-- [`PipeNotFoundError`](pipe-not-found-error.md) — Pipe not found
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/auto-detected-inputs-file-error.md b/docs/errors/auto-detected-inputs-file-error.md
deleted file mode 100644
index 7ff8c2bca..000000000
--- a/docs/errors/auto-detected-inputs-file-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Auto-detected inputs file is not a regular file"
-description: "Reference for the `AutoDetectedInputsFileError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Auto-detected inputs file is not a regular file
-
-Raised when the inputs file auto-detection finds in a bundle directory is not a regular file.
-
-| Field | Value |
-|---|---|
-| `error_type` | `AutoDetectedInputsFileError` |
-| `title` | Auto-detected inputs file is not a regular file |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/auto-detected-inputs-file-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.cli.commands.run.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-| `user_action` | `change_input` — Replace it with the file itself, or name the inputs file with --inputs <path> |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/aws-credentials-error.md b/docs/errors/aws-credentials-error.md
deleted file mode 100644
index 4cb532c47..000000000
--- a/docs/errors/aws-credentials-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Aws credentials"
-description: "Reference for the `AwsCredentialsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Aws credentials
-
-| Field | Value |
-|---|---|
-| `error_type` | `AwsCredentialsError` |
-| `title` | Aws credentials |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/aws-credentials-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.aws.exceptions` |
-| Parent class | [`CredentialsError`](credentials-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/azure-credentials-error.md b/docs/errors/azure-credentials-error.md
deleted file mode 100644
index c64a54a09..000000000
--- a/docs/errors/azure-credentials-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Azure credentials"
-description: "Reference for the `AzureCredentialsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Azure credentials
-
-| Field | Value |
-|---|---|
-| `error_type` | `AzureCredentialsError` |
-| `title` | Azure credentials |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/azure-credentials-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.azure_rest.azure_exceptions` |
-| Parent class | [`CredentialsError`](credentials-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/batch-params-error.md b/docs/errors/batch-params-error.md
deleted file mode 100644
index 3bca1ffb0..000000000
--- a/docs/errors/batch-params-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Batch params"
-description: "Reference for the `BatchParamsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Batch params
-
-| Field | Value |
-|---|---|
-| `error_type` | `BatchParamsError` |
-| `title` | Batch params |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/batch-params-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_run.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/bedrock-factory-error.md b/docs/errors/bedrock-factory-error.md
deleted file mode 100644
index a7f9661da..000000000
--- a/docs/errors/bedrock-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Bedrock factory"
-description: "Reference for the `BedrockFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Bedrock factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `BedrockFactoryError` |
-| `title` | Bedrock factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/bedrock-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.bedrock.bedrock_exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/bedrock-worker-configuration-error.md b/docs/errors/bedrock-worker-configuration-error.md
deleted file mode 100644
index d4c598f60..000000000
--- a/docs/errors/bedrock-worker-configuration-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Bedrock worker configuration"
-description: "Reference for the `BedrockWorkerConfigurationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Bedrock worker configuration
-
-| Field | Value |
-|---|---|
-| `error_type` | `BedrockWorkerConfigurationError` |
-| `title` | Bedrock worker configuration |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/bedrock-worker-configuration-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.bedrock.bedrock_exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/binding-path-unresolved-error.md b/docs/errors/binding-path-unresolved-error.md
deleted file mode 100644
index 0d61364b5..000000000
--- a/docs/errors/binding-path-unresolved-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Binding path unresolved"
-description: "Reference for the `BindingPathUnresolvedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Binding path unresolved
-
-A binding step's `from` path that cannot be walked before the run: the declared structures do not hold it, or the concept of its root is not known.
-
-| Field | Value |
-|---|---|
-| `error_type` | `BindingPathUnresolvedError` |
-| `title` | Binding path unresolved |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/binding-path-unresolved-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_controllers.binding.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/binding-step-run-error.md b/docs/errors/binding-step-run-error.md
deleted file mode 100644
index 758c3e461..000000000
--- a/docs/errors/binding-step-run-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Binding step run"
-description: "Reference for the `BindingStepRunError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Binding step run
-
-A binding step that could not bind its value at run time, although its path was derived before the run.
-
-| Field | Value |
-|---|---|
-| `error_type` | `BindingStepRunError` |
-| `title` | Binding step run |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/binding-step-run-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_controllers.binding.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/broken-plugin-error.md b/docs/errors/broken-plugin-error.md
deleted file mode 100644
index 3315334be..000000000
--- a/docs/errors/broken-plugin-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Broken plugin"
-description: "Reference for the `BrokenPluginError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Broken plugin
-
-A discovered plugin failed while loading or registering itself.
-
-| Field | Value |
-|---|---|
-| `error_type` | `BrokenPluginError` |
-| `title` | Broken plugin |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/broken-plugin-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/bundle-elaborator-error.md b/docs/errors/bundle-elaborator-error.md
deleted file mode 100644
index f7da26ce4..000000000
--- a/docs/errors/bundle-elaborator-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Bundle elaborator"
-description: "Reference for the `BundleElaboratorError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Bundle elaborator
-
-Raised when bundle elaboration fails (e.g. synthetic-name collision, invalid output for preliminary_text).
-
-| Field | Value |
-|---|---|
-| `error_type` | `BundleElaboratorError` |
-| `title` | Bundle elaborator |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/bundle-elaborator-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.mthds_parsing.exceptions` |
-| Parent class | [`MthdsParserError`](mthds-parser-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/bundle-resource-not-named-error.md b/docs/errors/bundle-resource-not-named-error.md
deleted file mode 100644
index 7bb3c7086..000000000
--- a/docs/errors/bundle-resource-not-named-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Bundle resource not named"
-description: "Reference for the `BundleResourceNotNamedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Bundle resource not named
-
-Raised when a file submitted with a bundle is named by none of its steps.
-
-| Field | Value |
-|---|---|
-| `error_type` | `BundleResourceNotNamedError` |
-| `title` | Bundle resource not named |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/bundle-resource-not-named-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.core.bundle_resources.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-| `retryable` | `false` |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/bundle-resource-path-error.md b/docs/errors/bundle-resource-path-error.md
deleted file mode 100644
index 3936000f1..000000000
--- a/docs/errors/bundle-resource-path-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Bundle resource path"
-description: "Reference for the `BundleResourcePathError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Bundle resource path
-
-Raised when a file submitted with a bundle is keyed by a path that cannot name a file inside the bundle.
-
-| Field | Value |
-|---|---|
-| `error_type` | `BundleResourcePathError` |
-| `title` | Bundle resource path |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/bundle-resource-path-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.core.bundle_resources.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-| `retryable` | `false` |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/codegen-error.md b/docs/errors/codegen-error.md
deleted file mode 100644
index f930e5459..000000000
--- a/docs/errors/codegen-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Codegen error"
-description: "Reference for the `CodegenError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Codegen error
-
-Base error for the codegen projection engine (stamps, lock, check, emission).
-
-| Field | Value |
-|---|---|
-| `error_type` | `CodegenError` |
-| `title` | Codegen error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/codegen-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.codegen.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/codegen-lock-error.md b/docs/errors/codegen-lock-error.md
deleted file mode 100644
index 49398134c..000000000
--- a/docs/errors/codegen-lock-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Codegen lock error"
-description: "Reference for the `CodegenLockError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Codegen lock error
-
-Raised when a `codegen.lock` cannot be read or parsed.
-
-| Field | Value |
-|---|---|
-| `error_type` | `CodegenLockError` |
-| `title` | Codegen lock error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/codegen-lock-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.codegen.exceptions` |
-| Parent class | [`CodegenError`](codegen-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/codegen-stamp-error.md b/docs/errors/codegen-stamp-error.md
deleted file mode 100644
index 20d1b5d92..000000000
--- a/docs/errors/codegen-stamp-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Codegen stamp error"
-description: "Reference for the `CodegenStampError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Codegen stamp error
-
-Raised when a generated file cannot be stamped (e.g. an unstampable file type).
-
-| Field | Value |
-|---|---|
-| `error_type` | `CodegenStampError` |
-| `title` | Codegen stamp error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/codegen-stamp-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.codegen.exceptions` |
-| Parent class | [`CodegenError`](codegen-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/cogt-error.md b/docs/errors/cogt-error.md
deleted file mode 100644
index 34d11f58f..000000000
--- a/docs/errors/cogt-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "AI inference failed"
-description: "Reference for the `CogtError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# AI inference failed
-
-| Field | Value |
-|---|---|
-| `error_type` | `CogtError` |
-| `title` | AI inference failed |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/cogt-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/concept-code-error.md b/docs/errors/concept-code-error.md
deleted file mode 100644
index 69aa80d66..000000000
--- a/docs/errors/concept-code-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Concept code"
-description: "Reference for the `ConceptCodeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Concept code
-
-| Field | Value |
-|---|---|
-| `error_type` | `ConceptCodeError` |
-| `title` | Concept code |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/concept-code-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.concepts.exceptions` |
-| Parent class | [`ConceptError`](concept-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/concept-error.md b/docs/errors/concept-error.md
deleted file mode 100644
index 5ca3c5037..000000000
--- a/docs/errors/concept-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Concept error"
-description: "Reference for the `ConceptError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Concept error
-
-| Field | Value |
-|---|---|
-| `error_type` | `ConceptError` |
-| `title` | Concept error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/concept-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.concepts.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/concept-factory-error.md b/docs/errors/concept-factory-error.md
deleted file mode 100644
index 83c9d7b4e..000000000
--- a/docs/errors/concept-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Concept factory"
-description: "Reference for the `ConceptFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Concept factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `ConceptFactoryError` |
-| `title` | Concept factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/concept-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.concepts.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/concept-library-concept-not-found-error.md b/docs/errors/concept-library-concept-not-found-error.md
deleted file mode 100644
index 4dbd77d7a..000000000
--- a/docs/errors/concept-library-concept-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Concept library concept not found"
-description: "Reference for the `ConceptLibraryConceptNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Concept library concept not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `ConceptLibraryConceptNotFoundError` |
-| `title` | Concept library concept not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/concept-library-concept-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.concepts.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/concept-library-error.md b/docs/errors/concept-library-error.md
deleted file mode 100644
index cee0ad2b2..000000000
--- a/docs/errors/concept-library-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Concept library"
-description: "Reference for the `ConceptLibraryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Concept library
-
-A concept-library failure (unresolved / duplicate / invalid concept reference).
-
-| Field | Value |
-|---|---|
-| `error_type` | `ConceptLibraryError` |
-| `title` | Concept library |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/concept-library-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.libraries.concept.exceptions` |
-| Parent class | [`LibraryLoadingError`](library-loading-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/concept-loading-error.md b/docs/errors/concept-loading-error.md
deleted file mode 100644
index f11ce00d4..000000000
--- a/docs/errors/concept-loading-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Concept loading"
-description: "Reference for the `ConceptLoadingError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Concept loading
-
-| Field | Value |
-|---|---|
-| `error_type` | `ConceptLoadingError` |
-| `title` | Concept loading |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/concept-loading-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.libraries.exceptions` |
-| Parent class | [`LibraryLoadingError`](library-loading-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/concept-ref-ambiguous-error.md b/docs/errors/concept-ref-ambiguous-error.md
deleted file mode 100644
index 5e64cc1e6..000000000
--- a/docs/errors/concept-ref-ambiguous-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Concept ref ambiguous"
-description: "Reference for the `ConceptRefAmbiguousError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Concept ref ambiguous
-
-A bare `<domain>.<Code>` ref matches more than one concept the provider holds.
-
-| Field | Value |
-|---|---|
-| `error_type` | `ConceptRefAmbiguousError` |
-| `title` | Concept ref ambiguous |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/concept-ref-ambiguous-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.concepts.exceptions` |
-| Parent class | [`ConceptError`](concept-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/concept-refine-error.md b/docs/errors/concept-refine-error.md
deleted file mode 100644
index ac2183ab5..000000000
--- a/docs/errors/concept-refine-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Concept refine"
-description: "Reference for the `ConceptRefineError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Concept refine
-
-| Field | Value |
-|---|---|
-| `error_type` | `ConceptRefineError` |
-| `title` | Concept refine |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/concept-refine-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.concepts.exceptions` |
-| Parent class | [`ConceptError`](concept-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/concept-spec-error.md b/docs/errors/concept-spec-error.md
deleted file mode 100644
index 604a554d7..000000000
--- a/docs/errors/concept-spec-error.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-title: "Concept spec (removed)"
-description: "The `ConceptSpecError` Pipelex error class no longer exists."
----
-
-<!-- pipelex:authored -->
-
-# Concept spec (removed)
-
-**`ConceptSpecError` is no longer raised.** It reported a malformed concept spec, the JSON authoring format that `pipelex-agent concept` and the `POST /v1/build/concept` route converted into MTHDS TOML. The command, the route and the concept spec are all gone: a concept is written in MTHDS directly, in a `[concept.<Code>]` section, and checked with `pipelex validate bundle` or [`POST /v1/validate`](../api-server/pipe-validate.md).
-
-This page stays at the URL the error's `type_uri` published, so a link recorded from an earlier response still resolves.
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/concept-string-error.md b/docs/errors/concept-string-error.md
deleted file mode 100644
index 281025219..000000000
--- a/docs/errors/concept-string-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Concept string"
-description: "Reference for the `ConceptStringError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Concept string
-
-| Field | Value |
-|---|---|
-| `error_type` | `ConceptStringError` |
-| `title` | Concept string |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/concept-string-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.concepts.exceptions` |
-| Parent class | [`ConceptError`](concept-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/concept-structure-generator-error.md b/docs/errors/concept-structure-generator-error.md
deleted file mode 100644
index 6675e5227..000000000
--- a/docs/errors/concept-structure-generator-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Concept structure generator"
-description: "Reference for the `ConceptStructureGeneratorError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Concept structure generator
-
-| Field | Value |
-|---|---|
-| `error_type` | `ConceptStructureGeneratorError` |
-| `title` | Concept structure generator |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/concept-structure-generator-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.concepts.structure_generation.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/concept-structure-validation-error.md b/docs/errors/concept-structure-validation-error.md
deleted file mode 100644
index 2a7277788..000000000
--- a/docs/errors/concept-structure-validation-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Concept structure validation"
-description: "Reference for the `ConceptStructureValidationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Concept structure validation
-
-| Field | Value |
-|---|---|
-| `error_type` | `ConceptStructureValidationError` |
-| `title` | Concept structure validation |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/concept-structure-validation-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.concepts.structure_generation.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/config-validation-error.md b/docs/errors/config-validation-error.md
deleted file mode 100644
index 57ac73039..000000000
--- a/docs/errors/config-validation-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Config validation"
-description: "Reference for the `ConfigValidationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Config validation
-
-| Field | Value |
-|---|---|
-| `error_type` | `ConfigValidationError` |
-| `title` | Config validation |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/config-validation-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.system.exceptions` |
-| Parent class | [`FatalError`](fatal-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/construct-field-blueprint-type-error.md b/docs/errors/construct-field-blueprint-type-error.md
deleted file mode 100644
index fe7ec0f67..000000000
--- a/docs/errors/construct-field-blueprint-type-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Construct field blueprint type"
-description: "Reference for the `ConstructFieldBlueprintTypeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Construct field blueprint type
-
-| Field | Value |
-|---|---|
-| `error_type` | `ConstructFieldBlueprintTypeError` |
-| `title` | Construct field blueprint type |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/construct-field-blueprint-type-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.compose.exceptions` |
-| Parent class | [`PipeComposeError`](pipe-compose-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/construct-field-blueprint-value-error.md b/docs/errors/construct-field-blueprint-value-error.md
deleted file mode 100644
index 019bfd70b..000000000
--- a/docs/errors/construct-field-blueprint-value-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Construct field blueprint value"
-description: "Reference for the `ConstructFieldBlueprintValueError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Construct field blueprint value
-
-| Field | Value |
-|---|---|
-| `error_type` | `ConstructFieldBlueprintValueError` |
-| `title` | Construct field blueprint value |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/construct-field-blueprint-value-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.compose.exceptions` |
-| Parent class | [`PipeComposeError`](pipe-compose-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/context-provider-error.md b/docs/errors/context-provider-error.md
deleted file mode 100644
index ac2e9b48e..000000000
--- a/docs/errors/context-provider-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Context provider"
-description: "Reference for the `ContextProviderError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Context provider
-
-| Field | Value |
-|---|---|
-| `error_type` | `ContextProviderError` |
-| `title` | Context provider |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/context-provider-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.misc.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/core-unconditional-plugin-disabled-error.md b/docs/errors/core-unconditional-plugin-disabled-error.md
deleted file mode 100644
index 752ae2c50..000000000
--- a/docs/errors/core-unconditional-plugin-disabled-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Core unconditional plugin disabled"
-description: "Reference for the `CoreUnconditionalPluginDisabledError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Core unconditional plugin disabled
-
-A plugin that core requires unconditionally was named in ``runtime.plugins.disabled``.
-
-| Field | Value |
-|---|---|
-| `error_type` | `CoreUnconditionalPluginDisabledError` |
-| `title` | Core unconditional plugin disabled |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/core-unconditional-plugin-disabled-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/cost-registry-error.md b/docs/errors/cost-registry-error.md
deleted file mode 100644
index 56a083125..000000000
--- a/docs/errors/cost-registry-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Cost registry"
-description: "Reference for the `CostRegistryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Cost registry
-
-| Field | Value |
-|---|---|
-| `error_type` | `CostRegistryError` |
-| `title` | Cost registry |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/cost-registry-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/crate-normalization-error.md b/docs/errors/crate-normalization-error.md
deleted file mode 100644
index b67919791..000000000
--- a/docs/errors/crate-normalization-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Crate normalization error"
-description: "Reference for the `CrateNormalizationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Crate normalization error
-
-Raised when a library crate cannot be normalized (e.g. a non-domain-qualified key, or a pipe ref matching no crate pipe, or several).
-
-| Field | Value |
-|---|---|
-| `error_type` | `CrateNormalizationError` |
-| `title` | Crate normalization error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/crate-normalization-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.libraries.exceptions` |
-| Parent class | [`LibraryError`](library-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/credentials-error.md b/docs/errors/credentials-error.md
deleted file mode 100644
index e24807ddd..000000000
--- a/docs/errors/credentials-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Missing or invalid credentials"
-description: "Reference for the `CredentialsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Missing or invalid credentials
-
-| Field | Value |
-|---|---|
-| `error_type` | `CredentialsError` |
-| `title` | Missing or invalid credentials |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/credentials-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.system.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/csv-coercion-error.md b/docs/errors/csv-coercion-error.md
deleted file mode 100644
index 2113041a3..000000000
--- a/docs/errors/csv-coercion-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "CSV coercion error"
-description: "Reference for the `CsvCoercionError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# CSV coercion error
-
-Raised when a CSV cell value cannot be coerced to its declared field type.
-
-| Field | Value |
-|---|---|
-| `error_type` | `CsvCoercionError` |
-| `title` | CSV coercion error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/csv-coercion-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.tabular.exceptions` |
-| Parent class | [`CsvError`](csv-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/csv-column-error.md b/docs/errors/csv-column-error.md
deleted file mode 100644
index e7906c341..000000000
--- a/docs/errors/csv-column-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "CSV column error"
-description: "Reference for the `CsvColumnError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# CSV column error
-
-Raised when CSV headers do not line up with the row concept's fields.
-
-| Field | Value |
-|---|---|
-| `error_type` | `CsvColumnError` |
-| `title` | CSV column error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/csv-column-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.tabular.exceptions` |
-| Parent class | [`CsvError`](csv-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/csv-error.md b/docs/errors/csv-error.md
deleted file mode 100644
index 298577d4f..000000000
--- a/docs/errors/csv-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "CSV error"
-description: "Reference for the `CsvError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# CSV error
-
-Base for CSV codec errors.
-
-| Field | Value |
-|---|---|
-| `error_type` | `CsvError` |
-| `title` | CSV error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/csv-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.tools.tabular.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/csv-flatness-error.md b/docs/errors/csv-flatness-error.md
deleted file mode 100644
index 9a03f4113..000000000
--- a/docs/errors/csv-flatness-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "CSV flatness error"
-description: "Reference for the `CsvFlatnessError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# CSV flatness error
-
-Raised when a concept used with CSV is not flat.
-
-| Field | Value |
-|---|---|
-| `error_type` | `CsvFlatnessError` |
-| `title` | CSV flatness error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/csv-flatness-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.tabular.exceptions` |
-| Parent class | [`CsvError`](csv-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/csv-read-error.md b/docs/errors/csv-read-error.md
deleted file mode 100644
index e296ca414..000000000
--- a/docs/errors/csv-read-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "CSV read error"
-description: "Reference for the `CsvReadError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# CSV read error
-
-Raised when a CSV file cannot be opened, decoded, or parsed.
-
-| Field | Value |
-|---|---|
-| `error_type` | `CsvReadError` |
-| `title` | CSV read error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/csv-read-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.tabular.exceptions` |
-| Parent class | [`CsvError`](csv-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/date-content-error.md b/docs/errors/date-content-error.md
deleted file mode 100644
index 2f0abb959..000000000
--- a/docs/errors/date-content-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Date content"
-description: "Reference for the `DateContentError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Date content
-
-Raised when a DateContent operation needs a time of day the value does not carry.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DateContentError` |
-| `title` | Date content |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/date-content-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.stuffs.exceptions` |
-| Parent class | [`StuffError`](stuff-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/delivery-error.md b/docs/errors/delivery-error.md
deleted file mode 100644
index 997302403..000000000
--- a/docs/errors/delivery-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Delivery"
-description: "Reference for the `DeliveryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Delivery
-
-| Field | Value |
-|---|---|
-| `error_type` | `DeliveryError` |
-| `title` | Delivery |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/delivery-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_run.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/doc-gen-engine-missing-error.md b/docs/errors/doc-gen-engine-missing-error.md
deleted file mode 100644
index 040d52ae9..000000000
--- a/docs/errors/doc-gen-engine-missing-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Doc gen engine missing"
-description: "Reference for the `DocGenEngineMissingError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Doc gen engine missing
-
-The document engine a `PipeDocGen` step prints with is not available in this runtime.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DocGenEngineMissingError` |
-| `title` | Doc gen engine missing |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/doc-gen-engine-missing-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.cogt.doc_gen.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/doc-gen-handle-not-found-error.md b/docs/errors/doc-gen-handle-not-found-error.md
deleted file mode 100644
index 4751acdc8..000000000
--- a/docs/errors/doc-gen-handle-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Doc gen handle not found"
-description: "Reference for the `DocGenHandleNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Doc gen handle not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `DocGenHandleNotFoundError` |
-| `title` | Doc gen handle not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/doc-gen-handle-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/doc-gen-model-capability-error.md b/docs/errors/doc-gen-model-capability-error.md
deleted file mode 100644
index c6a49b91b..000000000
--- a/docs/errors/doc-gen-model-capability-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Doc gen model capability"
-description: "Reference for the `DocGenModelCapabilityError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Doc gen model capability
-
-The document engine a `PipeDocGen` step names does not print the step's format from its source.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DocGenModelCapabilityError` |
-| `title` | Doc gen model capability |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/doc-gen-model-capability-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.cogt.doc_gen.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/doc-gen-render-error.md b/docs/errors/doc-gen-render-error.md
deleted file mode 100644
index 066b68cc7..000000000
--- a/docs/errors/doc-gen-render-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Doc gen render"
-description: "Reference for the `DocGenRenderError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Doc gen render
-
-A document engine could not print a render job.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DocGenRenderError` |
-| `title` | Doc gen render |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/doc-gen-render-error/` |
-| `error_domain` | `runtime` |
-| Defined in | `pipelex.cogt.doc_gen.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/domain-code-error.md b/docs/errors/domain-code-error.md
deleted file mode 100644
index 5af8848ff..000000000
--- a/docs/errors/domain-code-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Domain code"
-description: "Reference for the `DomainCodeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Domain code
-
-| Field | Value |
-|---|---|
-| `error_type` | `DomainCodeError` |
-| `title` | Domain code |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/domain-code-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.domains.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/domain-factory-error.md b/docs/errors/domain-factory-error.md
deleted file mode 100644
index 14a94996d..000000000
--- a/docs/errors/domain-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Domain factory"
-description: "Reference for the `DomainFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Domain factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `DomainFactoryError` |
-| `title` | Domain factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/domain-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.domains.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/domain-library-error.md b/docs/errors/domain-library-error.md
deleted file mode 100644
index e83021f5f..000000000
--- a/docs/errors/domain-library-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Domain library"
-description: "Reference for the `DomainLibraryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Domain library
-
-| Field | Value |
-|---|---|
-| `error_type` | `DomainLibraryError` |
-| `title` | Domain library |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/domain-library-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.libraries.domain.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/domain-loading-error.md b/docs/errors/domain-loading-error.md
deleted file mode 100644
index 606d7012d..000000000
--- a/docs/errors/domain-loading-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Domain loading"
-description: "Reference for the `DomainLoadingError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Domain loading
-
-| Field | Value |
-|---|---|
-| `error_type` | `DomainLoadingError` |
-| `title` | Domain loading |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/domain-loading-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.libraries.exceptions` |
-| Parent class | [`LibraryLoadingError`](library-loading-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/drift-ack-error.md b/docs/errors/drift-ack-error.md
deleted file mode 100644
index b46806857..000000000
--- a/docs/errors/drift-ack-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Drift ack"
-description: "Reference for the `DriftAckError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Drift ack
-
-Raised when an ack file is invalid or an ack operation cannot proceed.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DriftAckError` |
-| `title` | Drift ack |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/drift-ack-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cli.dev_cli.commands.drift.exceptions` |
-| Parent class | [`DriftError`](drift-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/drift-error.md b/docs/errors/drift-error.md
deleted file mode 100644
index c9556820a..000000000
--- a/docs/errors/drift-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Drift"
-description: "Reference for the `DriftError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Drift
-
-Base error for the drift-contracts tooling.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DriftError` |
-| `title` | Drift |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/drift-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cli.dev_cli.commands.drift.exceptions` |
-| Parent class | [`PipelexCLIError`](pipelex-cli-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/drift-git-error.md b/docs/errors/drift-git-error.md
deleted file mode 100644
index 8fe442498..000000000
--- a/docs/errors/drift-git-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Drift git"
-description: "Reference for the `DriftGitError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Drift git
-
-Raised when a git plumbing call needed by drift fails.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DriftGitError` |
-| `title` | Drift git |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/drift-git-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cli.dev_cli.commands.drift.exceptions` |
-| Parent class | [`DriftError`](drift-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/drift-manifest-error.md b/docs/errors/drift-manifest-error.md
deleted file mode 100644
index 2f763409e..000000000
--- a/docs/errors/drift-manifest-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Drift manifest"
-description: "Reference for the `DriftManifestError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Drift manifest
-
-Raised when drift.toml is missing, unparseable, or schema-invalid.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DriftManifestError` |
-| `title` | Drift manifest |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/drift-manifest-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cli.dev_cli.commands.drift.exceptions` |
-| Parent class | [`DriftError`](drift-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/dry-run-error.md b/docs/errors/dry-run-error.md
deleted file mode 100644
index 239101b17..000000000
--- a/docs/errors/dry-run-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Dry run"
-description: "Reference for the `DryRunError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Dry run
-
-Raised when a dry run fails. The validation sweep raises it with one failure per pipe whose dry run failed, located at the innermost failing pipe that is not allowed to fail, so a controller that failed because a pipe it runs failed is reported once, at that pipe. Bundle validation reports each failure as its own ``dry_run`` item, with the error type ``DryRunError``, the pipe's code, domain and source, and a message that keeps the failure's own text only when that text is caller-facing and otherwise names the failure's title.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DryRunError` |
-| `title` | Dry run |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/dry-run-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_run.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/dry-run-graph-not-produced-error.md b/docs/errors/dry-run-graph-not-produced-error.md
deleted file mode 100644
index c98acafea..000000000
--- a/docs/errors/dry-run-graph-not-produced-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Dry run graph not produced"
-description: "Reference for the `DryRunGraphNotProducedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Dry run graph not produced
-
-Raised when a graph-producing dry run completes but no ``GraphSpec`` was assembled onto the pipe output.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DryRunGraphNotProducedError` |
-| `title` | Dry run graph not produced |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/dry-run-graph-not-produced-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_run.exceptions` |
-| Parent class | [`DryRunError`](dry-run-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/dry-run-mock-build-error.md b/docs/errors/dry-run-mock-build-error.md
deleted file mode 100644
index 0a5f5e700..000000000
--- a/docs/errors/dry-run-mock-build-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Dry run mock build"
-description: "Reference for the `DryRunMockBuildError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Dry run mock build
-
-Raised when building a leaf mock object fails (polyfactory build or model validation).
-
-| Field | Value |
-|---|---|
-| `error_type` | `DryRunMockBuildError` |
-| `title` | Dry run mock build |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/dry-run-mock-build-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.cogt.content_generation.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/dry-run-object-fidelity-error.md b/docs/errors/dry-run-object-fidelity-error.md
deleted file mode 100644
index 1e8e3445e..000000000
--- a/docs/errors/dry-run-object-fidelity-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Dry run object fidelity"
-description: "Reference for the `DryRunObjectFidelityError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Dry run object fidelity
-
-Raised when a dry-run synthetic object fails re-validation against its original class.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DryRunObjectFidelityError` |
-| `title` | Dry run object fidelity |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/dry-run-object-fidelity-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.cogt.content_generation.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/duplicate-bundle-validator-error.md b/docs/errors/duplicate-bundle-validator-error.md
deleted file mode 100644
index 1c983d7d9..000000000
--- a/docs/errors/duplicate-bundle-validator-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Duplicate bundle validator"
-description: "Reference for the `DuplicateBundleValidatorError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Duplicate bundle validator
-
-Two plugins registered a bundle validator for the same orchestration mode.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DuplicateBundleValidatorError` |
-| `title` | Duplicate bundle validator |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-bundle-validator-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/duplicate-doc-gen-default-error.md b/docs/errors/duplicate-doc-gen-default-error.md
deleted file mode 100644
index 9cc661476..000000000
--- a/docs/errors/duplicate-doc-gen-default-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Duplicate doc gen default"
-description: "Reference for the `DuplicateDocGenDefaultError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Duplicate doc gen default
-
-Two plugins declared the model deck's default document engine for the same format and source.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DuplicateDocGenDefaultError` |
-| `title` | Duplicate doc gen default |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-doc-gen-default-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/duplicate-http-error-mapper-error.md b/docs/errors/duplicate-http-error-mapper-error.md
deleted file mode 100644
index af5c7d472..000000000
--- a/docs/errors/duplicate-http-error-mapper-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Duplicate http error mapper"
-description: "Reference for the `DuplicateHttpErrorMapperError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Duplicate http error mapper
-
-Two plugins registered an HTTP-error mapper for the same exception type.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DuplicateHttpErrorMapperError` |
-| `title` | Duplicate http error mapper |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-http-error-mapper-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/duplicate-inference-backend-error.md b/docs/errors/duplicate-inference-backend-error.md
deleted file mode 100644
index f38b88ccd..000000000
--- a/docs/errors/duplicate-inference-backend-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Duplicate inference backend"
-description: "Reference for the `DuplicateInferenceBackendError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Duplicate inference backend
-
-Two plugins registered an inference backend for the same (family, sdk).
-
-| Field | Value |
-|---|---|
-| `error_type` | `DuplicateInferenceBackendError` |
-| `title` | Duplicate inference backend |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-inference-backend-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/duplicate-internal-model-error.md b/docs/errors/duplicate-internal-model-error.md
deleted file mode 100644
index 2c3e22b20..000000000
--- a/docs/errors/duplicate-internal-model-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Duplicate internal model"
-description: "Reference for the `DuplicateInternalModelError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Duplicate internal model
-
-Two plugins declared a model of the same name and model type in the internal backend.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DuplicateInternalModelError` |
-| `title` | Duplicate internal model |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-internal-model-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/duplicate-log-sink-error.md b/docs/errors/duplicate-log-sink-error.md
deleted file mode 100644
index 689f85ab8..000000000
--- a/docs/errors/duplicate-log-sink-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Duplicate log sink"
-description: "Reference for the `DuplicateLogSinkError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Duplicate log sink
-
-Two plugins registered a log sink for the same method.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DuplicateLogSinkError` |
-| `title` | Duplicate log sink |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-log-sink-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/duplicate-model-lister-error.md b/docs/errors/duplicate-model-lister-error.md
deleted file mode 100644
index 2ffdbc7e0..000000000
--- a/docs/errors/duplicate-model-lister-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Duplicate model lister"
-description: "Reference for the `DuplicateModelListerError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Duplicate model lister
-
-Two plugins registered a model lister for the same sdk.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DuplicateModelListerError` |
-| `title` | Duplicate model lister |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-model-lister-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/duplicate-orchestrator-error.md b/docs/errors/duplicate-orchestrator-error.md
deleted file mode 100644
index 8d86f62eb..000000000
--- a/docs/errors/duplicate-orchestrator-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Duplicate orchestrator"
-description: "Reference for the `DuplicateOrchestratorError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Duplicate orchestrator
-
-Two plugins registered an orchestrator for the same orchestration mode.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DuplicateOrchestratorError` |
-| `title` | Duplicate orchestrator |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-orchestrator-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/duplicate-pipe-func-executor-error.md b/docs/errors/duplicate-pipe-func-executor-error.md
deleted file mode 100644
index d95b9caf9..000000000
--- a/docs/errors/duplicate-pipe-func-executor-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Duplicate pipe func executor"
-description: "Reference for the `DuplicatePipeFuncExecutorError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Duplicate pipe func executor
-
-Two plugins registered a PipeFunc executor for the same execution mode.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DuplicatePipeFuncExecutorError` |
-| `title` | Duplicate pipe func executor |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-pipe-func-executor-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/duplicate-pipe-func-package-offer-error.md b/docs/errors/duplicate-pipe-func-package-offer-error.md
deleted file mode 100644
index 4fa8efa5c..000000000
--- a/docs/errors/duplicate-pipe-func-package-offer-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Duplicate pipe func package offer"
-description: "Reference for the `DuplicatePipeFuncPackageOfferError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Duplicate pipe func package offer
-
-Two plugins stated the package offer of the same PipeFunc execution mode.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DuplicatePipeFuncPackageOfferError` |
-| `title` | Duplicate pipe func package offer |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-pipe-func-package-offer-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/duplicate-secrets-provider-error.md b/docs/errors/duplicate-secrets-provider-error.md
deleted file mode 100644
index ca444a02b..000000000
--- a/docs/errors/duplicate-secrets-provider-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Duplicate secrets provider"
-description: "Reference for the `DuplicateSecretsProviderError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Duplicate secrets provider
-
-Two plugins registered a secrets provider for the same method.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DuplicateSecretsProviderError` |
-| `title` | Duplicate secrets provider |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-secrets-provider-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/duplicate-service-error-code-error.md b/docs/errors/duplicate-service-error-code-error.md
deleted file mode 100644
index 74b08ec91..000000000
--- a/docs/errors/duplicate-service-error-code-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Duplicate service error code"
-description: "Reference for the `DuplicateServiceErrorCodeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Duplicate service error code
-
-Two plugins contributed the same service error code.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DuplicateServiceErrorCodeError` |
-| `title` | Duplicate service error code |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-service-error-code-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/duplicate-storage-provider-error.md b/docs/errors/duplicate-storage-provider-error.md
deleted file mode 100644
index 11cd5a477..000000000
--- a/docs/errors/duplicate-storage-provider-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Duplicate storage provider"
-description: "Reference for the `DuplicateStorageProviderError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Duplicate storage provider
-
-Two plugins registered a storage provider for the same method.
-
-| Field | Value |
-|---|---|
-| `error_type` | `DuplicateStorageProviderError` |
-| `title` | Duplicate storage provider |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-storage-provider-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/empty-method-tree-error.md b/docs/errors/empty-method-tree-error.md
deleted file mode 100644
index 538ae6b82..000000000
--- a/docs/errors/empty-method-tree-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Empty method tree"
-description: "Reference for the `EmptyMethodTreeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Empty method tree
-
-Raised when a folder handed over as a method holds no bundle.
-
-| Field | Value |
-|---|---|
-| `error_type` | `EmptyMethodTreeError` |
-| `title` | Empty method tree |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/empty-method-tree-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.libraries.exceptions` |
-| Parent class | [`MethodTreeLoadError`](method-tree-load-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/entry-pipe-ambiguous-error.md b/docs/errors/entry-pipe-ambiguous-error.md
deleted file mode 100644
index 234e0cdec..000000000
--- a/docs/errors/entry-pipe-ambiguous-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Entry pipe ambiguous"
-description: "Reference for the `EntryPipeAmbiguousError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Entry pipe ambiguous
-
-An entry-shaped bare `pipe_code` matched pipes in several domains.
-
-| Field | Value |
-|---|---|
-| `error_type` | `EntryPipeAmbiguousError` |
-| `title` | Entry pipe ambiguous |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/entry-pipe-ambiguous-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.libraries.pipe.exceptions` |
-| Parent class | [`PipeLibraryError`](pipe-library-error.md) |
-| `user_action` | `change_input` — Name one candidate explicitly: 'domain.pipe_code', or 'alias->domain.pipe_code' for a cross-package code. |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/entry-pipe-not-found-error.md b/docs/errors/entry-pipe-not-found-error.md
deleted file mode 100644
index 7cc8cadf4..000000000
--- a/docs/errors/entry-pipe-not-found-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Entry pipe not found"
-description: "Reference for the `EntryPipeNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Entry pipe not found
-
-An entry-shaped `pipe_code` — one a human typed — resolved to no pipe.
-
-| Field | Value |
-|---|---|
-| `error_type` | `EntryPipeNotFoundError` |
-| `title` | Entry pipe not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/entry-pipe-not-found-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.libraries.pipe.exceptions` |
-| Parent class | [`PipeNotFoundError`](pipe-not-found-error.md) |
-| `user_action` | `change_input` — Check the pipe code for typos and make sure the bundle in scope for this operation declares it. |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/env-var-not-found-error.md b/docs/errors/env-var-not-found-error.md
deleted file mode 100644
index c67346669..000000000
--- a/docs/errors/env-var-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Environment variable not set"
-description: "Reference for the `EnvVarNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Environment variable not set
-
-| Field | Value |
-|---|---|
-| `error_type` | `EnvVarNotFoundError` |
-| `title` | Environment variable not set |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/env-var-not-found-error/` |
-| `error_domain` | `config` |
-| Defined in | `pipelex.system.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/event-log-error.md b/docs/errors/event-log-error.md
deleted file mode 100644
index 7fb31b69b..000000000
--- a/docs/errors/event-log-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Event log"
-description: "Reference for the `EventLogError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Event log
-
-Base error for trace-event log backend failures.
-
-| Field | Value |
-|---|---|
-| `error_type` | `EventLogError` |
-| `title` | Event log |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/event-log-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tracing.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/event-log-read-error.md b/docs/errors/event-log-read-error.md
deleted file mode 100644
index 891ce3fd2..000000000
--- a/docs/errors/event-log-read-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Event log read"
-description: "Reference for the `EventLogReadError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Event log read
-
-Raised when reading trace events from the configured backend fails.
-
-| Field | Value |
-|---|---|
-| `error_type` | `EventLogReadError` |
-| `title` | Event log read |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/event-log-read-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tracing.exceptions` |
-| Parent class | [`EventLogError`](event-log-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/event-log-schema-mismatch-error.md b/docs/errors/event-log-schema-mismatch-error.md
deleted file mode 100644
index c1877aa74..000000000
--- a/docs/errors/event-log-schema-mismatch-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Event log schema mismatch"
-description: "Reference for the `EventLogSchemaMismatchError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Event log schema mismatch
-
-Raised when a trace event is well-formed JSON the current models refuse.
-
-| Field | Value |
-|---|---|
-| `error_type` | `EventLogSchemaMismatchError` |
-| `title` | Event log schema mismatch |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/event-log-schema-mismatch-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tracing.exceptions` |
-| Parent class | [`EventLogReadError`](event-log-read-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/event-log-setup-error.md b/docs/errors/event-log-setup-error.md
deleted file mode 100644
index eb5309718..000000000
--- a/docs/errors/event-log-setup-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Event log setup"
-description: "Reference for the `EventLogSetupError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Event log setup
-
-Raised when constructing the configured event-log backend fails.
-
-| Field | Value |
-|---|---|
-| `error_type` | `EventLogSetupError` |
-| `title` | Event log setup |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/event-log-setup-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tracing.exceptions` |
-| Parent class | [`EventLogError`](event-log-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/execution-and-runtime.md b/docs/errors/execution-and-runtime.md
deleted file mode 100644
index 309045385..000000000
--- a/docs/errors/execution-and-runtime.md
+++ /dev/null
@@ -1,63 +0,0 @@
----
-title: "Execution & runtime"
-description: "Pipelex error classes in the Execution & runtime area, grouped by subsystem."
----
-
-<!-- pipelex:generated -->
-
-# Execution & runtime
-
-Each error class below has a stable RFC 7807 `type` URI that dereferences to its
-own page. Classes are grouped by subsystem.
-
-## Pipe execution
-
-- [`AsyncExecutionNotEnabledError`](async-execution-not-enabled-error.md) — Async execution not enabled
-- [`BatchParamsError`](batch-params-error.md) — Batch params
-- [`DeliveryError`](delivery-error.md) — Delivery
-- [`DryRunError`](dry-run-error.md) — Dry run
-- [`DryRunGraphNotProducedError`](dry-run-graph-not-produced-error.md) — Dry run graph not produced
-- [`PipeJobError`](pipe-job-error.md) — Pipe job
-- [`PipeRouterError`](pipe-router-error.md) — Pipe router
-- [`PipeRunParamsError`](pipe-run-params-error.md) — Pipe run params
-- [`StorageDeliveryError`](storage-delivery-error.md) — Storage delivery
-- [`WebhookDeliveryError`](webhook-delivery-error.md) — Webhook delivery
-
-## Pipeline execution
-
-- [`MethodEntryError`](method-entry-error.md) — Method entry
-- [`PipeExecutionError`](pipe-execution-error.md) — Pipe execution
-- [`PipeIOContractError`](pipe-io-contract-error.md) — Pipe IO contract
-- [`PipeStackOverflowError`](pipe-stack-overflow-error.md) — Pipe stack overflow
-- [`PipelineExecutionError`](pipeline-execution-error.md) — Pipeline execution
-- [`PipelineInputContentError`](pipeline-input-content-error.md) — Pipeline input content
-- [`PipelineInputFormatError`](pipeline-input-format-error.md) — Pipeline input format
-- [`PipelineInputFormatUnsupportedError`](pipeline-input-format-unsupported-error.md) — Pipeline input format unsupported
-- [`PipelineInputNotAnImageError`](pipeline-input-not-an-image-error.md) — Pipeline input not an image
-- [`PipelineInputUrlInvalidError`](pipeline-input-url-invalid-error.md) — Pipeline input url invalid
-- [`PipelineInputUrlMissingError`](pipeline-input-url-missing-error.md) — Pipeline input url missing
-- [`PipelineManagerAlreadyExistsError`](pipeline-manager-already-exists-error.md) — Pipeline manager already exists
-- [`PipelineManagerNotFoundError`](pipeline-manager-not-found-error.md) — Pipeline manager not found
-- [`ValidateBundleError`](validate-bundle-error.md) — Validate bundle
-
-## Runtime bridge
-
-- [`MissingBundleValidatorError`](missing-bundle-validator-error.md) — Missing bundle validator
-- [`MissingOrchestratorError`](missing-orchestrator-error.md) — Missing orchestrator
-- [`PipelexBridgeDispatchError`](pipelex-bridge-dispatch-error.md) — Pipelex bridge dispatch
-- [`PipelexRuntimeBridgeError`](pipelex-runtime-bridge-error.md) — Pipelex runtime bridge
-
-## Graph
-
-- [`GraphSpecError`](graph-spec-error.md) — Graph spec
-- [`GraphSpecValidationError`](graph-spec-validation-error.md) — Graph spec validation
-
-## Tracing
-
-- [`EventLogError`](event-log-error.md) — Event log
-- [`EventLogReadError`](event-log-read-error.md) — Event log read
-- [`EventLogSchemaMismatchError`](event-log-schema-mismatch-error.md) — Event log schema mismatch
-- [`EventLogSetupError`](event-log-setup-error.md) — Event log setup
-- [`TraceEventModeError`](trace-event-mode-error.md) — Trace event mode
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/explicit-concept-incompatible-error.md b/docs/errors/explicit-concept-incompatible-error.md
deleted file mode 100644
index 5e59fbe62..000000000
--- a/docs/errors/explicit-concept-incompatible-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Explicit concept incompatible"
-description: "Reference for the `ExplicitConceptIncompatibleError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Explicit concept incompatible
-
-An explicit envelope/object names a concept incompatible with the declared one (D6).
-
-| Field | Value |
-|---|---|
-| `error_type` | `ExplicitConceptIncompatibleError` |
-| `title` | Explicit concept incompatible |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/explicit-concept-incompatible-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`InputShapingError`](input-shaping-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/extract-capability-error.md b/docs/errors/extract-capability-error.md
deleted file mode 100644
index d57048901..000000000
--- a/docs/errors/extract-capability-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Extract capability"
-description: "Reference for the `ExtractCapabilityError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Extract capability
-
-| Field | Value |
-|---|---|
-| `error_type` | `ExtractCapabilityError` |
-| `title` | Extract capability |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/extract-capability-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/extract-handle-not-found-error.md b/docs/errors/extract-handle-not-found-error.md
deleted file mode 100644
index 9b876484f..000000000
--- a/docs/errors/extract-handle-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Extract handle not found"
-description: "Reference for the `ExtractHandleNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Extract handle not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `ExtractHandleNotFoundError` |
-| `title` | Extract handle not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/extract-handle-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/extract-input-error.md b/docs/errors/extract-input-error.md
deleted file mode 100644
index bb6aa06fb..000000000
--- a/docs/errors/extract-input-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Extract input"
-description: "Reference for the `ExtractInputError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Extract input
-
-| Field | Value |
-|---|---|
-| `error_type` | `ExtractInputError` |
-| `title` | Extract input |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/extract-input-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.extract.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/extract-input-format-error.md b/docs/errors/extract-input-format-error.md
deleted file mode 100644
index 2a6f3aa5f..000000000
--- a/docs/errors/extract-input-format-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Extract input format"
-description: "Reference for the `ExtractInputFormatError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Extract input format
-
-The file given to an extraction has a known format that the extract model does not read.
-
-| Field | Value |
-|---|---|
-| `error_type` | `ExtractInputFormatError` |
-| `title` | Extract input format |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/extract-input-format-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/extract-job-failure-error.md b/docs/errors/extract-job-failure-error.md
deleted file mode 100644
index 0f5d79b75..000000000
--- a/docs/errors/extract-job-failure-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Extract job failure"
-description: "Reference for the `ExtractJobFailureError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Extract job failure
-
-| Field | Value |
-|---|---|
-| `error_type` | `ExtractJobFailureError` |
-| `title` | Extract job failure |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/extract-job-failure-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/extract-model-not-found-error.md b/docs/errors/extract-model-not-found-error.md
deleted file mode 100644
index e3d8d9e44..000000000
--- a/docs/errors/extract-model-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Extract model not found"
-description: "Reference for the `ExtractModelNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Extract model not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `ExtractModelNotFoundError` |
-| `title` | Extract model not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/extract-model-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`ModelNotFoundError`](model-not-found-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/extract-output-error.md b/docs/errors/extract-output-error.md
deleted file mode 100644
index 10007c743..000000000
--- a/docs/errors/extract-output-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Extract output"
-description: "Reference for the `ExtractOutputError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Extract output
-
-| Field | Value |
-|---|---|
-| `error_type` | `ExtractOutputError` |
-| `title` | Extract output |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/extract-output-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/fal-credentials-error.md b/docs/errors/fal-credentials-error.md
deleted file mode 100644
index d8ec38e25..000000000
--- a/docs/errors/fal-credentials-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Fal credentials"
-description: "Reference for the `FalCredentialsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Fal credentials
-
-| Field | Value |
-|---|---|
-| `error_type` | `FalCredentialsError` |
-| `title` | Fal credentials |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/fal-credentials-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.img_gen.exceptions` |
-| Parent class | [`CredentialsError`](credentials-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/fatal-error.md b/docs/errors/fatal-error.md
deleted file mode 100644
index 26b74f63e..000000000
--- a/docs/errors/fatal-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Fatal error"
-description: "Reference for the `FatalError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Fatal error
-
-| Field | Value |
-|---|---|
-| `error_type` | `FatalError` |
-| `title` | Fatal error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/fatal-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.system.exceptions` |
-| Parent class | [`TracebackMessageError`](traceback-message-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/file-type-error.md b/docs/errors/file-type-error.md
deleted file mode 100644
index 27bb320dd..000000000
--- a/docs/errors/file-type-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "File type"
-description: "Reference for the `FileTypeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# File type
-
-| Field | Value |
-|---|---|
-| `error_type` | `FileTypeError` |
-| `title` | File type |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/file-type-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.misc.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/fix-transaction-error.md b/docs/errors/fix-transaction-error.md
deleted file mode 100644
index 8de889624..000000000
--- a/docs/errors/fix-transaction-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Fix transaction"
-description: "Reference for the `FixTransactionError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Fix transaction
-
-A multi-file commit failed and could not be fully rolled back.
-
-| Field | Value |
-|---|---|
-| `error_type` | `FixTransactionError` |
-| `title` | Fix transaction |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/fix-transaction-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.fix_ops.exceptions` |
-| Parent class | [`PipelexUnexpectedError`](pipelex-unexpected-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/fix-write-conflict-error.md b/docs/errors/fix-write-conflict-error.md
deleted file mode 100644
index c6e116126..000000000
--- a/docs/errors/fix-write-conflict-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Fix write conflict"
-description: "Reference for the `FixWriteConflictError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Fix write conflict
-
-A file changed after a fix or a migration read it but before the atomic commit.
-
-| Field | Value |
-|---|---|
-| `error_type` | `FixWriteConflictError` |
-| `title` | Fix write conflict |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/fix-write-conflict-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.fix_ops.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/former-release-config-error.md b/docs/errors/former-release-config-error.md
deleted file mode 100644
index 99974aa08..000000000
--- a/docs/errors/former-release-config-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Configuration left by a former release"
-description: "Reference for the `FormerReleaseConfigError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Configuration left by a former release
-
-The inference configuration still carries what a former release wrote for the Pipelex Gateway.
-
-| Field | Value |
-|---|---|
-| `error_type` | `FormerReleaseConfigError` |
-| `title` | Configuration left by a former release |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/former-release-config-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.migration.exceptions` |
-| Parent class | [`PipelexSetupError`](pipelex-setup-error.md) |
-| `user_action` | `unknown` — Run 'pipelex migrate' to remove what the former release left; it keeps a copy of each file it changes or removes. From an agent, run 'pipelex-agent migrate --dry-run --format json' to see what the cleanup would remove (its 'former_release' key), show the user, then run 'pipelex-agent migrate --yes'. |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/function-names-migration-error.md b/docs/errors/function-names-migration-error.md
deleted file mode 100644
index be617c4f9..000000000
--- a/docs/errors/function-names-migration-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Function names migration error"
-description: "Reference for the `FunctionNamesMigrationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Function names migration error
-
-The function names of a method could not be migrated to import paths.
-
-| Field | Value |
-|---|---|
-| `error_type` | `FunctionNamesMigrationError` |
-| `title` | Function names migration error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/function-names-migration-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.migration.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-| `retryable` | `false` |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/gcp-log-sink-credentials-error.md b/docs/errors/gcp-log-sink-credentials-error.md
deleted file mode 100644
index 518a4fe3d..000000000
--- a/docs/errors/gcp-log-sink-credentials-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Log sink credentials missing or refused"
-description: "Reference for the `GcpLogSinkCredentialsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Log sink credentials missing or refused
-
-Raised at boot when the ``gcp`` log sink's credentials cannot be found or are refused when refreshed.
-
-| Field | Value |
-|---|---|
-| `error_type` | `GcpLogSinkCredentialsError` |
-| `title` | Log sink credentials missing or refused |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/gcp-log-sink-credentials-error/` |
-| `error_domain` | `config` |
-| Defined in | `pipelex.tools.log.exceptions` |
-| Parent class | [`CredentialsError`](credentials-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/generated-image-error.md b/docs/errors/generated-image-error.md
deleted file mode 100644
index bf9d38cbc..000000000
--- a/docs/errors/generated-image-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Generated image"
-description: "Reference for the `GeneratedImageError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Generated image
-
-| Field | Value |
-|---|---|
-| `error_type` | `GeneratedImageError` |
-| `title` | Generated image |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/generated-image-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/google-img-gen-worker-error.md b/docs/errors/google-img-gen-worker-error.md
deleted file mode 100644
index ead0ef2ac..000000000
--- a/docs/errors/google-img-gen-worker-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Google img gen worker"
-description: "Reference for the `GoogleImgGenWorkerError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Google img gen worker
-
-Base exception for Google Image Generation Worker errors.
-
-| Field | Value |
-|---|---|
-| `error_type` | `GoogleImgGenWorkerError` |
-| `title` | Google img gen worker |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/google-img-gen-worker-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.google.google_exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/google-llm-worker-error.md b/docs/errors/google-llm-worker-error.md
deleted file mode 100644
index bb70ba6ca..000000000
--- a/docs/errors/google-llm-worker-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Google LLM worker"
-description: "Reference for the `GoogleLLMWorkerError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Google LLM worker
-
-Base exception for Google LLM Worker errors.
-
-| Field | Value |
-|---|---|
-| `error_type` | `GoogleLLMWorkerError` |
-| `title` | Google LLM worker |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/google-llm-worker-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.google.google_exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/graph-spec-error.md b/docs/errors/graph-spec-error.md
deleted file mode 100644
index a540c1f88..000000000
--- a/docs/errors/graph-spec-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Graph spec"
-description: "Reference for the `GraphSpecError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Graph spec
-
-Base exception for GraphSpec-related errors.
-
-| Field | Value |
-|---|---|
-| `error_type` | `GraphSpecError` |
-| `title` | Graph spec |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/graph-spec-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.graph.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/graph-spec-validation-error.md b/docs/errors/graph-spec-validation-error.md
deleted file mode 100644
index 5bf10f56b..000000000
--- a/docs/errors/graph-spec-validation-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Graph spec validation"
-description: "Reference for the `GraphSpecValidationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Graph spec validation
-
-Exception raised when GraphSpec validation fails.
-
-| Field | Value |
-|---|---|
-| `error_type` | `GraphSpecValidationError` |
-| `title` | Graph spec validation |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/graph-spec-validation-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.graph.exceptions` |
-| Parent class | [`GraphSpecError`](graph-spec-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/host-library-requirements-error.md b/docs/errors/host-library-requirements-error.md
deleted file mode 100644
index 0cb13688a..000000000
--- a/docs/errors/host-library-requirements-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Host library requirements"
-description: "Reference for the `HostLibraryRequirementsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Host library requirements
-
-Raised when a method of this host's own library directories, loaded beside a caller's bundles, is refused for its requirements.
-
-| Field | Value |
-|---|---|
-| `error_type` | `HostLibraryRequirementsError` |
-| `title` | Host library requirements |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/host-library-requirements-error/` |
-| `error_domain` | `config` |
-| Defined in | `pipelex.libraries.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-| `retryable` | `false` |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/host-library-tree-error.md b/docs/errors/host-library-tree-error.md
deleted file mode 100644
index 9d6e90de0..000000000
--- a/docs/errors/host-library-tree-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Host library tree"
-description: "Reference for the `HostLibraryTreeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Host library tree
-
-Raised when a library directory of this host, one a load reads beside a caller's bundles, cannot be read as a method tree.
-
-| Field | Value |
-|---|---|
-| `error_type` | `HostLibraryTreeError` |
-| `title` | Host library tree |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/host-library-tree-error/` |
-| `error_domain` | `config` |
-| Defined in | `pipelex.libraries.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-| `retryable` | `false` |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/hosted-base-url-error.md b/docs/errors/hosted-base-url-error.md
deleted file mode 100644
index 369e55bce..000000000
--- a/docs/errors/hosted-base-url-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Hosted base url"
-description: "Reference for the `HostedBaseUrlError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Hosted base url
-
-The base URL of the hosted API is not an origin: it carries a path, a query, credentials, or a scheme other than http or https.
-
-| Field | Value |
-|---|---|
-| `error_type` | `HostedBaseUrlError` |
-| `title` | Hosted base url |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-base-url-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.hosted.exceptions` |
-| Parent class | [`HostedRunError`](hosted-run-error.md) |
-| `user_action` | `change_input` — Give the hosted API's origin as scheme://host[:port], such as https://api.pipelex.com, in --base-url or PIPELEX_BASE_URL |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/hosted-local-file-upload-unavailable-error.md b/docs/errors/hosted-local-file-upload-unavailable-error.md
deleted file mode 100644
index 356c780ab..000000000
--- a/docs/errors/hosted-local-file-upload-unavailable-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Hosted local file upload unavailable"
-description: "Reference for the `HostedLocalFileUploadUnavailableError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Hosted local file upload unavailable
-
-A hosted run's inputs name a local file, and its method calls another method by its address.
-
-| Field | Value |
-|---|---|
-| `error_type` | `HostedLocalFileUploadUnavailableError` |
-| `title` | Hosted local file upload unavailable |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-local-file-upload-unavailable-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.hosted.exceptions` |
-| Parent class | [`HostedRunError`](hosted-run-error.md) |
-| `user_action` | `change_input` — Pass each local file as an https URL the hosted API can fetch, instead of a path on this machine, then run again |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/hosted-method-invalid-error.md b/docs/errors/hosted-method-invalid-error.md
deleted file mode 100644
index 7beef1fd0..000000000
--- a/docs/errors/hosted-method-invalid-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Hosted method invalid"
-description: "Reference for the `HostedMethodInvalidError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Hosted method invalid
-
-The hosted API read the method's signature before the run and found that the method does not load.
-
-| Field | Value |
-|---|---|
-| `error_type` | `HostedMethodInvalidError` |
-| `title` | Hosted method invalid |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-method-invalid-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.hosted.exceptions` |
-| Parent class | [`HostedRunError`](hosted-run-error.md) |
-| `user_action` | `change_input` — Fix the method as each validation error says, then run it again |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/hosted-run-error.md b/docs/errors/hosted-run-error.md
deleted file mode 100644
index bca5a8736..000000000
--- a/docs/errors/hosted-run-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Hosted run error"
-description: "Reference for the `HostedRunError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Hosted run error
-
-Base class for errors pipelex raises itself while running a method on the hosted Pipelex API.
-
-| Field | Value |
-|---|---|
-| `error_type` | `HostedRunError` |
-| `title` | Hosted run error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-run-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.hosted.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/hosted-run-interrupted-error.md b/docs/errors/hosted-run-interrupted-error.md
deleted file mode 100644
index 3dad19829..000000000
--- a/docs/errors/hosted-run-interrupted-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Hosted run interrupted"
-description: "Reference for the `HostedRunInterruptedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Hosted run interrupted
-
-The hosted run was interrupted on this machine, by Ctrl-C or a cancellation, while it was being started or followed.
-
-| Field | Value |
-|---|---|
-| `error_type` | `HostedRunInterruptedError` |
-| `title` | Hosted run interrupted |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-run-interrupted-error/` |
-| `error_domain` | `runtime` |
-| Defined in | `pipelex.hosted.exceptions` |
-| Parent class | [`HostedRunError`](hosted-run-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/hosted-run-outcome-unknown-error.md b/docs/errors/hosted-run-outcome-unknown-error.md
deleted file mode 100644
index 156b25737..000000000
--- a/docs/errors/hosted-run-outcome-unknown-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Hosted run outcome unknown"
-description: "Reference for the `HostedRunOutcomeUnknownError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Hosted run outcome unknown
-
-The request that runs the method was sent, and the connection failed before its answer came back.
-
-| Field | Value |
-|---|---|
-| `error_type` | `HostedRunOutcomeUnknownError` |
-| `title` | Hosted run outcome unknown |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-run-outcome-unknown-error/` |
-| `error_domain` | `runtime` |
-| Defined in | `pipelex.hosted.exceptions` |
-| Parent class | [`HostedRunError`](hosted-run-error.md) |
-| `user_action` | `unknown` — A run may have started on the hosted API before the connection failed: check the run history on app.pipelex.com before running again, since running again starts a new, paid run |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/hosted-run-polling-error.md b/docs/errors/hosted-run-polling-error.md
deleted file mode 100644
index b06a56e4d..000000000
--- a/docs/errors/hosted-run-polling-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Hosted run polling"
-description: "Reference for the `HostedRunPollingError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Hosted run polling
-
-A run started on the hosted API, but following it to its result failed: the network, the hosted API, or its answer.
-
-| Field | Value |
-|---|---|
-| `error_type` | `HostedRunPollingError` |
-| `title` | Hosted run polling |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-run-polling-error/` |
-| `error_domain` | `runtime` |
-| Defined in | `pipelex.hosted.exceptions` |
-| Parent class | [`HostedRunError`](hosted-run-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/hosted-run-source-error.md b/docs/errors/hosted-run-source-error.md
deleted file mode 100644
index 244179b1d..000000000
--- a/docs/errors/hosted-run-source-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Hosted run source"
-description: "Reference for the `HostedRunSourceError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Hosted run source
-
-A hosted run cannot be given its method: no bundle file, an unreadable method file, no `.mthds` file, or `-L` with an address or a catalog id.
-
-| Field | Value |
-|---|---|
-| `error_type` | `HostedRunSourceError` |
-| `title` | Hosted run source |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-run-source-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.hosted.exceptions` |
-| Parent class | [`HostedRunError`](hosted-run-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/hub-slot-already-claimed-error.md b/docs/errors/hub-slot-already-claimed-error.md
deleted file mode 100644
index 02b23e731..000000000
--- a/docs/errors/hub-slot-already-claimed-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Hub slot already claimed"
-description: "Reference for the `HubSlotAlreadyClaimedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Hub slot already claimed
-
-Two plugins claimed the same hub slot.
-
-| Field | Value |
-|---|---|
-| `error_type` | `HubSlotAlreadyClaimedError` |
-| `title` | Hub slot already claimed |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/hub-slot-already-claimed-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/image-content-error.md b/docs/errors/image-content-error.md
deleted file mode 100644
index 5420ba330..000000000
--- a/docs/errors/image-content-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Image content"
-description: "Reference for the `ImageContentError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Image content
-
-| Field | Value |
-|---|---|
-| `error_type` | `ImageContentError` |
-| `title` | Image content |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/image-content-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/img-gen-generated-type-error.md b/docs/errors/img-gen-generated-type-error.md
deleted file mode 100644
index 6081e7b96..000000000
--- a/docs/errors/img-gen-generated-type-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Img gen generated type"
-description: "Reference for the `ImgGenGeneratedTypeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Img gen generated type
-
-| Field | Value |
-|---|---|
-| `error_type` | `ImgGenGeneratedTypeError` |
-| `title` | Img gen generated type |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/img-gen-generated-type-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`ImgGenGenerationError`](img-gen-generation-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/img-gen-generation-error.md b/docs/errors/img-gen-generation-error.md
deleted file mode 100644
index 3ff6eeea2..000000000
--- a/docs/errors/img-gen-generation-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Img gen generation"
-description: "Reference for the `ImgGenGenerationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Img gen generation
-
-| Field | Value |
-|---|---|
-| `error_type` | `ImgGenGenerationError` |
-| `title` | Img gen generation |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/img-gen-generation-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/img-gen-handle-not-found-error.md b/docs/errors/img-gen-handle-not-found-error.md
deleted file mode 100644
index f7e4a934a..000000000
--- a/docs/errors/img-gen-handle-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Img gen handle not found"
-description: "Reference for the `ImgGenHandleNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Img gen handle not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `ImgGenHandleNotFoundError` |
-| `title` | Img gen handle not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/img-gen-handle-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/img-gen-model-not-found-error.md b/docs/errors/img-gen-model-not-found-error.md
deleted file mode 100644
index 1eca4dbd6..000000000
--- a/docs/errors/img-gen-model-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Img gen model not found"
-description: "Reference for the `ImgGenModelNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Img gen model not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `ImgGenModelNotFoundError` |
-| `title` | Img gen model not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/img-gen-model-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`ModelNotFoundError`](model-not-found-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/img-gen-parameter-error.md b/docs/errors/img-gen-parameter-error.md
deleted file mode 100644
index a4300d6f6..000000000
--- a/docs/errors/img-gen-parameter-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Img gen parameter"
-description: "Reference for the `ImgGenParameterError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Img gen parameter
-
-| Field | Value |
-|---|---|
-| `error_type` | `ImgGenParameterError` |
-| `title` | Img gen parameter |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/img-gen-parameter-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/img-gen-prompt-error.md b/docs/errors/img-gen-prompt-error.md
deleted file mode 100644
index 4264808ab..000000000
--- a/docs/errors/img-gen-prompt-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Img gen prompt"
-description: "Reference for the `ImgGenPromptError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Img gen prompt
-
-| Field | Value |
-|---|---|
-| `error_type` | `ImgGenPromptError` |
-| `title` | Img gen prompt |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/img-gen-prompt-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/img-gen-settings-validation-error.md b/docs/errors/img-gen-settings-validation-error.md
deleted file mode 100644
index e870ce753..000000000
--- a/docs/errors/img-gen-settings-validation-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Img gen settings validation"
-description: "Reference for the `ImgGenSettingsValidationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Img gen settings validation
-
-| Field | Value |
-|---|---|
-| `error_type` | `ImgGenSettingsValidationError` |
-| `title` | Img gen settings validation |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/img-gen-settings-validation-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/index.md b/docs/errors/index.md
index 2d9efe185..080182dc9 100644
--- a/docs/errors/index.md
+++ b/docs/errors/index.md
@@ -1,24 +1,175 @@
---
-title: "Error Reference"
-description: "Auto-generated overview of the Pipelex error reference, grouped into macro areas of error classes."
+title: "Error Codes"
+description: "Every Pipelex error code, with its title, domain, retry verdict and HTTP status, each linking to its page."
---
-<!-- pipelex:generated -->
-<!-- This index is generated by `pipelex-dev generate-error-pages`. To claim this
- page for hand-editing, add a standalone `pipelex:authored` HTML comment line;
- the generator will then preserve it on every run. -->
+# Error Codes
-# Error Reference
+An error code names a situation a runner or a client can meet, and its type URI is the URL of the code's page. A code of the MTHDS standard, such as `input.missing`, is a core code, documented with the standard on [mthds.ai](https://mthds.ai/latest/errors/) at `https://mthds.ai/errors/<code>`. A code that starts with `pipelex.` names a situation the standard leaves to its implementations, and has its page here, at `https://docs.pipelex.com/errors/<code>`. Each page says what its code means, who must act and what to do, and gives the code's steps, parameters and templates.
-Every Pipelex error class has a stable RFC 7807 `type` URI on the form
-`<base_uri>/<kebab-class-name>/`, and that URI dereferences to a per-class page.
-The classes are grouped into a few macro areas — pick the one that matches where
-the error came from:
+These pages are generated from the Pipelex error registry, which follows the [MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/) under the `pipelex` prefix the core registry registers to Pipelex. The registry is published with every Pipelex release, as the release asset `pipelex-error-registry.json` on [GitHub](https://github.com/Pipelex/pipelex/releases) and inside the `pipelex` package. This is version `0.89.0` of the registry. [The Error Registry](../contribute/error-registry.md) describes how it is maintained.
-- [Authoring & language](authoring-and-language.md) — MTHDS parsing, Core language, Pipe operators, Pipe controllers, Pipe signatures, Libraries.
-- [Execution & runtime](execution-and-runtime.md) — Pipe execution, Pipeline execution, Runtime bridge, Graph, Tracing.
-- [Inference & providers](inference-and-providers.md) — Inference (Cogt), Provider adapters, Plugin system.
-- [Platform & tooling](platform-and-tooling.md) — Base & root errors, Tools, Kit, System & configuration, CLI, Codegen, Fix ops, Hosted, Methods, Migration.
+The registry declares the Pipelex codes, but Pipelex's errors do not carry them yet: an error still reports its `error_type` and a type URI derived from its class, and giving every error its code is the next step of this work, as the [Error Model](../under-the-hood/error-model.md#error-codes-and-the-pipelex-error-registry) describes.
-See [Error Model](../under-the-hood/error-model.md) for the underlying contract
-and classification rules.
+## pipelex.billing { #pipelex-billing }
+
+Credit and subscriptions: what an organization's plan and balance allow.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.billing.plan_limit`](pipelex/billing/plan_limit.md) | The account's plan does not allow this | `account` | `no` | `409` |
+| [`pipelex.billing.credit_exhausted`](pipelex/billing/credit_exhausted.md) | The organization is out of credit | `account` | `no` | `402` |
+| [`pipelex.billing.subscription_conflict`](pipelex/billing/subscription_conflict.md) | The subscription's state does not allow this | `account` | `no` | `409` |
+| [`pipelex.billing.plan_refused`](pipelex/billing/plan_refused.md) | The plan's rules refuse this change | `input` | `no` | `409` |
+
+## pipelex.org { #pipelex-org }
+
+Organizations, their members, their API keys and their promo codes.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.org.required`](pipelex/org/required.md) | An organization is required | `account` | `no` | `403` |
+| [`pipelex.org.mismatch`](pipelex/org/mismatch.md) | The reference belongs to another organization | `input` | `no` | `403` |
+| [`pipelex.org.not_found`](pipelex/org/not_found.md) | The organization's resource does not exist | `input` | `no` | `404` |
+| [`pipelex.org.not_manageable`](pipelex/org/not_manageable.md) | The resource cannot be changed this way in its state | `input` | `no` | `409` |
+| [`pipelex.org.already_exists`](pipelex/org/already_exists.md) | The organization's resource already exists | `input` | `no` | `409` |
+| [`pipelex.org.promo_invalid`](pipelex/org/promo_invalid.md) | The promo code cannot be redeemed | `input` | `no` | `422` |
+| [`pipelex.org.promo_credit_pending`](pipelex/org/promo_credit_pending.md) | The promo credit is pending | `runtime` | `no` | `502` |
+
+## pipelex.catalog { #pipelex-catalog }
+
+Saved methods in an organization's catalog.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.catalog.not_found`](pipelex/catalog/not_found.md) | The saved method does not exist | `input` | `no` | `404` |
+| [`pipelex.catalog.not_published`](pipelex/catalog/not_published.md) | The saved method has no published version | `input` | `no` | `409` |
+| [`pipelex.catalog.being_deleted`](pipelex/catalog/being_deleted.md) | The saved method is being deleted | `input` | `no` | `409` |
+| [`pipelex.catalog.deletion_failed`](pipelex/catalog/deletion_failed.md) | The saved method's deletion failed | `runtime` | `yes` | `503` |
+| [`pipelex.catalog.update_conflict`](pipelex/catalog/update_conflict.md) | The saved method changed since it was read | `input` | `no` | `409` |
+| [`pipelex.catalog.selector_invalid`](pipelex/catalog/selector_invalid.md) | The catalog selector is malformed | `input` | `no` | `422` |
+| [`pipelex.catalog.link_conflict`](pipelex/catalog/link_conflict.md) | The directory is linked to another method | `input` | `no` | none (client) |
+
+## pipelex.run { #pipelex-run }
+
+Pipelex's extensions to runs.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.run.already_exists`](pipelex/run/already_exists.md) | A run with this id already exists | `input` | `no` | `409` |
+
+## pipelex.storage { #pipelex-storage }
+
+Pipelex's storage addresses and uploads.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.storage.uri_invalid`](pipelex/storage/uri_invalid.md) | The storage address is malformed | `input` | `no` | `422` |
+| [`pipelex.storage.not_found`](pipelex/storage/not_found.md) | A stored file is gone | `runtime` | `no` | `500` |
+| [`pipelex.storage.unavailable`](pipelex/storage/unavailable.md) | Storage is unavailable | `runtime` | `yes` | `503` |
+| [`pipelex.storage.not_configured`](pipelex/storage/not_configured.md) | This deployment serves no storage for that address | `operator` | `no` | `500` |
+| [`pipelex.storage.grant_unusable`](pipelex/storage/grant_unusable.md) | The upload grant is spent or expired | `runtime` | `yes` | `403` |
+| [`pipelex.storage.grant_mismatch`](pipelex/storage/grant_mismatch.md) | The upload differs from its grant | `runtime` | `no` | `403` |
+| [`pipelex.storage.upload_refused`](pipelex/storage/upload_refused.md) | Storage refused the upload | `runtime` | `no` | `403` |
+
+## pipelex.security { #pipelex-security }
+
+Pipelex's own refusals made for safety, each recorded as a security event.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.security.reserved_key`](pipelex/security/reserved_key.md) | The request carries a reserved key | `input` | `no` | `422` |
+| [`pipelex.security.result_outside_scope`](pipelex/security/result_outside_scope.md) | A result location lies outside the run | `runtime` | `no` | `500` |
+
+## pipelex.config { #pipelex-config }
+
+The runtime's own configuration.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.config.invalid`](pipelex/config/invalid.md) | The runtime's configuration is invalid | `operator` | `no` | `500` |
+| [`pipelex.config.syntax`](pipelex/config/syntax.md) | A configuration file does not parse | `operator` | `no` | `500` |
+| [`pipelex.config.file_missing`](pipelex/config/file_missing.md) | A configuration file is missing | `operator` | `no` | `500` |
+| [`pipelex.config.variable_missing`](pipelex/config/variable_missing.md) | A configuration variable is not set | `operator` | `no` | `500` |
+| [`pipelex.config.credential_missing`](pipelex/config/credential_missing.md) | An inference backend has no credential | `operator` | `no` | `500` |
+| [`pipelex.config.credential_refused`](pipelex/config/credential_refused.md) | A service refused the configured credential | `operator` | `no` | `500` |
+| [`pipelex.config.dependency_missing`](pipelex/config/dependency_missing.md) | An optional dependency is not installed | `operator` | `no` | `500` |
+
+## pipelex.plugin { #pipelex-plugin }
+
+The plugins installed in the runtime.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.plugin.not_found`](pipelex/plugin/not_found.md) | No plugin provides the configured choice | `operator` | `no` | `500` |
+| [`pipelex.plugin.broken`](pipelex/plugin/broken.md) | A plugin failed to load | `operator` | `no` | `500` |
+| [`pipelex.plugin.conflict`](pipelex/plugin/conflict.md) | Two plugins claim the same slot | `operator` | `no` | `500` |
+| [`pipelex.plugin.api_mismatch`](pipelex/plugin/api_mismatch.md) | A plugin targets another plugin API | `operator` | `no` | `500` |
+
+## pipelex.deployment { #pipelex-deployment }
+
+The policies of a runner deployment.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.deployment.orchestration_override_forbidden`](pipelex/deployment/orchestration_override_forbidden.md) | This deployment does not allow choosing the orchestration mode | `input` | `no` | `422` |
+| [`pipelex.deployment.custom_code_requires_sandbox`](pipelex/deployment/custom_code_requires_sandbox.md) | Custom code needs a sandbox-hosted deployment | `operator` | `no` | `501` |
+| [`pipelex.deployment.python_structures_refused`](pipelex/deployment/python_structures_refused.md) | Python structure classes are not allowed here | `method` | `no` | `422` |
+| [`pipelex.deployment.token_claims_invalid`](pipelex/deployment/token_claims_invalid.md) | The token's claims cannot be used | `operator` | `no` | `500` |
+
+## pipelex.docgen { #pipelex-docgen }
+
+The document engines that print a PipeDocGen step's documents.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.docgen.engine_unavailable`](pipelex/docgen/engine_unavailable.md) | No document engine prints this here | `operator` | `no` | `501` |
+| [`pipelex.docgen.template_invalid`](pipelex/docgen/template_invalid.md) | The document template cannot be used | `method` | `no` | `422` |
+| [`pipelex.docgen.resource_refused`](pipelex/docgen/resource_refused.md) | The document names a file it may not read | `method` | `no` | `422` |
+| [`pipelex.docgen.content_unprintable`](pipelex/docgen/content_unprintable.md) | The document's content cannot be printed | `input` | `no` | `422` |
+| [`pipelex.docgen.print_timeout`](pipelex/docgen/print_timeout.md) | Printing the document took too long | `runtime` | `yes` | `504` |
+| [`pipelex.docgen.template_warning`](pipelex/docgen/template_warning.md) | The document template may be faulty | `method` | `no` | none (warning) |
+
+## pipelex.sandbox { #pipelex-sandbox }
+
+The Daytona sandbox that runs a method's own code.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.sandbox.unavailable`](pipelex/sandbox/unavailable.md) | The Daytona sandbox could not be started | `runtime` | `yes` | `503` |
+
+## pipelex.codegen { #pipelex-codegen }
+
+Code generated from a method.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.codegen.output_conflict`](pipelex/codegen/output_conflict.md) | Codegen will not write there | `input` | `no` | `409` |
+| [`pipelex.codegen.lock_invalid`](pipelex/codegen/lock_invalid.md) | The codegen lock is unreadable | `input` | `no` | `422` |
+| [`pipelex.codegen.lock_unsupported`](pipelex/codegen/lock_unsupported.md) | The codegen lock needs a newer Pipelex | `operator` | `no` | `500` |
+| [`pipelex.codegen.lock_not_found`](pipelex/codegen/lock_not_found.md) | No codegen lock in this directory | `input` | `no` | `404` |
+| [`pipelex.codegen.drifted`](pipelex/codegen/drifted.md) | The generated code has drifted from its method | `input` | `no` | `409` |
+
+## pipelex.connector { #pipelex-connector }
+
+The toolsets a method's connectors offer a model.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.connector.tool_not_in_toolset`](pipelex/connector/tool_not_in_toolset.md) | The tool is not in the connector's toolset | `method` | `no` | `422` |
+
+## pipelex.erasure { #pipelex-erasure }
+
+The erasure of runs and methods.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.erasure.incomplete`](pipelex/erasure/incomplete.md) | The erasure left data behind | `runtime` | `yes` | `503` |
+
+## pipelex.webhook { #pipelex-webhook }
+
+The webhooks a caller registers to hear about its runs.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.webhook.delivery_failed`](pipelex/webhook/delivery_failed.md) | A webhook was not delivered | `input` | `yes` | `502` |
diff --git a/docs/errors/inference-and-providers.md b/docs/errors/inference-and-providers.md
deleted file mode 100644
index 93cb704c1..000000000
--- a/docs/errors/inference-and-providers.md
+++ /dev/null
@@ -1,154 +0,0 @@
----
-title: "Inference & providers"
-description: "Pipelex error classes in the Inference & providers area, grouped by subsystem."
----
-
-<!-- pipelex:generated -->
-
-# Inference & providers
-
-Each error class below has a stable RFC 7807 `type` URI that dereferences to its
-own page. Classes are grouped by subsystem.
-
-## Inference (Cogt)
-
-- [`CogtError`](cogt-error.md) — AI inference failed
-- [`CostRegistryError`](cost-registry-error.md) — Cost registry
-- [`DocGenEngineMissingError`](doc-gen-engine-missing-error.md) — Doc gen engine missing
-- [`DocGenHandleNotFoundError`](doc-gen-handle-not-found-error.md) — Doc gen handle not found
-- [`DocGenModelCapabilityError`](doc-gen-model-capability-error.md) — Doc gen model capability
-- [`DocGenRenderError`](doc-gen-render-error.md) — Doc gen render
-- [`DryRunMockBuildError`](dry-run-mock-build-error.md) — Dry run mock build
-- [`DryRunObjectFidelityError`](dry-run-object-fidelity-error.md) — Dry run object fidelity
-- [`ExtractCapabilityError`](extract-capability-error.md) — Extract capability
-- [`ExtractHandleNotFoundError`](extract-handle-not-found-error.md) — Extract handle not found
-- [`ExtractInputError`](extract-input-error.md) — Extract input
-- [`ExtractInputFormatError`](extract-input-format-error.md) — Extract input format
-- [`ExtractJobFailureError`](extract-job-failure-error.md) — Extract job failure
-- [`ExtractModelNotFoundError`](extract-model-not-found-error.md) — Extract model not found
-- [`ExtractOutputError`](extract-output-error.md) — Extract output
-- [`FalCredentialsError`](fal-credentials-error.md) — Fal credentials
-- [`GeneratedImageError`](generated-image-error.md) — Generated image
-- [`ImageContentError`](image-content-error.md) — Image content
-- [`ImgGenGeneratedTypeError`](img-gen-generated-type-error.md) — Img gen generated type
-- [`ImgGenGenerationError`](img-gen-generation-error.md) — Img gen generation
-- [`ImgGenHandleNotFoundError`](img-gen-handle-not-found-error.md) — Img gen handle not found
-- [`ImgGenModelNotFoundError`](img-gen-model-not-found-error.md) — Img gen model not found
-- [`ImgGenParameterError`](img-gen-parameter-error.md) — Img gen parameter
-- [`ImgGenPromptError`](img-gen-prompt-error.md) — Img gen prompt
-- [`ImgGenSettingsValidationError`](img-gen-settings-validation-error.md) — Img gen settings validation
-- [`InferenceBackendCredentialsError`](inference-backend-credentials-error.md) — Inference backend credentials
-- [`InferenceBackendLibraryError`](inference-backend-library-error.md) — Inference backend library
-- [`InferenceBackendLibraryNotFoundError`](inference-backend-library-not-found-error.md) — Inference backend library not found
-- [`InferenceBackendLibraryValidationError`](inference-backend-library-validation-error.md) — Inference backend library validation
-- [`InferenceModelSpecError`](inference-model-spec-error.md) — Inference model spec
-- [`JudgmentAnswerMismatchError`](judgment-answer-mismatch-error.md) — Judgment answer mismatch
-- [`JudgmentCapabilityError`](judgment-capability-error.md) — Judgment capability
-- [`JudgmentHandleNotFoundError`](judgment-handle-not-found-error.md) — Judgment handle not found
-- [`JudgmentJobFailureError`](judgment-job-failure-error.md) — Judgment job failure
-- [`JudgmentModelMissingError`](judgment-model-missing-error.md) — Judgment model missing
-- [`JudgmentModelNotFoundError`](judgment-model-not-found-error.md) — Judgment model not found
-- [`JudgmentRefusedError`](judgment-refused-error.md) — Judgment refused
-- [`LLMAssignmentError`](llm-assignment-error.md) — LLM assignment
-- [`LLMCapabilityError`](llm-capability-error.md) — LLM capability
-- [`LLMCompletionError`](llm-completion-error.md) — LLM completion
-- [`LLMCompletionRefusedError`](llm-completion-refused-error.md) — LLM completion refused
-- [`LLMCompletionTruncatedError`](llm-completion-truncated-error.md) — LLM completion truncated
-- [`LLMConfigError`](llm-config-error.md) — LLM config
-- [`LLMHandleNotFoundError`](llm-handle-not-found-error.md) — LLM handle not found
-- [`LLMModelNotFoundError`](llm-model-not-found-error.md) — LLM model not found
-- [`LLMPromptParameterError`](llm-prompt-parameter-error.md) — LLM prompt parameter
-- [`LLMPromptSpecError`](llm-prompt-spec-error.md) — LLM prompt spec
-- [`LLMSettingRefusedError`](llm-setting-refused-error.md) — LLM setting refused
-- [`LLMSettingsValidationError`](llm-settings-validation-error.md) — LLM settings validation
-- [`MarkdownFormattingBudgetError`](markdown-formatting-budget-error.md) — Markdown formatting budget exceeded
-- [`ModelChoiceNotFoundError`](model-choice-not-found-error.md) — Model choice not found
-- [`ModelDeckNotFoundError`](model-deck-not-found-error.md) — Model deck not found
-- [`ModelDeckPresetValidatonError`](model-deck-preset-validaton-error.md) — Model deck preset validaton
-- [`ModelDeckValidationError`](model-deck-validation-error.md) — Model deck validation
-- [`ModelDeckValidatonError`](model-deck-validaton-error.md) — Model deck validaton
-- [`ModelListingUnsupportedError`](model-listing-unsupported-error.md) — Model listing unsupported
-- [`ModelManagerError`](model-manager-error.md) — Model manager
-- [`ModelNotFoundError`](model-not-found-error.md) — Model not found
-- [`ModelReferenceParseError`](model-reference-parse-error.md) — Model reference parse
-- [`ModelWaterfallError`](model-waterfall-error.md) — Model waterfall
-- [`NeitherUrlNorDataError`](neither-url-nor-data-error.md) — Neither url nor data
-- [`OutputStructureSchemaError`](output-structure-schema-error.md) — Output structure schema
-- [`PluginModelDeclarationError`](plugin-model-declaration-error.md) — Plugin model declaration
-- [`PromptDocumentFactoryError`](prompt-document-factory-error.md) — Prompt document factory
-- [`PromptDocumentFormatError`](prompt-document-format-error.md) — Prompt document format
-- [`PromptImageFactoryError`](prompt-image-factory-error.md) — Prompt image factory
-- [`PromptImageFormatError`](prompt-image-format-error.md) — Prompt image format
-- [`ReportingManagerError`](reporting-manager-error.md) — Reporting manager
-- [`RoutingProfileBlueprintValueError`](routing-profile-blueprint-value-error.md) — Routing profile blueprint value
-- [`RoutingProfileDisabledBackendError`](routing-profile-disabled-backend-error.md) — Routing profile disabled backend
-- [`RoutingProfileLibraryError`](routing-profile-library-error.md) — Routing profile library
-- [`RoutingProfileLibraryNotFoundError`](routing-profile-library-not-found-error.md) — Routing profile library not found
-- [`SdkTypeError`](sdk-type-error.md) — Sdk type
-- [`SearchHandleNotFoundError`](search-handle-not-found-error.md) — Search handle not found
-- [`SearchJobFailureError`](search-job-failure-error.md) — Search job failure
-- [`SearchModelNotFoundError`](search-model-not-found-error.md) — Search model not found
-- [`TemplateSigilSyntaxError`](template-sigil-syntax-error.md) — Template sigil syntax
-- [`TemplateUrlRefusedError`](template-url-refused-error.md) — Relative URL refused
-- [`UnsafeSchemaError`](unsafe-schema-error.md) — Unsafe schema
-
-## Provider adapters
-
-- [`AnthropicFactoryError`](anthropic-factory-error.md) — Anthropic factory
-- [`AnthropicModelListingError`](anthropic-model-listing-error.md) — Anthropic model listing
-- [`AnthropicSDKUnsupportedError`](anthropic-sdk-unsupported-error.md) — Anthropic SDK unsupported
-- [`AnthropicWorkerConfigurationError`](anthropic-worker-configuration-error.md) — Anthropic worker configuration
-- [`AzureCredentialsError`](azure-credentials-error.md) — Azure credentials
-- [`BedrockFactoryError`](bedrock-factory-error.md) — Bedrock factory
-- [`BedrockWorkerConfigurationError`](bedrock-worker-configuration-error.md) — Bedrock worker configuration
-- [`GoogleImgGenWorkerError`](google-img-gen-worker-error.md) — Google img gen worker
-- [`GoogleLLMWorkerError`](google-llm-worker-error.md) — Google LLM worker
-- [`LinkupError`](linkup-error.md) — Linkup
-- [`LinkupSearchEmptyResultError`](linkup-search-empty-result-error.md) — Linkup search empty result
-- [`LinkupSearchResponseError`](linkup-search-response-error.md) — Linkup search response
-- [`MistralExtractResponseError`](mistral-extract-response-error.md) — Mistral extract response
-- [`MistralModelListingError`](mistral-model-listing-error.md) — Mistral model listing
-- [`MistralPluginError`](mistral-plugin-error.md) — Mistral plugin
-- [`MistralWorkerConfigurationError`](mistral-worker-configuration-error.md) — Mistral worker configuration
-- [`OpenAIClientFactoryError`](open-ai-client-factory-error.md) — OpenAI client factory error
-- [`PortkeyCredentialsError`](portkey-credentials-error.md) — Portkey credentials
-- [`PortkeyError`](portkey-error.md) — Portkey
-- [`PortkeyFactoryError`](portkey-factory-error.md) — Portkey factory
-- [`TypesafeError`](typesafe-error.md) — Typesafe
-- [`TypesafeJudgmentResponseError`](typesafe-judgment-response-error.md) — Typesafe judgment response
-- [`TypesafeQuestionUnsupportedError`](typesafe-question-unsupported-error.md) — Typesafe question unsupported
-- [`VertexAIConfigError`](vertex-ai-config-error.md) — VertexAI configuration error
-- [`VertexAICredentialsError`](vertex-ai-credentials-error.md) — VertexAI credentials error
-
-## Plugin system
-
-- [`BrokenPluginError`](broken-plugin-error.md) — Broken plugin
-- [`CoreUnconditionalPluginDisabledError`](core-unconditional-plugin-disabled-error.md) — Core unconditional plugin disabled
-- [`DuplicateBundleValidatorError`](duplicate-bundle-validator-error.md) — Duplicate bundle validator
-- [`DuplicateDocGenDefaultError`](duplicate-doc-gen-default-error.md) — Duplicate doc gen default
-- [`DuplicateHttpErrorMapperError`](duplicate-http-error-mapper-error.md) — Duplicate http error mapper
-- [`DuplicateInferenceBackendError`](duplicate-inference-backend-error.md) — Duplicate inference backend
-- [`DuplicateInternalModelError`](duplicate-internal-model-error.md) — Duplicate internal model
-- [`DuplicateLogSinkError`](duplicate-log-sink-error.md) — Duplicate log sink
-- [`DuplicateModelListerError`](duplicate-model-lister-error.md) — Duplicate model lister
-- [`DuplicateOrchestratorError`](duplicate-orchestrator-error.md) — Duplicate orchestrator
-- [`DuplicatePipeFuncExecutorError`](duplicate-pipe-func-executor-error.md) — Duplicate pipe func executor
-- [`DuplicatePipeFuncPackageOfferError`](duplicate-pipe-func-package-offer-error.md) — Duplicate pipe func package offer
-- [`DuplicateSecretsProviderError`](duplicate-secrets-provider-error.md) — Duplicate secrets provider
-- [`DuplicateServiceErrorCodeError`](duplicate-service-error-code-error.md) — Duplicate service error code
-- [`DuplicateStorageProviderError`](duplicate-storage-provider-error.md) — Duplicate storage provider
-- [`HubSlotAlreadyClaimedError`](hub-slot-already-claimed-error.md) — Hub slot already claimed
-- [`InferenceBackendNotFoundError`](inference-backend-not-found-error.md) — Inference backend not found
-- [`PluginApiVersionMismatchError`](plugin-api-version-mismatch-error.md) — Plugin api version mismatch
-- [`PluginDeclaredInMultipleGroupsError`](plugin-declared-in-multiple-groups-error.md) — Plugin declared in multiple groups
-- [`PluginError`](plugin-error.md) — Plugin error
-- [`PluginLayerViolationError`](plugin-layer-violation-error.md) — Plugin layer violation
-- [`ReservedServiceErrorCodeError`](reserved-service-error-code-error.md) — Reserved service error code
-- [`RetiredPluginEntryPointGroupError`](retired-plugin-entry-point-group-error.md) — Retired plugin entry point group
-- [`UnknownBootOrchestratorError`](unknown-boot-orchestrator-error.md) — Unknown boot orchestrator
-- [`UnknownLogSinkError`](unknown-log-sink-error.md) — Unknown log sink
-- [`UnknownPipeFuncExecutionModeError`](unknown-pipe-func-execution-mode-error.md) — Unknown pipe func execution mode
-- [`UnknownSecretsMethodError`](unknown-secrets-method-error.md) — Unknown secrets method
-- [`UnknownStorageMethodError`](unknown-storage-method-error.md) — Unknown storage method
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/inference-backend-credentials-error.md b/docs/errors/inference-backend-credentials-error.md
deleted file mode 100644
index f0184ce79..000000000
--- a/docs/errors/inference-backend-credentials-error.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-title: "Inference backend credentials"
-description: "Reference for the `InferenceBackendCredentialsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Inference backend credentials
-
-| Field | Value |
-|---|---|
-| `error_type` | `InferenceBackendCredentialsError` |
-| `title` | Inference backend credentials |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/inference-backend-credentials-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-| `user_action` | `check_credentials` — Check that the required API key environment variable is set |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/inference-backend-library-error.md b/docs/errors/inference-backend-library-error.md
deleted file mode 100644
index cdd4575df..000000000
--- a/docs/errors/inference-backend-library-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Inference backend library"
-description: "Reference for the `InferenceBackendLibraryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Inference backend library
-
-A backend the library cannot load.
-
-| Field | Value |
-|---|---|
-| `error_type` | `InferenceBackendLibraryError` |
-| `title` | Inference backend library |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/inference-backend-library-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/inference-backend-library-not-found-error.md b/docs/errors/inference-backend-library-not-found-error.md
deleted file mode 100644
index 3031a5dab..000000000
--- a/docs/errors/inference-backend-library-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Inference backend library not found"
-description: "Reference for the `InferenceBackendLibraryNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Inference backend library not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `InferenceBackendLibraryNotFoundError` |
-| `title` | Inference backend library not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/inference-backend-library-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/inference-backend-library-validation-error.md b/docs/errors/inference-backend-library-validation-error.md
deleted file mode 100644
index ed28ecaa8..000000000
--- a/docs/errors/inference-backend-library-validation-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Inference backend library validation"
-description: "Reference for the `InferenceBackendLibraryValidationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Inference backend library validation
-
-| Field | Value |
-|---|---|
-| `error_type` | `InferenceBackendLibraryValidationError` |
-| `title` | Inference backend library validation |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/inference-backend-library-validation-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/inference-backend-not-found-error.md b/docs/errors/inference-backend-not-found-error.md
deleted file mode 100644
index 502029f37..000000000
--- a/docs/errors/inference-backend-not-found-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Inference backend not found"
-description: "Reference for the `InferenceBackendNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Inference backend not found
-
-No inference backend is registered for a requested (family, sdk).
-
-| Field | Value |
-|---|---|
-| `error_type` | `InferenceBackendNotFoundError` |
-| `title` | Inference backend not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/inference-backend-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/inference-model-spec-error.md b/docs/errors/inference-model-spec-error.md
deleted file mode 100644
index 54d636d1d..000000000
--- a/docs/errors/inference-model-spec-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Inference model spec"
-description: "Reference for the `InferenceModelSpecError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Inference model spec
-
-| Field | Value |
-|---|---|
-| `error_type` | `InferenceModelSpecError` |
-| `title` | Inference model spec |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/inference-model-spec-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/input-shaping-error.md b/docs/errors/input-shaping-error.md
deleted file mode 100644
index 85d89c0f7..000000000
--- a/docs/errors/input-shaping-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Input shaping"
-description: "Reference for the `InputShapingError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Input shaping
-
-Base for signature-driven input-shaping failures (Smart Inputs, D4).
-
-| Field | Value |
-|---|---|
-| `error_type` | `InputShapingError` |
-| `title` | Input shaping |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/input-shaping-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/input-stuff-spec-not-found-error.md b/docs/errors/input-stuff-spec-not-found-error.md
deleted file mode 100644
index 9548a0786..000000000
--- a/docs/errors/input-stuff-spec-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Input stuff spec not found"
-description: "Reference for the `InputStuffSpecNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Input stuff spec not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `InputStuffSpecNotFoundError` |
-| `title` | Input stuff spec not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/input-stuff-spec-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.pipes.inputs.exceptions` |
-| Parent class | [`InputStuffSpecsError`](input-stuff-specs-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/input-stuff-specs-error.md b/docs/errors/input-stuff-specs-error.md
deleted file mode 100644
index cb09da447..000000000
--- a/docs/errors/input-stuff-specs-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Input stuff specs"
-description: "Reference for the `InputStuffSpecsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Input stuff specs
-
-| Field | Value |
-|---|---|
-| `error_type` | `InputStuffSpecsError` |
-| `title` | Input stuff specs |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/input-stuff-specs-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.pipes.inputs.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/input-stuff-specs-factory-error.md b/docs/errors/input-stuff-specs-factory-error.md
deleted file mode 100644
index fdde12355..000000000
--- a/docs/errors/input-stuff-specs-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Input stuff specs factory"
-description: "Reference for the `InputStuffSpecsFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Input stuff specs factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `InputStuffSpecsFactoryError` |
-| `title` | Input stuff specs factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/input-stuff-specs-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.pipes.inputs.exceptions` |
-| Parent class | [`InputStuffSpecsError`](input-stuff-specs-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/invocation-path-error.md b/docs/errors/invocation-path-error.md
deleted file mode 100644
index 3a1f4b462..000000000
--- a/docs/errors/invocation-path-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Invocation path not derivable"
-description: "Reference for the `InvocationPathError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Invocation path not derivable
-
-Raised when an invocation's path cannot be derived: a controller dispatched a pipe without naming its segment.
-
-| Field | Value |
-|---|---|
-| `error_type` | `InvocationPathError` |
-| `title` | Invocation path not derivable |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/invocation-path-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.system.exceptions` |
-| Parent class | [`PipelexUnexpectedError`](pipelex-unexpected-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/jinja2-context-error.md b/docs/errors/jinja2-context-error.md
deleted file mode 100644
index 292f53b61..000000000
--- a/docs/errors/jinja2-context-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Jinja 2 context"
-description: "Reference for the `Jinja2ContextError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Jinja 2 context
-
-| Field | Value |
-|---|---|
-| `error_type` | `Jinja2ContextError` |
-| `title` | Jinja 2 context |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/jinja2-context-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.jinja2.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/jinja2-detect-variables-error.md b/docs/errors/jinja2-detect-variables-error.md
deleted file mode 100644
index 31fd9ad1f..000000000
--- a/docs/errors/jinja2-detect-variables-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Jinja 2 detect variables"
-description: "Reference for the `Jinja2DetectVariablesError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Jinja 2 detect variables
-
-| Field | Value |
-|---|---|
-| `error_type` | `Jinja2DetectVariablesError` |
-| `title` | Jinja 2 detect variables |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/jinja2-detect-variables-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.jinja2.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/jinja2-stuff-error.md b/docs/errors/jinja2-stuff-error.md
deleted file mode 100644
index cee1c38b4..000000000
--- a/docs/errors/jinja2-stuff-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Jinja 2 stuff"
-description: "Reference for the `Jinja2StuffError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Jinja 2 stuff
-
-| Field | Value |
-|---|---|
-| `error_type` | `Jinja2StuffError` |
-| `title` | Jinja 2 stuff |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/jinja2-stuff-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.jinja2.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/jinja2-template-budget-error.md b/docs/errors/jinja2-template-budget-error.md
deleted file mode 100644
index 9af4506bd..000000000
--- a/docs/errors/jinja2-template-budget-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Template render budget exceeded"
-description: "Reference for the `Jinja2TemplateBudgetError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Template render budget exceeded
-
-| Field | Value |
-|---|---|
-| `error_type` | `Jinja2TemplateBudgetError` |
-| `title` | Template render budget exceeded |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/jinja2-template-budget-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.tools.jinja2.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/jinja2-template-render-error.md b/docs/errors/jinja2-template-render-error.md
deleted file mode 100644
index 1cc8aef29..000000000
--- a/docs/errors/jinja2-template-render-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Jinja 2 template render"
-description: "Reference for the `Jinja2TemplateRenderError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Jinja 2 template render
-
-| Field | Value |
-|---|---|
-| `error_type` | `Jinja2TemplateRenderError` |
-| `title` | Jinja 2 template render |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/jinja2-template-render-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.jinja2.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/jinja2-template-security-error.md b/docs/errors/jinja2-template-security-error.md
deleted file mode 100644
index be5cd4879..000000000
--- a/docs/errors/jinja2-template-security-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Jinja 2 template security"
-description: "Reference for the `Jinja2TemplateSecurityError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Jinja 2 template security
-
-| Field | Value |
-|---|---|
-| `error_type` | `Jinja2TemplateSecurityError` |
-| `title` | Jinja 2 template security |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/jinja2-template-security-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.jinja2.exceptions` |
-| Parent class | [`SecurityError`](security-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/jinja2-template-syntax-error.md b/docs/errors/jinja2-template-syntax-error.md
deleted file mode 100644
index 7b547c709..000000000
--- a/docs/errors/jinja2-template-syntax-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Jinja 2 template syntax"
-description: "Reference for the `Jinja2TemplateSyntaxError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Jinja 2 template syntax
-
-| Field | Value |
-|---|---|
-| `error_type` | `Jinja2TemplateSyntaxError` |
-| `title` | Jinja 2 template syntax |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/jinja2-template-syntax-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.jinja2.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/job-metadata-error.md b/docs/errors/job-metadata-error.md
deleted file mode 100644
index 29f0a1bbd..000000000
--- a/docs/errors/job-metadata-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Job metadata"
-description: "Reference for the `JobMetadataError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Job metadata
-
-| Field | Value |
-|---|---|
-| `error_type` | `JobMetadataError` |
-| `title` | Job metadata |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/job-metadata-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.system.exceptions` |
-| Parent class | [`PipelexUnexpectedError`](pipelex-unexpected-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/json-type-error.md b/docs/errors/json-type-error.md
deleted file mode 100644
index b6b2f7ccf..000000000
--- a/docs/errors/json-type-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Json type"
-description: "Reference for the `JsonTypeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Json type
-
-| Field | Value |
-|---|---|
-| `error_type` | `JsonTypeError` |
-| `title` | Json type |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/json-type-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.misc.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/judgment-answer-mismatch-error.md b/docs/errors/judgment-answer-mismatch-error.md
deleted file mode 100644
index 10e83e9cc..000000000
--- a/docs/errors/judgment-answer-mismatch-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Judgment answer mismatch"
-description: "Reference for the `JudgmentAnswerMismatchError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Judgment answer mismatch
-
-A judgment worker answered questions nobody asked, or answered one in the wrong shape.
-
-| Field | Value |
-|---|---|
-| `error_type` | `JudgmentAnswerMismatchError` |
-| `title` | Judgment answer mismatch |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/judgment-answer-mismatch-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/judgment-capability-error.md b/docs/errors/judgment-capability-error.md
deleted file mode 100644
index 2c05af80a..000000000
--- a/docs/errors/judgment-capability-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Judgment capability"
-description: "Reference for the `JudgmentCapabilityError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Judgment capability
-
-A judgment job carries files its model does not read: images to a model without vision, documents to one that reads none.
-
-| Field | Value |
-|---|---|
-| `error_type` | `JudgmentCapabilityError` |
-| `title` | Judgment capability |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/judgment-capability-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/judgment-handle-not-found-error.md b/docs/errors/judgment-handle-not-found-error.md
deleted file mode 100644
index 9b64ac7ce..000000000
--- a/docs/errors/judgment-handle-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Judgment handle not found"
-description: "Reference for the `JudgmentHandleNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Judgment handle not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `JudgmentHandleNotFoundError` |
-| `title` | Judgment handle not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/judgment-handle-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/judgment-job-failure-error.md b/docs/errors/judgment-job-failure-error.md
deleted file mode 100644
index 1cd4bbc36..000000000
--- a/docs/errors/judgment-job-failure-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Judgment job failure"
-description: "Reference for the `JudgmentJobFailureError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Judgment job failure
-
-| Field | Value |
-|---|---|
-| `error_type` | `JudgmentJobFailureError` |
-| `title` | Judgment job failure |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/judgment-job-failure-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/judgment-model-missing-error.md b/docs/errors/judgment-model-missing-error.md
deleted file mode 100644
index 6ae365521..000000000
--- a/docs/errors/judgment-model-missing-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Judgment model missing"
-description: "Reference for the `JudgmentModelMissingError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Judgment model missing
-
-A judgment has no model to run on: the step names none, and the model deck names no default.
-
-| Field | Value |
-|---|---|
-| `error_type` | `JudgmentModelMissingError` |
-| `title` | Judgment model missing |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/judgment-model-missing-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/judgment-model-not-found-error.md b/docs/errors/judgment-model-not-found-error.md
deleted file mode 100644
index 5ce0479a6..000000000
--- a/docs/errors/judgment-model-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Judgment model not found"
-description: "Reference for the `JudgmentModelNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Judgment model not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `JudgmentModelNotFoundError` |
-| `title` | Judgment model not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/judgment-model-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`ModelNotFoundError`](model-not-found-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/judgment-refused-error.md b/docs/errors/judgment-refused-error.md
deleted file mode 100644
index 37d0369a3..000000000
--- a/docs/errors/judgment-refused-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Judgment refused"
-description: "Reference for the `JudgmentRefusedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Judgment refused
-
-The judging model declined to answer a step's question, whose output cannot hold nothing.
-
-| Field | Value |
-|---|---|
-| `error_type` | `JudgmentRefusedError` |
-| `title` | Judgment refused |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/judgment-refused-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/kit-error.md b/docs/errors/kit-error.md
deleted file mode 100644
index b8b43b349..000000000
--- a/docs/errors/kit-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Kit"
-description: "Reference for the `KitError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Kit
-
-| Field | Value |
-|---|---|
-| `error_type` | `KitError` |
-| `title` | Kit |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/kit-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.kit.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/kit-index-loading-error.md b/docs/errors/kit-index-loading-error.md
deleted file mode 100644
index f2ccb22aa..000000000
--- a/docs/errors/kit-index-loading-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Kit index loading"
-description: "Reference for the `KitIndexLoadingError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Kit index loading
-
-| Field | Value |
-|---|---|
-| `error_type` | `KitIndexLoadingError` |
-| `title` | Kit index loading |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/kit-index-loading-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.kit.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/langfuse-credentials-error.md b/docs/errors/langfuse-credentials-error.md
deleted file mode 100644
index 0dc1a5107..000000000
--- a/docs/errors/langfuse-credentials-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Langfuse credentials"
-description: "Reference for the `LangfuseCredentialsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Langfuse credentials
-
-| Field | Value |
-|---|---|
-| `error_type` | `LangfuseCredentialsError` |
-| `title` | Langfuse credentials |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/langfuse-credentials-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.system.telemetry.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/library-error.md b/docs/errors/library-error.md
deleted file mode 100644
index 2521fe469..000000000
--- a/docs/errors/library-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Library error"
-description: "Reference for the `LibraryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Library error
-
-| Field | Value |
-|---|---|
-| `error_type` | `LibraryError` |
-| `title` | Library error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/library-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.libraries.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/library-loading-error.md b/docs/errors/library-loading-error.md
deleted file mode 100644
index 5a87ea2a3..000000000
--- a/docs/errors/library-loading-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Library loading"
-description: "Reference for the `LibraryLoadingError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Library loading
-
-Error raised when loading library components fails.
-
-| Field | Value |
-|---|---|
-| `error_type` | `LibraryLoadingError` |
-| `title` | Library loading |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/library-loading-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.libraries.exceptions` |
-| Parent class | [`LibraryError`](library-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/linkup-error.md b/docs/errors/linkup-error.md
deleted file mode 100644
index 9373d0b59..000000000
--- a/docs/errors/linkup-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Linkup"
-description: "Reference for the `LinkupError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Linkup
-
-Base for every error this backend raises, so callers can catch the provider as a family.
-
-| Field | Value |
-|---|---|
-| `error_type` | `LinkupError` |
-| `title` | Linkup |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/linkup-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.linkup.linkup_exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/linkup-search-empty-result-error.md b/docs/errors/linkup-search-empty-result-error.md
deleted file mode 100644
index 78bc71156..000000000
--- a/docs/errors/linkup-search-empty-result-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Linkup search empty result"
-description: "Reference for the `LinkupSearchEmptyResultError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Linkup search empty result
-
-The Linkup API answered a structured search with no object payload to fill the output structure.
-
-| Field | Value |
-|---|---|
-| `error_type` | `LinkupSearchEmptyResultError` |
-| `title` | Linkup search empty result |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/linkup-search-empty-result-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.linkup.linkup_exceptions` |
-| Parent class | [`LinkupError`](linkup-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/linkup-search-response-error.md b/docs/errors/linkup-search-response-error.md
deleted file mode 100644
index 8d3642925..000000000
--- a/docs/errors/linkup-search-response-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Linkup search response"
-description: "Reference for the `LinkupSearchResponseError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Linkup search response
-
-The Linkup API answered a structured search with a payload shape the leaf cannot validate.
-
-| Field | Value |
-|---|---|
-| `error_type` | `LinkupSearchResponseError` |
-| `title` | Linkup search response |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/linkup-search-response-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.linkup.linkup_exceptions` |
-| Parent class | [`LinkupError`](linkup-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/list-where-singular-error.md b/docs/errors/list-where-singular-error.md
deleted file mode 100644
index 180c53cd0..000000000
--- a/docs/errors/list-where-singular-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "List where singular"
-description: "Reference for the `ListWhereSingularError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# List where singular
-
-A list was provided where the signature declares a single value (D2).
-
-| Field | Value |
-|---|---|
-| `error_type` | `ListWhereSingularError` |
-| `title` | List where singular |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/list-where-singular-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`InputShapingError`](input-shaping-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/llm-assignment-error.md b/docs/errors/llm-assignment-error.md
deleted file mode 100644
index 7c25efdef..000000000
--- a/docs/errors/llm-assignment-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "LLM assignment"
-description: "Reference for the `LLMAssignmentError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# LLM assignment
-
-| Field | Value |
-|---|---|
-| `error_type` | `LLMAssignmentError` |
-| `title` | LLM assignment |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/llm-assignment-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/llm-capability-error.md b/docs/errors/llm-capability-error.md
deleted file mode 100644
index ea31fceab..000000000
--- a/docs/errors/llm-capability-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "LLM capability"
-description: "Reference for the `LLMCapabilityError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# LLM capability
-
-| Field | Value |
-|---|---|
-| `error_type` | `LLMCapabilityError` |
-| `title` | LLM capability |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/llm-capability-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/llm-completion-error.md b/docs/errors/llm-completion-error.md
deleted file mode 100644
index 0e4561477..000000000
--- a/docs/errors/llm-completion-error.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-title: "LLM completion"
-description: "Reference for the `LLMCompletionError` Pipelex error class."
----
-
-<!-- pipelex:authored -->
-
-# LLM completion
-
-An LLM call answered, but its answer cannot be used as the pipe's output: the provider returned no choice, no text or a content type the worker does not read, or a structured generation failed for a reason no provider classified. Its category, and so whether it is retried, depends on the case, and its `user_action` gives the next step.
-
-Two subclasses report the answers a provider returns as a success although the model did not finish its text. Every LLM worker reads its response's stop signal before it returns any text, so a text cut at its limit, refused or filtered fails its pipe instead of passing for a result:
-
-- [`LLMCompletionTruncatedError`](llm-completion-truncated-error.md): the model was cut off before it finished, at its output limit (`max_tokens`) or at its context window, which the error tells apart. At the output limit, raise the pipe's `max_tokens` or shorten its input; at the context window, which no higher `max_tokens` lifts, shorten the input, lower the reasoning effort or choose a model with a larger window.
-- [`LLMCompletionRefusedError`](llm-completion-refused-error.md): the model declined to write the text, or a provider's safety filter stopped it. Revise the pipe's prompt or its input.
-
-Both are content errors in the `input` domain: they are not retryable, since the same request stops the same way, an HTTP surface answers them with 422, and their message survives STRICT disclosure. The message is one sentence naming the model by its deck handle, the pipe when the job knows it, the provider's stop value and, for a truncation, the output tokens used and the limit sent, then the next step; it never carries the partial text or the provider's body. An agent branches on the report's fields rather than the prose: `error_type`, `error_category` (`content`), `error_domain` (`input`), `retryable` (`false`) and `user_action`, whose kind is `change_input`.
-
-The stop values each worker reads are those of its provider's SDK, read as one vocabulary so that a gateway passing each provider's own value through the OpenAI completions shape is read too: OpenAI's `finish_reason`, Anthropic's `stop_reason`, Bedrock Converse's `stopReason`, Gemini's `finish_reason`, Mistral's `finish_reason`, and the Responses API's `incomplete` status with its reason. A stop value the classifier does not know is logged at warning level with the model and taken as normal, so a value a provider adds later fails no call. Two signals are never normal, whatever reason comes with them: an `incomplete` Responses API answer is a truncation when its reason is missing or unknown, and a Gemini answer with no candidate whose prompt feedback names a block reason is a refusal. Structured generation is not read this way: its configured re-asks are left as they are.
-
-A structured generation on an Anthropic model holds `max_tokens` to what its structured-output timeout lets the model produce. When that lowers the limit, an error the lowered limit can explain, a structured output that failed validation or came back incomplete, or a timeout, ends with a sentence saying the limit was lowered and to what, while a rate limit, an authentication failure, an overload, a server error or a lost connection carries no such sentence; a `max_tokens` the pipe set and the call lowers is also logged at warning level.
-
-| Field | Value |
-|---|---|
-| `error_type` | `LLMCompletionError` |
-| `title` | LLM completion |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/llm-completion-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/llm-completion-refused-error.md b/docs/errors/llm-completion-refused-error.md
deleted file mode 100644
index dfa86d91b..000000000
--- a/docs/errors/llm-completion-refused-error.md
+++ /dev/null
@@ -1,35 +0,0 @@
----
-title: "LLM completion refused"
-description: "Reference for the `LLMCompletionRefusedError` Pipelex error class."
----
-
-<!-- pipelex:authored -->
-
-# LLM completion refused
-
-A text completion the model declined to write, or that a provider's safety filter stopped.
-
-A provider answers such a completion as a success, often with no text at all and sometimes with the beginning of one, and a stop value saying why it ended: `content_filter` on OpenAI chat completions and on an `incomplete` Responses API answer, `refusal` on Anthropic, `content_filtered` and `guardrail_intervened` on Bedrock, and on Gemini `SAFETY`, `RECITATION`, `PROHIBITED_CONTENT`, `BLOCKLIST`, `SPII` and their kin. A Gemini prompt blocked before the model wrote anything comes back with no candidate at all and its reason in the prompt feedback, `prompt_feedback.block_reason`, such as `SAFETY` or `PROHIBITED_CONTENT`: it is a refusal too, whatever the reason, and the error names that reason as its stop value. The worker raises this error instead of handing the text back, so the pipe fails rather than passing an empty or cut text for a result.
-
-The message names the model by its deck handle, the pipe and the stop value, then the next step:
-
-```text
-The model 'claude-5-sonnet' declined to finish the text of pipe 'ui_designer', or a content filter stopped it (stop reason 'content_filtered'), so the text cannot be used. Revise the pipe's prompt or its input.
-```
-
-A run reports it located at the failing pipe, `Pipe 'ui_designer' failed (flow → ui_designer): The model …`. The partial text and the provider's body never appear in it.
-
-**What to do.** Revise the pipe's prompt or its input: rephrase what triggered the refusal, or remove the content the filter stopped on. Another model, whose policy or filter differs, may also answer.
-
-**For an agent.** Branch on the report's fields: `error_type` is `LLMCompletionRefusedError`, `error_category` is `content`, `error_domain` is `input` (an HTTP surface answers 422), `retryable` is `false`, since the same request is refused the same way, and `user_action.kind` is `change_input`. The message is caller-facing, so it survives STRICT disclosure.
-
-| Field | Value |
-|---|---|
-| `error_type` | `LLMCompletionRefusedError` |
-| `title` | LLM completion refused |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/llm-completion-refused-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`LLMCompletionError`](llm-completion-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/llm-completion-truncated-error.md b/docs/errors/llm-completion-truncated-error.md
deleted file mode 100644
index 95e7eea00..000000000
--- a/docs/errors/llm-completion-truncated-error.md
+++ /dev/null
@@ -1,48 +0,0 @@
----
-title: "LLM completion truncated"
-description: "Reference for the `LLMCompletionTruncatedError` Pipelex error class."
----
-
-<!-- pipelex:authored -->
-
-# LLM completion truncated
-
-A text completion stopped before the model finished it: it hit its output limit, or its context window.
-
-A provider answers such a completion as a success, with whatever text the model had written, empty or partial, and a stop value saying why it ended. The error tells the two limits apart, since they are lifted differently, and carries the one hit as its `truncation_limit`:
-
-- **The output limit** (`max_tokens`): `length` on OpenAI and Mistral, `max_tokens` on Anthropic and Bedrock, `MAX_TOKENS` on Gemini, and an `incomplete` Responses API answer whose reason is `max_output_tokens`, missing or unknown (the status alone says the text is unfinished; the error names the reason as its stop value when the answer gives one, and `incomplete` when it gives none).
-- **The context window** (`context_window`), which the input and the output filled together: `model_context_window_exceeded` on Anthropic and Bedrock, and `model_length` on Mistral.
-
-The worker raises this error instead of handing the text back, so the pipe fails rather than passing a truncated contract, summary or JSON for a result.
-
-The message names the model by its deck handle, the pipe, the stop value, the output tokens used and the `max_tokens` the request sent, or that it sent none, then the next step, which depends on the limit hit:
-
-```text
-The model 'claude-5-sonnet' was cut off before it finished the text of pipe 'ui_designer' (stop reason 'max_tokens', 4096 output tokens used, max_tokens set to 4096), so the text is incomplete. Raise the pipe's max_tokens, or shorten its input.
-```
-
-```text
-The model 'gpt-5' was cut off before it finished the text of pipe 'ui_designer' (stop reason 'length', 16384 output tokens used, no max_tokens sent), so the text is incomplete. Set the pipe's max_tokens up to the model's limit, lower its reasoning effort, or shorten its input.
-```
-
-```text
-The model 'claude-5-sonnet' filled its context window before it finished the text of pipe 'ui_designer' (stop reason 'model_context_window_exceeded', 812 output tokens used, max_tokens set to 4096), so the text is incomplete. Shorten the pipe's input, lower its reasoning effort, or choose a model with a larger context window.
-```
-
-A run reports it located at the failing pipe, `Pipe 'ui_designer' failed (flow → ui_designer): The model …`. The partial text and the provider's body never appear in it.
-
-**What to do.** At the output limit, raise the pipe's `max_tokens`, for instance `model = { model = "claude-5-sonnet", max_tokens = 16384 }`, or shorten its input. When the request sent no `max_tokens`, the pipe's setting being left to the provider, the provider's own default cut the text, so there is no limit of the pipe's to raise: set the pipe's `max_tokens`, up to the model's limit, lower its reasoning effort, or shorten its input. When the model thinks before it writes, its thinking counts against the same limit, so a lower reasoning effort also leaves more room for the text. At the context window, a higher `max_tokens` cannot help, since the input and the output already filled the window: shorten the pipe's input, lower its reasoning effort, or choose a model with a larger context window.
-
-**For an agent.** Branch on the report's fields: `error_type` is `LLMCompletionTruncatedError`, `error_category` is `content`, `error_domain` is `input` (an HTTP surface answers 422), `retryable` is `false`, since the same request stops at the same limit, and `user_action.kind` is `change_input`, its `detail` the next step for the limit hit. The message is caller-facing, so it survives STRICT disclosure.
-
-| Field | Value |
-|---|---|
-| `error_type` | `LLMCompletionTruncatedError` |
-| `title` | LLM completion truncated |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/llm-completion-truncated-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`LLMCompletionError`](llm-completion-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/llm-config-error.md b/docs/errors/llm-config-error.md
deleted file mode 100644
index 93e61121c..000000000
--- a/docs/errors/llm-config-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "LLM config"
-description: "Reference for the `LLMConfigError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# LLM config
-
-| Field | Value |
-|---|---|
-| `error_type` | `LLMConfigError` |
-| `title` | LLM config |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/llm-config-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/llm-handle-not-found-error.md b/docs/errors/llm-handle-not-found-error.md
deleted file mode 100644
index 6048ad170..000000000
--- a/docs/errors/llm-handle-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "LLM handle not found"
-description: "Reference for the `LLMHandleNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# LLM handle not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `LLMHandleNotFoundError` |
-| `title` | LLM handle not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/llm-handle-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/llm-model-not-found-error.md b/docs/errors/llm-model-not-found-error.md
deleted file mode 100644
index b328d9221..000000000
--- a/docs/errors/llm-model-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "LLM model not found"
-description: "Reference for the `LLMModelNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# LLM model not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `LLMModelNotFoundError` |
-| `title` | LLM model not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/llm-model-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`ModelNotFoundError`](model-not-found-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/llm-prompt-parameter-error.md b/docs/errors/llm-prompt-parameter-error.md
deleted file mode 100644
index 3fa543e8f..000000000
--- a/docs/errors/llm-prompt-parameter-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "LLM prompt parameter"
-description: "Reference for the `LLMPromptParameterError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# LLM prompt parameter
-
-| Field | Value |
-|---|---|
-| `error_type` | `LLMPromptParameterError` |
-| `title` | LLM prompt parameter |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/llm-prompt-parameter-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/llm-prompt-spec-error.md b/docs/errors/llm-prompt-spec-error.md
deleted file mode 100644
index 4584adeea..000000000
--- a/docs/errors/llm-prompt-spec-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "LLM prompt spec"
-description: "Reference for the `LLMPromptSpecError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# LLM prompt spec
-
-| Field | Value |
-|---|---|
-| `error_type` | `LLMPromptSpecError` |
-| `title` | LLM prompt spec |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/llm-prompt-spec-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/llm-setting-refused-error.md b/docs/errors/llm-setting-refused-error.md
deleted file mode 100644
index d1c670476..000000000
--- a/docs/errors/llm-setting-refused-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "LLM setting refused"
-description: "Reference for the `LLMSettingRefusedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# LLM setting refused
-
-A worker's refusal of an LLM setting, worded for the caller who wrote the setting.
-
-| Field | Value |
-|---|---|
-| `error_type` | `LLMSettingRefusedError` |
-| `title` | LLM setting refused |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/llm-setting-refused-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`LLMCapabilityError`](llm-capability-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/llm-settings-validation-error.md b/docs/errors/llm-settings-validation-error.md
deleted file mode 100644
index bc08f1c20..000000000
--- a/docs/errors/llm-settings-validation-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "LLM settings validation"
-description: "Reference for the `LLMSettingsValidationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# LLM settings validation
-
-| Field | Value |
-|---|---|
-| `error_type` | `LLMSettingsValidationError` |
-| `title` | LLM settings validation |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/llm-settings-validation-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/log-sink-header-value-error.md b/docs/errors/log-sink-header-value-error.md
deleted file mode 100644
index 3aad17bd4..000000000
--- a/docs/errors/log-sink-header-value-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Log sink header value holds a line break"
-description: "Reference for the `LogSinkHeaderValueError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Log sink header value holds a line break
-
-Raised at boot when an ``otlp`` sink header value holds a line break once its placeholders resolve.
-
-| Field | Value |
-|---|---|
-| `error_type` | `LogSinkHeaderValueError` |
-| `title` | Log sink header value holds a line break |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/log-sink-header-value-error/` |
-| `error_domain` | `config` |
-| Defined in | `pipelex.tools.log.exceptions` |
-| Parent class | [`CredentialsError`](credentials-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/log-sink-variable-error.md b/docs/errors/log-sink-variable-error.md
deleted file mode 100644
index e7f99620d..000000000
--- a/docs/errors/log-sink-variable-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Log sink variable did not resolve"
-description: "Reference for the `LogSinkVariableError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Log sink variable did not resolve
-
-Raised at boot when a ``${…}`` placeholder in a log sink's settings does not resolve.
-
-| Field | Value |
-|---|---|
-| `error_type` | `LogSinkVariableError` |
-| `title` | Log sink variable did not resolve |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/log-sink-variable-error/` |
-| `error_domain` | `config` |
-| Defined in | `pipelex.tools.log.exceptions` |
-| Parent class | [`CredentialsError`](credentials-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/markdown-formatting-budget-error.md b/docs/errors/markdown-formatting-budget-error.md
deleted file mode 100644
index 542d182d2..000000000
--- a/docs/errors/markdown-formatting-budget-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Markdown formatting budget exceeded"
-description: "Reference for the `MarkdownFormattingBudgetError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Markdown formatting budget exceeded
-
-Formatting a Markdown text outside any template render would spend more than the budget it gets of its own.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MarkdownFormattingBudgetError` |
-| `title` | Markdown formatting budget exceeded |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/markdown-formatting-budget-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.cogt.doc_gen.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-dependency-fetch-error.md b/docs/errors/method-dependency-fetch-error.md
deleted file mode 100644
index 2b22e681f..000000000
--- a/docs/errors/method-dependency-fetch-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method dependency fetch"
-description: "Reference for the `MethodDependencyFetchError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method dependency fetch
-
-An address-referenced method is not installed and fetching it failed (or its address is not fetchable).
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodDependencyFetchError` |
-| `title` | Method dependency fetch |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-dependency-fetch-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.methods.exceptions` |
-| Parent class | [`MethodRefError`](method-ref-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-dependency-not-shipped-error.md b/docs/errors/method-dependency-not-shipped-error.md
deleted file mode 100644
index 030edbfca..000000000
--- a/docs/errors/method-dependency-not-shipped-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method dependency not shipped"
-description: "Reference for the `MethodDependencyNotShippedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method dependency not shipped
-
-An address-referenced method the caller did not ship, under a resolution that reads nothing installed and fetches nothing.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodDependencyNotShippedError` |
-| `title` | Method dependency not shipped |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-dependency-not-shipped-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.methods.exceptions` |
-| Parent class | [`MethodRefError`](method-ref-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-entry-error.md b/docs/errors/method-entry-error.md
deleted file mode 100644
index 310e6ec1e..000000000
--- a/docs/errors/method-entry-error.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-title: "Method entry"
-description: "Reference for the `MethodEntryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method entry
-
-Raised when a method has no single pipe to start at, or no single bundle defining the pipe named.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodEntryError` |
-| `title` | Method entry |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-entry-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.pipeline.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-| `retryable` | `false` |
-| `user_action` | `change_input` — Name the pipe, or declare the method's one main_pipe: in its METHODS.toml, or in one of its bundles |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-fetch-disabled-error.md b/docs/errors/method-fetch-disabled-error.md
deleted file mode 100644
index 0e3379028..000000000
--- a/docs/errors/method-fetch-disabled-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method fetch disabled"
-description: "Reference for the `MethodFetchDisabledError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method fetch disabled
-
-An address-referenced method is not installed and fetch-on-miss is disabled, so it cannot be fetched.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodFetchDisabledError` |
-| `title` | Method fetch disabled |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-fetch-disabled-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.methods.exceptions` |
-| Parent class | [`MethodRefError`](method-ref-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-fetch-error.md b/docs/errors/method-fetch-error.md
deleted file mode 100644
index 53aa04d88..000000000
--- a/docs/errors/method-fetch-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method fetch"
-description: "Reference for the `MethodFetchError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method fetch
-
-Fetching the repository behind a method reference failed (clone, tag verification, or commit resolution).
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodFetchError` |
-| `title` | Method fetch |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-fetch-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.methods.exceptions` |
-| Parent class | [`MethodRefError`](method-ref-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-file-unavailable-error.md b/docs/errors/method-file-unavailable-error.md
deleted file mode 100644
index 489b29692..000000000
--- a/docs/errors/method-file-unavailable-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method file unavailable"
-description: "Reference for the `MethodFileUnavailableError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method file unavailable
-
-A method file, or the listing of the tree that holds it, cannot be read through the method file store.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodFileUnavailableError` |
-| `title` | Method file unavailable |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-file-unavailable-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.method_trees.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-install-error.md b/docs/errors/method-install-error.md
deleted file mode 100644
index 387e15955..000000000
--- a/docs/errors/method-install-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method install"
-description: "Reference for the `MethodInstallError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method install
-
-Installing a fetched method package into the installed-methods directory failed (occupied target, path escape, or copy failure).
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodInstallError` |
-| `title` | Method install |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-install-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.methods.exceptions` |
-| Parent class | [`MethodRefError`](method-ref-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-package-ambiguity-error.md b/docs/errors/method-package-ambiguity-error.md
deleted file mode 100644
index c76666201..000000000
--- a/docs/errors/method-package-ambiguity-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method package ambiguity"
-description: "Reference for the `MethodPackageAmbiguityError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method package ambiguity
-
-More than one package inside the fetched repository matches the requested address.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodPackageAmbiguityError` |
-| `title` | Method package ambiguity |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-package-ambiguity-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.methods.exceptions` |
-| Parent class | [`MethodRefError`](method-ref-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-package-not-found-error.md b/docs/errors/method-package-not-found-error.md
deleted file mode 100644
index 771e62e5b..000000000
--- a/docs/errors/method-package-not-found-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method package not found"
-description: "Reference for the `MethodPackageNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method package not found
-
-No package inside the fetched repository matches the requested address by manifest identity.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodPackageNotFoundError` |
-| `title` | Method package not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-package-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.methods.exceptions` |
-| Parent class | [`MethodRefError`](method-ref-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-package-symlink-error.md b/docs/errors/method-package-symlink-error.md
deleted file mode 100644
index 0e0457ab8..000000000
--- a/docs/errors/method-package-symlink-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method package symlink"
-description: "Reference for the `MethodPackageSymlinkError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method package symlink
-
-The fetched package contains a symlink, which fetched packages must not carry (it would bypass the content scans).
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodPackageSymlinkError` |
-| `title` | Method package symlink |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-package-symlink-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.methods.exceptions` |
-| Parent class | [`MethodRefError`](method-ref-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-package-too-large-error.md b/docs/errors/method-package-too-large-error.md
deleted file mode 100644
index 877d5e073..000000000
--- a/docs/errors/method-package-too-large-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method package too large"
-description: "Reference for the `MethodPackageTooLargeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method package too large
-
-Fetched content exceeds a ceiling: the selected package's file count or total bytes, or the repository's manifest scan.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodPackageTooLargeError` |
-| `title` | Method package too large |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-package-too-large-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.methods.exceptions` |
-| Parent class | [`MethodRefError`](method-ref-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-ref-error.md b/docs/errors/method-ref-error.md
deleted file mode 100644
index 6c1987855..000000000
--- a/docs/errors/method-ref-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method reference error"
-description: "Reference for the `MethodRefError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method reference error
-
-Base class for errors while resolving a method reference (`<address>[@<tag>]`).
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodRefError` |
-| `title` | Method reference error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-ref-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.methods.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-ref-parse-error.md b/docs/errors/method-ref-parse-error.md
deleted file mode 100644
index 14b6cef00..000000000
--- a/docs/errors/method-ref-parse-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method ref parse"
-description: "Reference for the `MethodRefParseError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method ref parse
-
-The method reference does not match the `<address>[@<tag>]` grammar.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodRefParseError` |
-| `title` | Method ref parse |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-ref-parse-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.methods.exceptions` |
-| Parent class | [`MethodRefError`](method-ref-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-requirements-error.md b/docs/errors/method-requirements-error.md
deleted file mode 100644
index 2151a3467..000000000
--- a/docs/errors/method-requirements-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Method requirements"
-description: "Reference for the `MethodRequirementsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method requirements
-
-Raised when a method's `requirements.txt` refuses the method as it loads.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodRequirementsError` |
-| `title` | Method requirements |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-requirements-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.libraries.exceptions` |
-| Parent class | [`LibraryLoadingError`](library-loading-error.md) |
-| `retryable` | `false` |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-requirements-file-error.md b/docs/errors/method-requirements-file-error.md
deleted file mode 100644
index f97445a0f..000000000
--- a/docs/errors/method-requirements-file-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method requirements file"
-description: "Reference for the `MethodRequirementsFileError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method requirements file
-
-Raised when a method's `requirements.txt` holds a line the MTHDS standard refuses, or cannot be read as UTF-8 text.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodRequirementsFileError` |
-| `title` | Method requirements file |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-requirements-file-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.libraries.exceptions` |
-| Parent class | [`MethodRequirementsError`](method-requirements-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-requirements-not-met-error.md b/docs/errors/method-requirements-not-met-error.md
deleted file mode 100644
index fdbca69cb..000000000
--- a/docs/errors/method-requirements-not-met-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method requirements not met"
-description: "Reference for the `MethodRequirementsNotMetError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method requirements not met
-
-Raised when the Python environment a method's PipeFunc steps run in does not satisfy its `requirements.txt`.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodRequirementsNotMetError` |
-| `title` | Method requirements not met |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-requirements-not-met-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.libraries.exceptions` |
-| Parent class | [`MethodRequirementsError`](method-requirements-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-structures-refused-error.md b/docs/errors/method-structures-refused-error.md
deleted file mode 100644
index fd6b2e9b7..000000000
--- a/docs/errors/method-structures-refused-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Method structures refused"
-description: "Reference for the `MethodStructuresRefusedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method structures refused
-
-The method declares Python structure classes, which hosted execution refuses to import into its own process.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodStructuresRefusedError` |
-| `title` | Method structures refused |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-structures-refused-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.methods.exceptions` |
-| Parent class | [`MethodRefError`](method-ref-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/method-tree-load-error.md b/docs/errors/method-tree-load-error.md
deleted file mode 100644
index 67a92f664..000000000
--- a/docs/errors/method-tree-load-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Method tree load"
-description: "Reference for the `MethodTreeLoadError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Method tree load
-
-Raised when a method tree a load reads from this host's disk cannot be listed.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MethodTreeLoadError` |
-| `title` | Method tree load |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/method-tree-load-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.libraries.exceptions` |
-| Parent class | [`LibraryLoadingError`](library-loading-error.md) |
-| `retryable` | `false` |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/migration-error.md b/docs/errors/migration-error.md
deleted file mode 100644
index 742fee38e..000000000
--- a/docs/errors/migration-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Migration error"
-description: "Reference for the `MigrationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Migration error
-
-Base for every failure raised by the configuration-migration engine.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MigrationError` |
-| `title` | Migration error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/migration-error/` |
-| `error_domain` | `config` |
-| Defined in | `pipelex.migration.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/migration-golden-error.md b/docs/errors/migration-golden-error.md
deleted file mode 100644
index dc942d595..000000000
--- a/docs/errors/migration-golden-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Migration golden error"
-description: "Reference for the `MigrationGoldenError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Migration golden error
-
-A checked-in golden is missing or unreadable, so no verdict can be produced.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MigrationGoldenError` |
-| `title` | Migration golden error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/migration-golden-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.migration.exceptions` |
-| Parent class | [`MigrationError`](migration-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/migration-ledger-error.md b/docs/errors/migration-ledger-error.md
deleted file mode 100644
index 65a4fafaf..000000000
--- a/docs/errors/migration-ledger-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Migration ledger error"
-description: "Reference for the `MigrationLedgerError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Migration ledger error
-
-A ledger file is missing, unparseable, or internally inconsistent.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MigrationLedgerError` |
-| `title` | Migration ledger error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/migration-ledger-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.migration.exceptions` |
-| Parent class | [`MigrationError`](migration-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/migration-registry-error.md b/docs/errors/migration-registry-error.md
deleted file mode 100644
index ecaeec8fc..000000000
--- a/docs/errors/migration-registry-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Migration registry error"
-description: "Reference for the `MigrationRegistryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Migration registry error
-
-The surface registry is inconsistent, or names a surface that does not exist.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MigrationRegistryError` |
-| `title` | Migration registry error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/migration-registry-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.migration.exceptions` |
-| Parent class | [`MigrationError`](migration-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/migration-snapshot-refused-error.md b/docs/errors/migration-snapshot-refused-error.md
deleted file mode 100644
index 2e379efa1..000000000
--- a/docs/errors/migration-snapshot-refused-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Migration snapshot refused"
-description: "Reference for the `MigrationSnapshotRefusedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Migration snapshot refused
-
-The regenerator refused to overwrite a head golden that records material the models lost.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MigrationSnapshotRefusedError` |
-| `title` | Migration snapshot refused |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/migration-snapshot-refused-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.migration.exceptions` |
-| Parent class | [`MigrationError`](migration-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/missing-bundle-validator-error.md b/docs/errors/missing-bundle-validator-error.md
deleted file mode 100644
index 948936185..000000000
--- a/docs/errors/missing-bundle-validator-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Missing bundle validator"
-description: "Reference for the `MissingBundleValidatorError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Missing bundle validator
-
-Raised when no bundle validator is registered for a requested orchestration mode.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MissingBundleValidatorError` |
-| `title` | Missing bundle validator |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/missing-bundle-validator-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.runtime_bridge.exceptions` |
-| Parent class | [`PipelexRuntimeBridgeError`](pipelex-runtime-bridge-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/missing-dependency-error.md b/docs/errors/missing-dependency-error.md
deleted file mode 100644
index c26f0b0ff..000000000
--- a/docs/errors/missing-dependency-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Missing dependency"
-description: "Reference for the `MissingDependencyError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Missing dependency
-
-Raised when a required dependency is not installed.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MissingDependencyError` |
-| `title` | Missing dependency |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/missing-dependency-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.system.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/missing-orchestrator-error.md b/docs/errors/missing-orchestrator-error.md
deleted file mode 100644
index 3441929b0..000000000
--- a/docs/errors/missing-orchestrator-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Missing orchestrator"
-description: "Reference for the `MissingOrchestratorError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Missing orchestrator
-
-Raised when no orchestrator is registered for a requested orchestration mode.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MissingOrchestratorError` |
-| `title` | Missing orchestrator |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/missing-orchestrator-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.runtime_bridge.exceptions` |
-| Parent class | [`PipelexRuntimeBridgeError`](pipelex-runtime-bridge-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/mistral-extract-response-error.md b/docs/errors/mistral-extract-response-error.md
deleted file mode 100644
index 672ccaca6..000000000
--- a/docs/errors/mistral-extract-response-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Mistral extract response"
-description: "Reference for the `MistralExtractResponseError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Mistral extract response
-
-| Field | Value |
-|---|---|
-| `error_type` | `MistralExtractResponseError` |
-| `title` | Mistral extract response |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/mistral-extract-response-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.mistral.mistral_exceptions` |
-| Parent class | [`MistralPluginError`](mistral-plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/mistral-model-listing-error.md b/docs/errors/mistral-model-listing-error.md
deleted file mode 100644
index 8ca804e6a..000000000
--- a/docs/errors/mistral-model-listing-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Mistral model listing"
-description: "Reference for the `MistralModelListingError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Mistral model listing
-
-| Field | Value |
-|---|---|
-| `error_type` | `MistralModelListingError` |
-| `title` | Mistral model listing |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/mistral-model-listing-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.mistral.mistral_exceptions` |
-| Parent class | [`MistralPluginError`](mistral-plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/mistral-plugin-error.md b/docs/errors/mistral-plugin-error.md
deleted file mode 100644
index fd4b20ecd..000000000
--- a/docs/errors/mistral-plugin-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Mistral plugin"
-description: "Reference for the `MistralPluginError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Mistral plugin
-
-| Field | Value |
-|---|---|
-| `error_type` | `MistralPluginError` |
-| `title` | Mistral plugin |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/mistral-plugin-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.mistral.mistral_exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/mistral-worker-configuration-error.md b/docs/errors/mistral-worker-configuration-error.md
deleted file mode 100644
index 85cf2cf48..000000000
--- a/docs/errors/mistral-worker-configuration-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Mistral worker configuration"
-description: "Reference for the `MistralWorkerConfigurationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Mistral worker configuration
-
-| Field | Value |
-|---|---|
-| `error_type` | `MistralWorkerConfigurationError` |
-| `title` | Mistral worker configuration |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/mistral-worker-configuration-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.mistral.mistral_exceptions` |
-| Parent class | [`MistralPluginError`](mistral-plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/model-choice-not-found-error.md b/docs/errors/model-choice-not-found-error.md
deleted file mode 100644
index ac0503a59..000000000
--- a/docs/errors/model-choice-not-found-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Model choice not found"
-description: "Reference for the `ModelChoiceNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Model choice not found
-
-Raised when a model reference names a handle, alias, preset or waterfall the model deck does not define, or a bare handle the deck serves only as another model type: by the deck check a pipe runs when it is built, and by the deck when a run resolves a reference. When a pipe is built, the pipe operator raises it again as a ``PipeOperatorModelChoiceError`` located on the pipe and the field, so a bundle naming an unknown model is an invalid validation verdict (error type ``unknown_model``), never a failure of the validator.
-
-| Field | Value |
-|---|---|
-| `error_type` | `ModelChoiceNotFoundError` |
-| `title` | Model choice not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/model-choice-not-found-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/model-deck-not-found-error.md b/docs/errors/model-deck-not-found-error.md
deleted file mode 100644
index 292a043a4..000000000
--- a/docs/errors/model-deck-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Model deck not found"
-description: "Reference for the `ModelDeckNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Model deck not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `ModelDeckNotFoundError` |
-| `title` | Model deck not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/model-deck-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/model-deck-preset-validaton-error.md b/docs/errors/model-deck-preset-validaton-error.md
deleted file mode 100644
index 83d117ea3..000000000
--- a/docs/errors/model-deck-preset-validaton-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Model deck preset validaton"
-description: "Reference for the `ModelDeckPresetValidatonError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Model deck preset validaton
-
-| Field | Value |
-|---|---|
-| `error_type` | `ModelDeckPresetValidatonError` |
-| `title` | Model deck preset validaton |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/model-deck-preset-validaton-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`ModelDeckValidatonError`](model-deck-validaton-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/model-deck-validation-error.md b/docs/errors/model-deck-validation-error.md
deleted file mode 100644
index 8303f9c88..000000000
--- a/docs/errors/model-deck-validation-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Model deck validation"
-description: "Reference for the `ModelDeckValidationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Model deck validation
-
-| Field | Value |
-|---|---|
-| `error_type` | `ModelDeckValidationError` |
-| `title` | Model deck validation |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/model-deck-validation-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/model-deck-validaton-error.md b/docs/errors/model-deck-validaton-error.md
deleted file mode 100644
index a2b89cca2..000000000
--- a/docs/errors/model-deck-validaton-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Model deck validaton"
-description: "Reference for the `ModelDeckValidatonError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Model deck validaton
-
-| Field | Value |
-|---|---|
-| `error_type` | `ModelDeckValidatonError` |
-| `title` | Model deck validaton |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/model-deck-validaton-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/model-listing-unsupported-error.md b/docs/errors/model-listing-unsupported-error.md
deleted file mode 100644
index d55c18cf4..000000000
--- a/docs/errors/model-listing-unsupported-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Model listing unsupported"
-description: "Reference for the `ModelListingUnsupportedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Model listing unsupported
-
-A registered lister cannot enumerate models for an SDK variant at runtime.
-
-| Field | Value |
-|---|---|
-| `error_type` | `ModelListingUnsupportedError` |
-| `title` | Model listing unsupported |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/model-listing-unsupported-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/model-manager-error.md b/docs/errors/model-manager-error.md
deleted file mode 100644
index 297acabbd..000000000
--- a/docs/errors/model-manager-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Model manager"
-description: "Reference for the `ModelManagerError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Model manager
-
-| Field | Value |
-|---|---|
-| `error_type` | `ModelManagerError` |
-| `title` | Model manager |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/model-manager-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/model-not-found-error.md b/docs/errors/model-not-found-error.md
deleted file mode 100644
index 73bf40725..000000000
--- a/docs/errors/model-not-found-error.md
+++ /dev/null
@@ -1,30 +0,0 @@
----
-title: "Model not found"
-description: "Reference for the `ModelNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:authored -->
-
-# Model not found
-
-A model the run needs is not available: either the model handle is not in the model deck, or the provider answered that the model does not exist (HTTP 404). The provider case raises one of the subclasses per inference kind.
-
-A handle missing from the model deck is reported with the fact alone, `Model handle 'x' was not found in the model deck.`, because the message reaches every surface a run failure reaches, a hosted run's stored error included. When the model belongs to a pipe of a run, the run's report is this error's, located: `Pipe 'summarize' failed (two_steps → summarize): Model handle 'x' was not found in the model deck.`
-
-Whose fault it is depends on who named the model:
-
-- **The caller's**, when the deck neither defines the reference nor names it in any of its own entries. Only the method being run can have named it, in an inline model setting such as `model = { model = "gpt-5.1", temperature = 0.2 }`, which the check at load does not look into. A model the deck serves only as another type, such as an LLM named in an image-generation setting, counts as undefined here, since the lookup of this type refuses it, unless one of the deck's own entries for this type names it. The error is then in the `input` domain, so an HTTP surface answers 422, and its message survives STRICT disclosure together with its next step, a `change_model` action naming the reference as the method wrote it and the type of model its pipe needs, never the type the deck serves it as: `Change the model 'gpt-5.1' to an LLM the model deck serves.` It is the same mistake that `ModelChoiceNotFoundError` reports at load for a reference written as a string, except for a model of another type, which the check at load does not tell apart and which therefore surfaces only here.
-- **The deployment's**, when the deck itself names the reference but cannot serve it: a preset, an alias target, a waterfall fallback or a default whose backend is not enabled. The domain is then `config`, the answer is 500, and the message is redacted under STRICT disclosure.
-
-When you run a method locally with `pipelex run`, the CLI renders a panel naming the pipe, the model and the pipe stack. For a reference only the method names, its tip gives the `change_model` next step first, then the remedy for a local setup, since a local deck can be what lacks the model; for a reference the deck names, it gives that remedy alone: your local model deck may be out of date, so delete the files under `.pipelex/inference/deck/` and run `pipelex init inference` to regenerate them, then check that the handle routes to an enabled backend you hold credentials for.
-
-| Field | Value |
-|---|---|
-| `error_type` | `ModelNotFoundError` |
-| `title` | Model not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/model-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/model-reference-parse-error.md b/docs/errors/model-reference-parse-error.md
deleted file mode 100644
index 6739f62b5..000000000
--- a/docs/errors/model-reference-parse-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Model reference parse"
-description: "Reference for the `ModelReferenceParseError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Model reference parse
-
-Error raised when a model reference string cannot be parsed.
-
-| Field | Value |
-|---|---|
-| `error_type` | `ModelReferenceParseError` |
-| `title` | Model reference parse |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/model-reference-parse-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.models.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/model-waterfall-error.md b/docs/errors/model-waterfall-error.md
deleted file mode 100644
index 67546b3c0..000000000
--- a/docs/errors/model-waterfall-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Model waterfall"
-description: "Reference for the `ModelWaterfallError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Model waterfall
-
-| Field | Value |
-|---|---|
-| `error_type` | `ModelWaterfallError` |
-| `title` | Model waterfall |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/model-waterfall-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`ModelNotFoundError`](model-not-found-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/module-file-error.md b/docs/errors/module-file-error.md
deleted file mode 100644
index 2fe4d2231..000000000
--- a/docs/errors/module-file-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Module file"
-description: "Reference for the `ModuleFileError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Module file
-
-Exception raised for errors related to module file operations.
-
-| Field | Value |
-|---|---|
-| `error_type` | `ModuleFileError` |
-| `title` | Module file |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/module-file-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.typing.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/mthds-parser-error.md b/docs/errors/mthds-parser-error.md
deleted file mode 100644
index b4abf307d..000000000
--- a/docs/errors/mthds-parser-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "MTHDS parser"
-description: "Reference for the `MthdsParserError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# MTHDS parser
-
-Raised when MthdsParser fails.
-
-| Field | Value |
-|---|---|
-| `error_type` | `MthdsParserError` |
-| `title` | MTHDS parser |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/mthds-parser-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.mthds_parsing.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/multiplicity-count-mismatch-error.md b/docs/errors/multiplicity-count-mismatch-error.md
deleted file mode 100644
index 0f26fd7c0..000000000
--- a/docs/errors/multiplicity-count-mismatch-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Multiplicity count mismatch"
-description: "Reference for the `MultiplicityCountMismatchError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Multiplicity count mismatch
-
-A fixed-count list input received the wrong number of items (D2).
-
-| Field | Value |
-|---|---|
-| `error_type` | `MultiplicityCountMismatchError` |
-| `title` | Multiplicity count mismatch |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/multiplicity-count-mismatch-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`InputShapingError`](input-shaping-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/native-concept-definition-error.md b/docs/errors/native-concept-definition-error.md
deleted file mode 100644
index 232a636c6..000000000
--- a/docs/errors/native-concept-definition-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Native concept definition"
-description: "Reference for the `NativeConceptDefinitionError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Native concept definition
-
-| Field | Value |
-|---|---|
-| `error_type` | `NativeConceptDefinitionError` |
-| `title` | Native concept definition |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/native-concept-definition-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.concepts.native.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/neither-url-nor-data-error.md b/docs/errors/neither-url-nor-data-error.md
deleted file mode 100644
index 38a2d32b2..000000000
--- a/docs/errors/neither-url-nor-data-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Neither url nor data"
-description: "Reference for the `NeitherUrlNorDataError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Neither url nor data
-
-| Field | Value |
-|---|---|
-| `error_type` | `NeitherUrlNorDataError` |
-| `title` | Neither url nor data |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/neither-url-nor-data-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.content_generation.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/nested-key-conflict-error.md b/docs/errors/nested-key-conflict-error.md
deleted file mode 100644
index 424906535..000000000
--- a/docs/errors/nested-key-conflict-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Nested key conflict"
-description: "Reference for the `NestedKeyConflictError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Nested key conflict
-
-Raised when attempting to create nested keys under a non-dict value.
-
-| Field | Value |
-|---|---|
-| `error_type` | `NestedKeyConflictError` |
-| `title` | Nested key conflict |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/nested-key-conflict-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.system.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/null-input-error.md b/docs/errors/null-input-error.md
deleted file mode 100644
index 04989ef1d..000000000
--- a/docs/errors/null-input-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Null input"
-description: "Reference for the `NullInputError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Null input
-
-A provided input value is ``null`` at the top level (D9).
-
-| Field | Value |
-|---|---|
-| `error_type` | `NullInputError` |
-| `title` | Null input |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/null-input-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`InputShapingError`](input-shaping-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/open-ai-client-factory-error.md b/docs/errors/open-ai-client-factory-error.md
deleted file mode 100644
index 5caba3543..000000000
--- a/docs/errors/open-ai-client-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "OpenAI client factory error"
-description: "Reference for the `OpenAIClientFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# OpenAI client factory error
-
-| Field | Value |
-|---|---|
-| `error_type` | `OpenAIClientFactoryError` |
-| `title` | OpenAI client factory error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/open-ai-client-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.openai.openai_exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/optional-value-absent-error.md b/docs/errors/optional-value-absent-error.md
deleted file mode 100644
index 0d6ef22da..000000000
--- a/docs/errors/optional-value-absent-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Optional value absent"
-description: "Reference for the `OptionalValueAbsentError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Optional value absent
-
-A force-marked (`!`) input was fed a recorded absence at run time (D9).
-
-| Field | Value |
-|---|---|
-| `error_type` | `OptionalValueAbsentError` |
-| `title` | Optional value absent |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/optional-value-absent-error/` |
-| `error_domain` | `runtime` |
-| Defined in | `pipelex.core.pipes.inputs.exceptions` |
-| Parent class | [`PipeRunError`](pipe-run-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/output-structure-schema-error.md b/docs/errors/output-structure-schema-error.md
deleted file mode 100644
index 76065ed66..000000000
--- a/docs/errors/output-structure-schema-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Output structure schema"
-description: "Reference for the `OutputStructureSchemaError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Output structure schema
-
-Raised when an output structure class cannot produce the JSON schema a structured leaf needs.
-
-| Field | Value |
-|---|---|
-| `error_type` | `OutputStructureSchemaError` |
-| `title` | Output structure schema |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/output-structure-schema-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.cogt.content_generation.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-batch-factory-error.md b/docs/errors/pipe-batch-factory-error.md
deleted file mode 100644
index 5e1bf362a..000000000
--- a/docs/errors/pipe-batch-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe batch factory"
-description: "Reference for the `PipeBatchFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe batch factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeBatchFactoryError` |
-| `title` | Pipe batch factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-batch-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_controllers.batch.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-compose-error.md b/docs/errors/pipe-compose-error.md
deleted file mode 100644
index 86ff276c9..000000000
--- a/docs/errors/pipe-compose-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe compose"
-description: "Reference for the `PipeComposeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe compose
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeComposeError` |
-| `title` | Pipe compose |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-compose-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.compose.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-compose-factory-error.md b/docs/errors/pipe-compose-factory-error.md
deleted file mode 100644
index 9d28ef8df..000000000
--- a/docs/errors/pipe-compose-factory-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe compose factory"
-description: "Reference for the `PipeComposeFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe compose factory
-
-Raised when a ``PipeCompose`` has no template in template mode, or its template does not parse.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeComposeFactoryError` |
-| `title` | Pipe compose factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-compose-factory-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.pipe_operators.compose.exceptions` |
-| Parent class | [`PipeComposeError`](pipe-compose-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-condition-factory-error.md b/docs/errors/pipe-condition-factory-error.md
deleted file mode 100644
index 3db09611a..000000000
--- a/docs/errors/pipe-condition-factory-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe condition factory"
-description: "Reference for the `PipeConditionFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe condition factory
-
-Raised when a ``PipeCondition`` declares neither ``expression_template`` nor ``expression``.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeConditionFactoryError` |
-| `title` | Pipe condition factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-condition-factory-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.pipe_controllers.condition.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-controller-error.md b/docs/errors/pipe-controller-error.md
deleted file mode 100644
index cfc8eaecd..000000000
--- a/docs/errors/pipe-controller-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe controller"
-description: "Reference for the `PipeControllerError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe controller
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeControllerError` |
-| `title` | Pipe controller |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-controller-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_controllers.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-controller-output-concept-mismatch-error.md b/docs/errors/pipe-controller-output-concept-mismatch-error.md
deleted file mode 100644
index 113d2ae00..000000000
--- a/docs/errors/pipe-controller-output-concept-mismatch-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe controller output concept mismatch"
-description: "Reference for the `PipeControllerOutputConceptMismatchError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe controller output concept mismatch
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeControllerOutputConceptMismatchError` |
-| `title` | Pipe controller output concept mismatch |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-controller-output-concept-mismatch-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_controllers.exceptions` |
-| Parent class | [`PipeControllerError`](pipe-controller-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-doc-gen-factory-error.md b/docs/errors/pipe-doc-gen-factory-error.md
deleted file mode 100644
index 58bb5c506..000000000
--- a/docs/errors/pipe-doc-gen-factory-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe doc gen factory"
-description: "Reference for the `PipeDocGenFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe doc gen factory
-
-Raised when a ``PipeDocGen`` cannot be built from its blueprint.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeDocGenFactoryError` |
-| `title` | Pipe doc gen factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-doc-gen-factory-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.pipe_operators.doc_gen.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-doc-gen-run-error.md b/docs/errors/pipe-doc-gen-run-error.md
deleted file mode 100644
index bc2d3db63..000000000
--- a/docs/errors/pipe-doc-gen-run-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe doc gen run"
-description: "Reference for the `PipeDocGenRunError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe doc gen run
-
-Raised when a ``PipeDocGen`` step fails while it composes its document: a template or the filename does not render.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeDocGenRunError` |
-| `title` | Pipe doc gen run |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-doc-gen-run-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.doc_gen.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-doc-gen-template-check-error.md b/docs/errors/pipe-doc-gen-template-check-error.md
deleted file mode 100644
index e77ee658c..000000000
--- a/docs/errors/pipe-doc-gen-template-check-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe doc gen template check"
-description: "Reference for the `PipeDocGenTemplateCheckError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe doc gen template check
-
-Raised by a ``PipeDocGen`` dry run when the engine's template checker reports errors in the step's template file.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeDocGenTemplateCheckError` |
-| `title` | Pipe doc gen template check |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-doc-gen-template-check-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.pipe_operators.doc_gen.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-doc-gen-template-file-unchecked-error.md b/docs/errors/pipe-doc-gen-template-file-unchecked-error.md
deleted file mode 100644
index 66dad0568..000000000
--- a/docs/errors/pipe-doc-gen-template-file-unchecked-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Pipe doc gen template file unchecked"
-description: "Reference for the `PipeDocGenTemplateFileUncheckedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe doc gen template file unchecked
-
-Raised when a ``PipeDocGen`` step built from a library crate is validated where its HTML template file is not at hand.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeDocGenTemplateFileUncheckedError` |
-| `title` | Pipe doc gen template file unchecked |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-doc-gen-template-file-unchecked-error/` |
-| `error_domain` | `runtime` |
-| Defined in | `pipelex.pipe_operators.doc_gen.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-| `retryable` | `false` |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-doc-gen-undefined-value-error.md b/docs/errors/pipe-doc-gen-undefined-value-error.md
deleted file mode 100644
index cc9b1a80f..000000000
--- a/docs/errors/pipe-doc-gen-undefined-value-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe doc gen undefined value"
-description: "Reference for the `PipeDocGenUndefinedValueError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe doc gen undefined value
-
-Raised when a ``PipeDocGen`` template or filename reads a value its inputs do not have.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeDocGenUndefinedValueError` |
-| `title` | Pipe doc gen undefined value |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-doc-gen-undefined-value-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.pipe_operators.doc_gen.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-execution-error.md b/docs/errors/pipe-execution-error.md
deleted file mode 100644
index 94bb148ee..000000000
--- a/docs/errors/pipe-execution-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe execution"
-description: "Reference for the `PipeExecutionError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe execution
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeExecutionError` |
-| `title` | Pipe execution |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-execution-error/` |
-| `error_domain` | `runtime` |
-| Defined in | `pipelex.pipeline.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-extract-factory-error.md b/docs/errors/pipe-extract-factory-error.md
deleted file mode 100644
index 2020930f6..000000000
--- a/docs/errors/pipe-extract-factory-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe extract factory"
-description: "Reference for the `PipeExtractFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe extract factory
-
-Raised when a ``PipeExtract``'s input is neither an image nor a document.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeExtractFactoryError` |
-| `title` | Pipe extract factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-extract-factory-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.pipe_operators.extract.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-factory-error.md b/docs/errors/pipe-factory-error.md
deleted file mode 100644
index 8051f10a3..000000000
--- a/docs/errors/pipe-factory-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe factory"
-description: "Reference for the `PipeFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe factory
-
-Raised when a pipe cannot be created from a blueprint.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeFactoryError` |
-| `title` | Pipe factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.pipes.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-func-execution-error.md b/docs/errors/pipe-func-execution-error.md
deleted file mode 100644
index 28c1e03b9..000000000
--- a/docs/errors/pipe-func-execution-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe func execution"
-description: "Reference for the `PipeFuncExecutionError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe func execution
-
-A transported PipeFunc failed to run to a usable result out-of-process.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeFuncExecutionError` |
-| `title` | Pipe func execution |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-func-execution-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.func.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-func-function-error.md b/docs/errors/pipe-func-function-error.md
deleted file mode 100644
index 306829cb2..000000000
--- a/docs/errors/pipe-func-function-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Pipe func function"
-description: "Reference for the `PipeFuncFunctionError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe func function
-
-A `PipeFunc`'s `function_name` names no function the step may call.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeFuncFunctionError` |
-| `title` | Pipe func function |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-func-function-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.pipe_operators.func.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-| `retryable` | `false` |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-func-package-set-unstated-error.md b/docs/errors/pipe-func-package-set-unstated-error.md
deleted file mode 100644
index b6efd70c2..000000000
--- a/docs/errors/pipe-func-package-set-unstated-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Pipe func package set unstated"
-description: "Reference for the `PipeFuncPackageSetUnstatedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe func package set unstated
-
-Raised when a method declaring requirements loads on a deployment that states no package set for its PipeFunc sandbox.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeFuncPackageSetUnstatedError` |
-| `title` | Pipe func package set unstated |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-func-package-set-unstated-error/` |
-| `error_domain` | `config` |
-| Defined in | `pipelex.libraries.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-| `retryable` | `false` |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-func-transport-error.md b/docs/errors/pipe-func-transport-error.md
deleted file mode 100644
index 2c0f6aca6..000000000
--- a/docs/errors/pipe-func-transport-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe func transport"
-description: "Reference for the `PipeFuncTransportError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe func transport
-
-A PipeFunc could not be packaged for, or rebound from, out-of-process execution.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeFuncTransportError` |
-| `title` | Pipe func transport |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-func-transport-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.func.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-img-gen-factory-error.md b/docs/errors/pipe-img-gen-factory-error.md
deleted file mode 100644
index 4d6f0aa34..000000000
--- a/docs/errors/pipe-img-gen-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe img gen factory"
-description: "Reference for the `PipeImgGenFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe img gen factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeImgGenFactoryError` |
-| `title` | Pipe img gen factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-img-gen-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.img_gen.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-img-gen-run-error.md b/docs/errors/pipe-img-gen-run-error.md
deleted file mode 100644
index f2f72a65d..000000000
--- a/docs/errors/pipe-img-gen-run-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe img gen run"
-description: "Reference for the `PipeImgGenRunError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe img gen run
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeImgGenRunError` |
-| `title` | Pipe img gen run |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-img-gen-run-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.img_gen.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-input-error.md b/docs/errors/pipe-input-error.md
deleted file mode 100644
index 6ae8f8a1c..000000000
--- a/docs/errors/pipe-input-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe input"
-description: "Reference for the `PipeInputError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe input
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeInputError` |
-| `title` | Pipe input |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-input-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.pipes.inputs.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-inputs-factory-error.md b/docs/errors/pipe-inputs-factory-error.md
deleted file mode 100644
index d76454ed2..000000000
--- a/docs/errors/pipe-inputs-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe inputs factory"
-description: "Reference for the `PipeInputsFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe inputs factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeInputsFactoryError` |
-| `title` | Pipe inputs factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-inputs-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.pipes.stuff_spec.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-io-contract-error.md b/docs/errors/pipe-io-contract-error.md
deleted file mode 100644
index 43e61336f..000000000
--- a/docs/errors/pipe-io-contract-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe IO contract"
-description: "Reference for the `PipeIOContractError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe IO contract
-
-Raised when projecting a validated pipe into its `pipe_io_contracts` IO contract fails.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeIOContractError` |
-| `title` | Pipe IO contract |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-io-contract-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipeline.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-job-error.md b/docs/errors/pipe-job-error.md
deleted file mode 100644
index 3ed165487..000000000
--- a/docs/errors/pipe-job-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe job"
-description: "Reference for the `PipeJobError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe job
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeJobError` |
-| `title` | Pipe job |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-job-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_run.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-judge-error.md b/docs/errors/pipe-judge-error.md
deleted file mode 100644
index b6c17cff4..000000000
--- a/docs/errors/pipe-judge-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe judge"
-description: "Reference for the `PipeJudgeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe judge
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeJudgeError` |
-| `title` | Pipe judge |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-judge-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.judge.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-judge-input-capability-error.md b/docs/errors/pipe-judge-input-capability-error.md
deleted file mode 100644
index 0f974e1ac..000000000
--- a/docs/errors/pipe-judge-input-capability-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe judge input capability"
-description: "Reference for the `PipeJudgeInputCapabilityError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe judge input capability
-
-A `PipeJudge`'s prompt presents an image or a document, and the judging model it resolves to does not read one.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeJudgeInputCapabilityError` |
-| `title` | Pipe judge input capability |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-judge-input-capability-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.pipe_operators.judge.exceptions` |
-| Parent class | [`PipeJudgeError`](pipe-judge-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-library-error.md b/docs/errors/pipe-library-error.md
deleted file mode 100644
index d9d2b532f..000000000
--- a/docs/errors/pipe-library-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe library"
-description: "Reference for the `PipeLibraryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe library
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeLibraryError` |
-| `title` | Pipe library |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-library-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.libraries.pipe.exceptions` |
-| Parent class | [`LibraryError`](library-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-llm-factory-error.md b/docs/errors/pipe-llm-factory-error.md
deleted file mode 100644
index 840258f57..000000000
--- a/docs/errors/pipe-llm-factory-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe LLM factory"
-description: "Reference for the `PipeLLMFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe LLM factory
-
-Raised when a ``PipeLLM``'s prompt template, or the system prompt it declares or inherits from its domain, does not parse.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeLLMFactoryError` |
-| `title` | Pipe LLM factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-llm-factory-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.pipe_operators.llm.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-load-refusal-error.md b/docs/errors/pipe-load-refusal-error.md
deleted file mode 100644
index 9cf0eb867..000000000
--- a/docs/errors/pipe-load-refusal-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe load refusal"
-description: "Reference for the `PipeLoadRefusalError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe load refusal
-
-Raised by the library load when building one pipe of a bundle raises a refusal of the caller's input that carries no locator of its own. It names the pipe and its file, and bundle validation reports it as an invalid verdict.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeLoadRefusalError` |
-| `title` | Pipe load refusal |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-load-refusal-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.core.pipes.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-loading-error.md b/docs/errors/pipe-loading-error.md
deleted file mode 100644
index 91b428ce3..000000000
--- a/docs/errors/pipe-loading-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe loading"
-description: "Reference for the `PipeLoadingError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe loading
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeLoadingError` |
-| `title` | Pipe loading |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-loading-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.libraries.exceptions` |
-| Parent class | [`LibraryLoadingError`](library-loading-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-not-found-error.md b/docs/errors/pipe-not-found-error.md
deleted file mode 100644
index 8a5aa7507..000000000
--- a/docs/errors/pipe-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe not found"
-description: "Reference for the `PipeNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeNotFoundError` |
-| `title` | Pipe not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.libraries.pipe.exceptions` |
-| Parent class | [`PipeLibraryError`](pipe-library-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-operator-model-availability-error.md b/docs/errors/pipe-operator-model-availability-error.md
deleted file mode 100644
index 883c07802..000000000
--- a/docs/errors/pipe-operator-model-availability-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe operator model availability"
-description: "Reference for the `PipeOperatorModelAvailabilityError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe operator model availability
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeOperatorModelAvailabilityError` |
-| `title` | Pipe operator model availability |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-operator-model-availability-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-operator-model-choice-error.md b/docs/errors/pipe-operator-model-choice-error.md
deleted file mode 100644
index 12932494e..000000000
--- a/docs/errors/pipe-operator-model-choice-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe operator model choice"
-description: "Reference for the `PipeOperatorModelChoiceError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe operator model choice
-
-Raised by a pipe operator (``PipeLLM``, ``PipeStructure``, ``PipeImgGen``, ``PipeExtract``, ``PipeSearch``, ``PipeJudge``) when it is built from its blueprint and a model field names a model the model deck does not define, or a bare handle the deck serves only as another model type (an LLM named in a ``PipeImgGen``, for instance). Bundle validation reports it as an invalid verdict whose item has the error type ``unknown_model``, and a run, which loads its bundle before any pipe runs, refuses the bundle with that same verdict.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeOperatorModelChoiceError` |
-| `title` | Pipe operator model choice |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-operator-model-choice-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.core.pipes.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-parallel-factory-error.md b/docs/errors/pipe-parallel-factory-error.md
deleted file mode 100644
index 685a602be..000000000
--- a/docs/errors/pipe-parallel-factory-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe parallel factory"
-description: "Reference for the `PipeParallelFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe parallel factory
-
-Raised when a ``PipeParallel`` branch names no ``result``.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeParallelFactoryError` |
-| `title` | Pipe parallel factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-parallel-factory-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.pipe_controllers.parallel.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-router-error.md b/docs/errors/pipe-router-error.md
deleted file mode 100644
index e0735e8eb..000000000
--- a/docs/errors/pipe-router-error.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-title: "Pipe router"
-description: "Reference for the `PipeRouterError` Pipelex error class."
----
-
-<!-- pipelex:authored -->
-
-# Pipe router
-
-A pipe failed while running: the failure, located at the pipe where it happened.
-
-The pipe router raises it around every failure of the pipe it runs, chained to that failure, with the pipe's code (`pipe_code`) and a snapshot of its path from the entry pipe (`pipe_stack`). A failure that already carries one rises untouched through the routers of the pipe controllers above it, so the location is always the innermost one. An exception that is not a Pipelex error is first turned into a [`PipelexUnexpectedError`](pipelex-unexpected-error.md) whose message names its class.
-
-Like [`PipelineExecutionError`](pipeline-execution-error.md), which wraps it when the run fails, it reports its **root fault** rather than itself: the `error_type`, `title`, `type_uri` and caller-facing flag are the root fault's, and the message is the root fault's own, prefixed with `Pipe '<code>' failed (<path>): `. The classification comes from the cause chain. See [the error model](../under-the-hood/error-model.md#run-failures-the-root-fault-located) for the full rules.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeRouterError` |
-| `title` | Pipe router |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-router-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_run.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-run-error.md b/docs/errors/pipe-run-error.md
deleted file mode 100644
index 424e7dc7a..000000000
--- a/docs/errors/pipe-run-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe run"
-description: "Reference for the `PipeRunError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe run
-
-A pipe failed while running, with the run mode and the pipe it failed in.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeRunError` |
-| `title` | Pipe run |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-run-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.pipes.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-run-inputs-error.md b/docs/errors/pipe-run-inputs-error.md
deleted file mode 100644
index 9e0221e07..000000000
--- a/docs/errors/pipe-run-inputs-error.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-title: "Pipe run inputs"
-description: "Reference for the `PipeRunInputsError` Pipelex error class."
----
-
-<!-- pipelex:authored -->
-
-# Pipe run inputs
-
-A pipe could not get the inputs it needs to run.
-
-When a pipe starts without a required input, the caller's request or the caller's method left it out: `Live run of PipeSequence 'flow': missing required inputs: topic.` That error is in the `input` domain, so an HTTP surface answers 422, its message survives STRICT disclosure, and its next step names the inputs to provide.
-
-An input whose resource the pipe cannot use (a local file that does not exist) raises it too, but that message names the path as resolved on the host running the method, so it carries no domain and is redacted under STRICT disclosure, as it is when raised from any other place.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeRunInputsError` |
-| `title` | Pipe run inputs |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-run-inputs-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.pipes.inputs.exceptions` |
-| Parent class | [`PipeRunError`](pipe-run-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-run-params-error.md b/docs/errors/pipe-run-params-error.md
deleted file mode 100644
index 435318af3..000000000
--- a/docs/errors/pipe-run-params-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe run params"
-description: "Reference for the `PipeRunParamsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe run params
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeRunParamsError` |
-| `title` | Pipe run params |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-run-params-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_run.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-search-error.md b/docs/errors/pipe-search-error.md
deleted file mode 100644
index b87b73d1f..000000000
--- a/docs/errors/pipe-search-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe search"
-description: "Reference for the `PipeSearchError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe search
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeSearchError` |
-| `title` | Pipe search |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-search-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.search.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-search-factory-error.md b/docs/errors/pipe-search-factory-error.md
deleted file mode 100644
index 12530e58b..000000000
--- a/docs/errors/pipe-search-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe search factory"
-description: "Reference for the `PipeSearchFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe search factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeSearchFactoryError` |
-| `title` | Pipe search factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-search-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.search.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-sequence-factory-error.md b/docs/errors/pipe-sequence-factory-error.md
deleted file mode 100644
index 8163eb5d8..000000000
--- a/docs/errors/pipe-sequence-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe sequence factory"
-description: "Reference for the `PipeSequenceFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe sequence factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeSequenceFactoryError` |
-| `title` | Pipe sequence factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-sequence-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_controllers.sequence.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-signature-not-executable-error.md b/docs/errors/pipe-signature-not-executable-error.md
deleted file mode 100644
index a0dd98347..000000000
--- a/docs/errors/pipe-signature-not-executable-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipe signature not executable"
-description: "Reference for the `PipeSignatureNotExecutableError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe signature not executable
-
-Raised when a `PipeSignature` is invoked in live execution.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeSignatureNotExecutableError` |
-| `title` | Pipe signature not executable |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-signature-not-executable-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_signature.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-spec-error.md b/docs/errors/pipe-spec-error.md
deleted file mode 100644
index 5d3039009..000000000
--- a/docs/errors/pipe-spec-error.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-title: "Pipe spec (removed)"
-description: "The `PipeSpecError` Pipelex error class no longer exists."
----
-
-<!-- pipelex:authored -->
-
-# Pipe spec (removed)
-
-**`PipeSpecError` is no longer raised.** It reported a malformed pipe spec, the JSON authoring format that `pipelex-agent pipe` and the `POST /v1/build/pipe-spec` route converted into MTHDS TOML. The command, the route and the pipe spec are all gone: a pipe is written in MTHDS directly, in a `[pipe.<code>]` section, and checked with `pipelex validate bundle` or [`POST /v1/validate`](../api-server/pipe-validate.md).
-
-This page stays at the URL the error's `type_uri` published, so a link recorded from an earlier response still resolves.
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-stack-overflow-error.md b/docs/errors/pipe-stack-overflow-error.md
deleted file mode 100644
index 1f9f37bb6..000000000
--- a/docs/errors/pipe-stack-overflow-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipe stack overflow"
-description: "Reference for the `PipeStackOverflowError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipe stack overflow
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipeStackOverflowError` |
-| `title` | Pipe stack overflow |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-stack-overflow-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipeline.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipelex-bridge-dispatch-error.md b/docs/errors/pipelex-bridge-dispatch-error.md
deleted file mode 100644
index 4aa8f6dbe..000000000
--- a/docs/errors/pipelex-bridge-dispatch-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipelex bridge dispatch"
-description: "Reference for the `PipelexBridgeDispatchError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipelex bridge dispatch
-
-Raised when a pipe dispatched through the bridge fails (validation or execution).
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelexBridgeDispatchError` |
-| `title` | Pipelex bridge dispatch |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipelex-bridge-dispatch-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.runtime_bridge.exceptions` |
-| Parent class | [`PipelexRuntimeBridgeError`](pipelex-runtime-bridge-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipelex-cli-error.md b/docs/errors/pipelex-cli-error.md
deleted file mode 100644
index 5f66e98b0..000000000
--- a/docs/errors/pipelex-cli-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipelex CLI"
-description: "Reference for the `PipelexCLIError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipelex CLI
-
-Raised when there's an error in CLI usage or operation.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelexCLIError` |
-| `title` | Pipelex CLI |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipelex-cli-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cli.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipelex-config-error.md b/docs/errors/pipelex-config-error.md
deleted file mode 100644
index 48ab87685..000000000
--- a/docs/errors/pipelex-config-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipelex config"
-description: "Reference for the `PipelexConfigError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipelex config
-
-A configuration this process cannot use, optionally with the migration that explains it.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelexConfigError` |
-| `title` | Pipelex config |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipelex-config-error/` |
-| `error_domain` | `config` |
-| Defined in | `pipelex.base_exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipelex-error.md b/docs/errors/pipelex-error.md
deleted file mode 100644
index 4157b95ad..000000000
--- a/docs/errors/pipelex-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipelex error"
-description: "Reference for the `PipelexError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipelex error
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelexError` |
-| `title` | Pipelex error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipelex-error/` |
-| `error_domain` | _(unset)_ |
-| Defined in | `pipelex.base_exceptions` |
-| Parent class | `Exception` (Python builtin) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipelex-runtime-bridge-error.md b/docs/errors/pipelex-runtime-bridge-error.md
deleted file mode 100644
index 2f98318f0..000000000
--- a/docs/errors/pipelex-runtime-bridge-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipelex runtime bridge"
-description: "Reference for the `PipelexRuntimeBridgeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipelex runtime bridge
-
-Base for errors raised by the Pipelex runtime-bridge surface.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelexRuntimeBridgeError` |
-| `title` | Pipelex runtime bridge |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipelex-runtime-bridge-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.runtime_bridge.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipelex-setup-error.md b/docs/errors/pipelex-setup-error.md
deleted file mode 100644
index 6579f0788..000000000
--- a/docs/errors/pipelex-setup-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipelex setup"
-description: "Reference for the `PipelexSetupError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipelex setup
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelexSetupError` |
-| `title` | Pipelex setup |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipelex-setup-error/` |
-| `error_domain` | `config` |
-| Defined in | `pipelex.base_exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipelex-unexpected-error.md b/docs/errors/pipelex-unexpected-error.md
deleted file mode 100644
index e9bcb8aae..000000000
--- a/docs/errors/pipelex-unexpected-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Unexpected internal error"
-description: "Reference for the `PipelexUnexpectedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Unexpected internal error
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelexUnexpectedError` |
-| `title` | Unexpected internal error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipelex-unexpected-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.base_exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipelex/billing/credit_exhausted.md b/docs/errors/pipelex/billing/credit_exhausted.md
new file mode 100644
index 000000000..38e29f204
--- /dev/null
+++ b/docs/errors/pipelex/billing/credit_exhausted.md
@@ -0,0 +1,49 @@
+---
+title: "pipelex.billing.credit_exhausted"
+description: "The organization is out of credit: what the Pipelex error code pipelex.billing.credit_exhausted means, who must act and what to do."
+---
+
+# pipelex.billing.credit_exhausted
+
+**The organization is out of credit**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.billing.credit_exhausted` |
+| Family | [`pipelex.billing`](../../index.md#pipelex-billing): Credit and subscriptions: what an organization's plan and balance allow. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `account`: the account's owner acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `402` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The organization's credit is spent. The platform refuses a run before queueing it, and a model call made once the credit has run out is refused as well.
+
+## What to do
+
+Add credit to the organization, or move it to a plan that includes more, then start the run again.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the account's owner, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `check_account` | Add credit to the organization, or move it to a plan that includes more, then try again. |
+| Any other reader | `contact_owner` | Ask the account's owner to add credit to the organization. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The organization has no credit left, so the operation was refused.
+
+## Parameters
+
+This code declares no parameters, so its problems carry no `params`.
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/billing/plan_limit.md b/docs/errors/pipelex/billing/plan_limit.md
new file mode 100644
index 000000000..7d78e8625
--- /dev/null
+++ b/docs/errors/pipelex/billing/plan_limit.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.billing.plan_limit"
+description: "The account's plan does not allow this: what the Pipelex error code pipelex.billing.plan_limit means, who must act and what to do."
+---
+
+# pipelex.billing.plan_limit
+
+**The account's plan does not allow this**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.billing.plan_limit` |
+| Family | [`pipelex.billing`](../../index.md#pipelex-billing): Credit and subscriptions: what an organization's plan and balance allow. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `account`: the account's owner acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `409` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The account's plan caps a resource, such as its API keys, and the account already holds as many as the plan allows.
+
+## What to do
+
+Remove something the limit counts, such as an API key no longer in use, or move the account to a plan with a higher limit.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the account's owner, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `check_account` | Check the account's plan, then free some of '`{limit}`' or move to a plan that allows more. |
+| Any other reader | `contact_owner` | Ask the account's owner to move to a plan that allows more than `{value}` for '`{limit}`'. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The account's plan allows at most `{value}` for '`{limit}`', and the account already holds that many.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `limit` | `identifier` | What the plan caps, such as the account's API keys. |
+| `value` | `integer` | The most the account's plan allows. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/billing/plan_refused.md b/docs/errors/pipelex/billing/plan_refused.md
new file mode 100644
index 000000000..59a0fc38a
--- /dev/null
+++ b/docs/errors/pipelex/billing/plan_refused.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.billing.plan_refused"
+description: "The plan's rules refuse this change: what the Pipelex error code pipelex.billing.plan_refused means, who must act and what to do."
+---
+
+# pipelex.billing.plan_refused
+
+**The plan's rules refuse this change**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.billing.plan_refused` |
+| Family | [`pipelex.billing`](../../index.md#pipelex-billing): Credit and subscriptions: what an organization's plan and balance allow. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `409` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+An administrator's change to an organization's plan that the plan's kind does not allow.
+
+## What to do
+
+Read `params.reason`, then choose another plan, or make the change on a plan that allows it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Request a change the organization's plan allows, then send the request again. |
+| Any other reader | `change_input` | Pass this to the caller, whose plan change the plan's rules refuse. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The rules of the organization's plan refuse this change (reason: `{reason}`).
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `reason` | one of `enterprise_is_paid_only`, `plan_not_editable`, `plan_not_enterprise` | Why the change is refused: an enterprise plan is only ever paid, the plan cannot be edited, or the change applies only to an enterprise plan and this one is not. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/billing/subscription_conflict.md b/docs/errors/pipelex/billing/subscription_conflict.md
new file mode 100644
index 000000000..81b633e22
--- /dev/null
+++ b/docs/errors/pipelex/billing/subscription_conflict.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.billing.subscription_conflict"
+description: "The subscription's state does not allow this: what the Pipelex error code pipelex.billing.subscription_conflict means, who must act and what to do."
+---
+
+# pipelex.billing.subscription_conflict
+
+**The subscription's state does not allow this**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.billing.subscription_conflict` |
+| Family | [`pipelex.billing`](../../index.md#pipelex-billing): Credit and subscriptions: what an organization's plan and balance allow. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `account`: the account's owner acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `409` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A billing action needs an active subscription and the organization has none, or forbids one and the organization already has one.
+
+## What to do
+
+Read the organization's subscription in its billing settings, then subscribe first, or manage the subscription it already has.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the account's owner, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `check_account` | Check the organization's subscription, then take the billing action its state allows. |
+| Any other reader | `contact_owner` | Ask the account's owner to check the organization's subscription. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> This billing action is not possible while the organization's subscription is '`{subscription}`'.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `subscription` | one of `none`, `active` | The organization's subscription: it has none, or it has an active one. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/catalog/being_deleted.md b/docs/errors/pipelex/catalog/being_deleted.md
new file mode 100644
index 000000000..0e75e083a
--- /dev/null
+++ b/docs/errors/pipelex/catalog/being_deleted.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.catalog.being_deleted"
+description: "The saved method is being deleted: what the Pipelex error code pipelex.catalog.being_deleted means, who must act and what to do."
+---
+
+# pipelex.catalog.being_deleted
+
+**The saved method is being deleted**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.catalog.being_deleted` |
+| Family | [`pipelex.catalog`](../../index.md#pipelex-catalog): Saved methods in an organization's catalog. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `409` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The method's deletion is in flight, so it can no longer be run, changed or published.
+
+## What to do
+
+Use another method, or save the method again under a new id if it is still wanted.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Use another method, since the method '`{method_id}`' is being deleted. |
+| Any other reader | `change_input` | Pass this to the caller, whose request names the method '`{method_id}`', which is being deleted. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The method '`{method_id}`' is being deleted.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `method_id` | `identifier` | The catalog id of the method. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/catalog/deletion_failed.md b/docs/errors/pipelex/catalog/deletion_failed.md
new file mode 100644
index 000000000..ddadb6a9c
--- /dev/null
+++ b/docs/errors/pipelex/catalog/deletion_failed.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.catalog.deletion_failed"
+description: "The saved method's deletion failed: what the Pipelex error code pipelex.catalog.deletion_failed means, who must act and what to do."
+---
+
+# pipelex.catalog.deletion_failed
+
+**The saved method's deletion failed**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.catalog.deletion_failed` |
+| Family | [`pipelex.catalog`](../../index.md#pipelex-catalog): Saved methods in an organization's catalog. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `runtime`: nobody could have acted beforehand, so whoever made the call waits, retries or reports the problem |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `yes`: repeating the operation may succeed, after `retry_after` seconds when the problem gives it |
+| HTTP status | `503` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A step of the method's deletion failed. Deleting the method again resumes its deletion.
+
+## What to do
+
+Send the delete again. If it keeps failing, report it to whoever runs the runtime.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever made the call, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `retry` | Delete the method '`{method_id}`' again. |
+| Any other reader | `retry` | Delete the method '`{method_id}`' again. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The deletion of the method '`{method_id}`' did not complete.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `method_id` | `identifier` | The catalog id of the method. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/catalog/link_conflict.md b/docs/errors/pipelex/catalog/link_conflict.md
new file mode 100644
index 000000000..7bfbc54e2
--- /dev/null
+++ b/docs/errors/pipelex/catalog/link_conflict.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.catalog.link_conflict"
+description: "The directory is linked to another method: what the Pipelex error code pipelex.catalog.link_conflict means, who must act and what to do."
+---
+
+# pipelex.catalog.link_conflict
+
+**The directory is linked to another method**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.catalog.link_conflict` |
+| Family | [`pipelex.catalog`](../../index.md#pipelex-catalog): Saved methods in an organization's catalog. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | none (client) |
+| Raised as | an error a client detects itself, never received from a runner |
+
+## What it means
+
+A local directory records, in its method link, which saved method its files belong to. The link names another method than the one the save targets, cannot be read, or records a sync that did not finish, so the client refuses to save over a draft that is not this directory's.
+
+## What to do
+
+Check which method the directory is linked to, then save to that method or move the files to a directory of their own. Repair or remove a link that cannot be read.
+
+## Next steps
+
+A client that detects this error offers the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Save the directory to the method its link names, or save these files from a directory of their own. |
+| Any other reader | `change_input` | Pass this to the caller, whose directory '`{path}`' is linked in a way that stops this save. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The method link of the directory '`{path}`' stops this save to the method '`{method_id}`'.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `method_id` | `identifier` | The catalog id of the method the save targets. |
+| `path` | `caller_text` | The local directory whose link stops the save. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/catalog/not_found.md b/docs/errors/pipelex/catalog/not_found.md
new file mode 100644
index 000000000..3808a26ce
--- /dev/null
+++ b/docs/errors/pipelex/catalog/not_found.md
@@ -0,0 +1,55 @@
+---
+title: "pipelex.catalog.not_found"
+description: "The saved method does not exist: what the Pipelex error code pipelex.catalog.not_found means, who must act and what to do."
+---
+
+# pipelex.catalog.not_found
+
+**The saved method does not exist**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.catalog.not_found` |
+| Family | [`pipelex.catalog`](../../index.md#pipelex-catalog): Saved methods in an organization's catalog. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `404` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+No saved method, version or example matches the request in the catalog of the organization the request acts for.
+
+## What to do
+
+List the catalog's methods and their versions, and use an identifier that exists. A catalog id is read in the organization the request acts for, so check that it is the right one.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | List the organization's catalog to find the `{resource}`, then send the request again with one that exists. |
+| Any other reader | `change_input` | Pass this to the caller, whose request names a `{resource}` the catalog does not hold. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The organization's catalog holds no `{resource}` matching the request for the method '`{method_id}`'.
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `resource` | one of `method`, `version`, `example` | What the request names: a saved method, one of its versions, or one of its examples. |
+| `method_id` | `identifier` | The catalog id of the method the request names. |
+| `version` | `integer` (optional) | The version the request names, when what it names is a version. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/catalog/not_published.md b/docs/errors/pipelex/catalog/not_published.md
new file mode 100644
index 000000000..a71794cd3
--- /dev/null
+++ b/docs/errors/pipelex/catalog/not_published.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.catalog.not_published"
+description: "The saved method has no published version: what the Pipelex error code pipelex.catalog.not_published means, who must act and what to do."
+---
+
+# pipelex.catalog.not_published
+
+**The saved method has no published version**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.catalog.not_published` |
+| Family | [`pipelex.catalog`](../../index.md#pipelex-catalog): Saved methods in an organization's catalog. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `409` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A bare catalog id names the method's latest published version, and the method has only a draft.
+
+## What to do
+
+Publish the method, or name its draft with the `@draft` suffix.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Publish a version of the method '`{method_id}`', or name its draft as '`{method_id}`@draft', then send the request again. |
+| Any other reader | `change_input` | Pass this to the caller, who names the latest published version of the method '`{method_id}`', which has none. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The method '`{method_id}`' has no published version.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `method_id` | `identifier` | The catalog id of the method. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/catalog/selector_invalid.md b/docs/errors/pipelex/catalog/selector_invalid.md
new file mode 100644
index 000000000..f4916592d
--- /dev/null
+++ b/docs/errors/pipelex/catalog/selector_invalid.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.catalog.selector_invalid"
+description: "The catalog selector is malformed: what the Pipelex error code pipelex.catalog.selector_invalid means, who must act and what to do."
+---
+
+# pipelex.catalog.selector_invalid
+
+**The catalog selector is malformed**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.catalog.selector_invalid` |
+| Family | [`pipelex.catalog`](../../index.md#pipelex-catalog): Saved methods in an organization's catalog. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `422` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A method selector names a saved method by its catalog id, `mt_` and its characters, and may add `@3` for one version or `@draft` for the draft. This one breaks that grammar.
+
+## What to do
+
+Read `params.reason`, then correct the selector: a catalog id as the catalog returned it, with a version number that has no leading zero or the word `draft` after the `@`.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Write the selector as a catalog id, alone or followed by '@' and a version number or 'draft', then send the request again. |
+| Any other reader | `change_input` | Pass this to the caller, whose catalog selector cannot be parsed. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The catalog selector cannot be parsed (reason: `{reason}`).
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `reason` | one of `malformed_method_id`, `malformed_version_suffix`, `suffix_on_linkage` | What is wrong: the catalog id itself, the suffix after its '@', or a suffix where the request runs the source it sends and names no version. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/catalog/update_conflict.md b/docs/errors/pipelex/catalog/update_conflict.md
new file mode 100644
index 000000000..ead00bfbd
--- /dev/null
+++ b/docs/errors/pipelex/catalog/update_conflict.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.catalog.update_conflict"
+description: "The saved method changed since it was read: what the Pipelex error code pipelex.catalog.update_conflict means, who must act and what to do."
+---
+
+# pipelex.catalog.update_conflict
+
+**The saved method changed since it was read**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.catalog.update_conflict` |
+| Family | [`pipelex.catalog`](../../index.md#pipelex-catalog): Saved methods in an organization's catalog. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `409` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+Another write changed the method or its draft between the read the update started from and the update itself, so the update stopped rather than overwrite that change.
+
+## What to do
+
+Read the method again, apply the change to what it holds now, and send the update again.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `refresh` | Read the method '`{method_id}`' again, then apply the change to its current content. |
+| Any other reader | `refresh` | Read the method '`{method_id}`' again, then apply the change to its current content. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The method '`{method_id}`' changed after it was read, so the update was not applied.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `method_id` | `identifier` | The catalog id of the method. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/codegen/drifted.md b/docs/errors/pipelex/codegen/drifted.md
new file mode 100644
index 000000000..d2878c4a2
--- /dev/null
+++ b/docs/errors/pipelex/codegen/drifted.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.codegen.drifted"
+description: "The generated code has drifted from its method: what the Pipelex error code pipelex.codegen.drifted means, who must act and what to do."
+---
+
+# pipelex.codegen.drifted
+
+**The generated code has drifted from its method**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.codegen.drifted` |
+| Family | [`pipelex.codegen`](../../index.md#pipelex-codegen): Code generated from a method. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `409` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The artifacts the check read no longer match the method they were generated from.
+
+## What to do
+
+Generate the code again from the current method, and commit what it writes.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Generate the code again from the method, then check it again. |
+| Any other reader | `change_input` | Pass this to the caller, whose generated code no longer matches its method. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The generated code no longer matches its method.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `artifacts` | list of `identifier` | The generated artifacts that no longer match. |
+
+## See also
+
+- [Codegen Projections](../../../under-the-hood/codegen-projections.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/codegen/lock_invalid.md b/docs/errors/pipelex/codegen/lock_invalid.md
new file mode 100644
index 000000000..5d57c40ff
--- /dev/null
+++ b/docs/errors/pipelex/codegen/lock_invalid.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.codegen.lock_invalid"
+description: "The codegen lock is unreadable: what the Pipelex error code pipelex.codegen.lock_invalid means, who must act and what to do."
+---
+
+# pipelex.codegen.lock_invalid
+
+**The codegen lock is unreadable**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.codegen.lock_invalid` |
+| Family | [`pipelex.codegen`](../../index.md#pipelex-codegen): Code generated from a method. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `422` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The `codegen.lock` file is malformed, or records a tree that is not safe to write.
+
+## What to do
+
+Restore the lock from version control, or generate the code again, which rewrites it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Restore the lock '`{file}`' from version control, or generate the code again to rewrite it. |
+| Any other reader | `change_input` | Pass this to the caller, whose codegen lock '`{file}`' cannot be read. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The codegen lock '`{file}`' cannot be read.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `file` | `identifier` | The lock file. |
+
+## See also
+
+- [Codegen Projections](../../../under-the-hood/codegen-projections.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/codegen/lock_not_found.md b/docs/errors/pipelex/codegen/lock_not_found.md
new file mode 100644
index 000000000..3b9bfe3fe
--- /dev/null
+++ b/docs/errors/pipelex/codegen/lock_not_found.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.codegen.lock_not_found"
+description: "No codegen lock in this directory: what the Pipelex error code pipelex.codegen.lock_not_found means, who must act and what to do."
+---
+
+# pipelex.codegen.lock_not_found
+
+**No codegen lock in this directory**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.codegen.lock_not_found` |
+| Family | [`pipelex.codegen`](../../index.md#pipelex-codegen): Code generated from a method. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `404` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The directory checked has no `codegen.lock`, so it holds no code generated from a method.
+
+## What to do
+
+Run the check on the directory codegen wrote, or generate the code first.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Check the directory codegen wrote, or generate the code into '`{path}`' first. |
+| Any other reader | `change_input` | Pass this to the caller, whose directory '`{path}`' holds no codegen lock. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The directory '`{path}`' holds no codegen lock.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `path` | `identifier` | The directory checked. |
+
+## See also
+
+- [Codegen Projections](../../../under-the-hood/codegen-projections.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/codegen/lock_unsupported.md b/docs/errors/pipelex/codegen/lock_unsupported.md
new file mode 100644
index 000000000..46eb4ea19
--- /dev/null
+++ b/docs/errors/pipelex/codegen/lock_unsupported.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.codegen.lock_unsupported"
+description: "The codegen lock needs a newer Pipelex: what the Pipelex error code pipelex.codegen.lock_unsupported means, who must act and what to do."
+---
+
+# pipelex.codegen.lock_unsupported
+
+**The codegen lock needs a newer Pipelex**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.codegen.lock_unsupported` |
+| Family | [`pipelex.codegen`](../../index.md#pipelex-codegen): Code generated from a method. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The lock was written by a newer Pipelex, in a format this runtime does not read.
+
+## What to do
+
+If you run the runtime, upgrade Pipelex. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `upgrade` | Upgrade Pipelex to a version that reads the codegen lock format `{lock_version}`. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The codegen lock was written in the format version `{lock_version}`, which this Pipelex does not read.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `lock_version` | `integer` | The format version the lock was written in. |
+
+## See also
+
+- [Codegen Projections](../../../under-the-hood/codegen-projections.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/codegen/output_conflict.md b/docs/errors/pipelex/codegen/output_conflict.md
new file mode 100644
index 000000000..ed7897869
--- /dev/null
+++ b/docs/errors/pipelex/codegen/output_conflict.md
@@ -0,0 +1,55 @@
+---
+title: "pipelex.codegen.output_conflict"
+description: "Codegen will not write there: what the Pipelex error code pipelex.codegen.output_conflict means, who must act and what to do."
+---
+
+# pipelex.codegen.output_conflict
+
+**Codegen will not write there**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.codegen.output_conflict` |
+| Family | [`pipelex.codegen`](../../index.md#pipelex-codegen): Code generated from a method. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `409` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A file codegen does not own sits at the target, or the target lies outside the output root, is not a file, or is a symbolic link.
+
+## What to do
+
+Point codegen at a directory of its own, or remove what sits at the path, then generate again.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Generate into a directory codegen owns, or move what sits at '`{path}`' out of the way. |
+| Any other reader | `change_input` | Pass this to the caller, whose codegen target '`{path}`' holds something codegen will not overwrite. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> Codegen will not write to '`{path}`' (reason: `{reason}`).
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `path` | `identifier` | The path codegen would write. |
+| `reason` | one of `unowned_file`, `escapes_root`, `not_a_file`, `symlink` | Why codegen will not write there: a file it does not own sits there, the path lies outside the output root, is not a file, or is a symbolic link. |
+
+## See also
+
+- [Codegen Projections](../../../under-the-hood/codegen-projections.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/config/credential_missing.md b/docs/errors/pipelex/config/credential_missing.md
new file mode 100644
index 000000000..035badf07
--- /dev/null
+++ b/docs/errors/pipelex/config/credential_missing.md
@@ -0,0 +1,55 @@
+---
+title: "pipelex.config.credential_missing"
+description: "An inference backend has no credential: what the Pipelex error code pipelex.config.credential_missing means, who must act and what to do."
+---
+
+# pipelex.config.credential_missing
+
+**An inference backend has no credential**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.config.credential_missing` |
+| Family | [`pipelex.config`](../../index.md#pipelex-config): The runtime's own configuration. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A key or a credential file that an inference backend needs is absent.
+
+## What to do
+
+If you run the runtime, set the backend's key in its environment or its secrets, or disable the backend. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `check_credentials` | Set the credential '`{variable}`' of the backend '`{backend}`', then restart the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> An inference backend of the runtime has no credential.
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `backend` | `identifier` (operator-only) | The inference backend that lacks its credential. |
+| `variable` | `identifier` (operator-only) | The variable or the file that should hold the credential. |
+
+## See also
+
+- [Inference Backend Plugins](../../../under-the-hood/inference-backend-plugins.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/config/credential_refused.md b/docs/errors/pipelex/config/credential_refused.md
new file mode 100644
index 000000000..637f79dc0
--- /dev/null
+++ b/docs/errors/pipelex/config/credential_refused.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.config.credential_refused"
+description: "A service refused the configured credential: what the Pipelex error code pipelex.config.credential_refused means, who must act and what to do."
+---
+
+# pipelex.config.credential_refused
+
+**A service refused the configured credential**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.config.credential_refused` |
+| Family | [`pipelex.config`](../../index.md#pipelex-config): The runtime's own configuration. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A service that is not an inference provider, such as a log sink or a storage, refused the deployment's credential. An inference provider refusing its key is `provider.credential_refused` instead.
+
+## What to do
+
+If you run the runtime, renew or correct the credential. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `check_credentials` | Check the credential the `{surface}` configuration holds for the service '`{service}`'. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> A service the runtime depends on refused the credential it is configured with.
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `surface` | one of `log_sink`, `storage` (operator-only) | The part of the configuration that holds the credential. |
+| `service` | `identifier` (operator-only) | The service that refused it. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/config/dependency_missing.md b/docs/errors/pipelex/config/dependency_missing.md
new file mode 100644
index 000000000..a973acbcd
--- /dev/null
+++ b/docs/errors/pipelex/config/dependency_missing.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.config.dependency_missing"
+description: "An optional dependency is not installed: what the Pipelex error code pipelex.config.dependency_missing means, who must act and what to do."
+---
+
+# pipelex.config.dependency_missing
+
+**An optional dependency is not installed**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.config.dependency_missing` |
+| Family | [`pipelex.config`](../../index.md#pipelex-config): The runtime's own configuration. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A Python extra, an SDK or a program such as `plxt` that the configuration needs is not installed.
+
+## What to do
+
+If you run the runtime, install Pipelex with the extra its logs name. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `fix_configuration` | Install '`{dependency}`', which the extra '`{extra}`' provides, then restart the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> An optional dependency that the runtime's configuration needs is not installed.
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `dependency` | `identifier` (operator-only) | The package, the SDK or the program that is missing. |
+| `extra` | `identifier` (operator-only) | The Pipelex extra that provides it. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/config/file_missing.md b/docs/errors/pipelex/config/file_missing.md
new file mode 100644
index 000000000..2f679926c
--- /dev/null
+++ b/docs/errors/pipelex/config/file_missing.md
@@ -0,0 +1,55 @@
+---
+title: "pipelex.config.file_missing"
+description: "A configuration file is missing: what the Pipelex error code pipelex.config.file_missing means, who must act and what to do."
+---
+
+# pipelex.config.file_missing
+
+**A configuration file is missing**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.config.file_missing` |
+| Family | [`pipelex.config`](../../index.md#pipelex-config): The runtime's own configuration. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A configuration file, or a key file, that the runtime needs is absent or cannot be loaded.
+
+## What to do
+
+If you run the runtime, restore the file its logs name, or write the default configuration with `pipelex init`. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `fix_configuration` | Create or restore the file '`{file}`' of the `{surface}` configuration, then restart the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> A configuration file the runtime needs is missing.
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `surface` | `identifier` (operator-only) | The part of the configuration the file belongs to. |
+| `file` | `identifier` (operator-only) | The file that is missing. |
+
+## See also
+
+- [Init Commands](../../../tools/cli/init.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/config/invalid.md b/docs/errors/pipelex/config/invalid.md
new file mode 100644
index 000000000..21400397a
--- /dev/null
+++ b/docs/errors/pipelex/config/invalid.md
@@ -0,0 +1,57 @@
+---
+title: "pipelex.config.invalid"
+description: "The runtime's configuration is invalid: what the Pipelex error code pipelex.config.invalid means, who must act and what to do."
+---
+
+# pipelex.config.invalid
+
+**The runtime's configuration is invalid**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.config.invalid` |
+| Family | [`pipelex.config`](../../index.md#pipelex-config): The runtime's own configuration. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A configuration file or setting parsed, but does not validate.
+
+## What to do
+
+If you run the runtime, read its logs for the file and the setting, and correct them; `pipelex doctor` checks the configuration. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `fix_configuration` | Correct the setting '`{setting}`' in the file '`{file}`' of the `{surface}` configuration, then restart the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The runtime's configuration is invalid, so it cannot serve this request.
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `surface` | `identifier` (operator-only) | The part of the configuration at fault, such as the backends, the model deck, the routing, the plugins, the storage, the telemetry, the log sinks, the libraries or the API server's settings. |
+| `file` | `identifier` (operator-only) | The configuration file that holds the setting. |
+| `setting` | `identifier` (operator-only) | The setting that does not validate. |
+
+## See also
+
+- [Configuration](../../../configuration/index.md)
+- [Doctor Command](../../../tools/cli/doctor.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/config/syntax.md b/docs/errors/pipelex/config/syntax.md
new file mode 100644
index 000000000..72d4fefa7
--- /dev/null
+++ b/docs/errors/pipelex/config/syntax.md
@@ -0,0 +1,57 @@
+---
+title: "pipelex.config.syntax"
+description: "A configuration file does not parse: what the Pipelex error code pipelex.config.syntax means, who must act and what to do."
+---
+
+# pipelex.config.syntax
+
+**A configuration file does not parse**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.config.syntax` |
+| Family | [`pipelex.config`](../../index.md#pipelex-config): The runtime's own configuration. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A configuration file is not valid TOML.
+
+## What to do
+
+If you run the runtime, open the file its logs name at the line and column given, and fix the syntax. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `fix_configuration` | Fix the TOML of the file '`{file}`' of the `{surface}` configuration at line `{line}`, column `{column}`, then restart the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> A configuration file of the runtime does not parse.
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `surface` | `identifier` (operator-only) | The part of the configuration the file belongs to. |
+| `file` | `identifier` (operator-only) | The file that does not parse. |
+| `line` | `integer` (operator-only) | The line of the first fault. |
+| `column` | `integer` (operator-only) | The column of the first fault. |
+
+## See also
+
+- [Configuration](../../../configuration/index.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/config/variable_missing.md b/docs/errors/pipelex/config/variable_missing.md
new file mode 100644
index 000000000..e0d53b72c
--- /dev/null
+++ b/docs/errors/pipelex/config/variable_missing.md
@@ -0,0 +1,55 @@
+---
+title: "pipelex.config.variable_missing"
+description: "A configuration variable is not set: what the Pipelex error code pipelex.config.variable_missing means, who must act and what to do."
+---
+
+# pipelex.config.variable_missing
+
+**A configuration variable is not set**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.config.variable_missing` |
+| Family | [`pipelex.config`](../../index.md#pipelex-config): The runtime's own configuration. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+An environment variable or a secret that the configuration refers to did not resolve.
+
+## What to do
+
+If you run the runtime, set the variable in its environment or in its secrets provider. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `fix_configuration` | Set the `{source}` variable '`{variable}`', then restart the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> A variable the runtime's configuration refers to is not set.
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `variable` | `identifier` (operator-only) | The variable that is not set. |
+| `source` | one of `env`, `secret` (operator-only) | Where the configuration reads the variable from: the environment or a secret. |
+
+## See also
+
+- [Secrets Provider Plugins](../../../under-the-hood/secrets-provider-plugins.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/connector/tool_not_in_toolset.md b/docs/errors/pipelex/connector/tool_not_in_toolset.md
new file mode 100644
index 000000000..da0636d51
--- /dev/null
+++ b/docs/errors/pipelex/connector/tool_not_in_toolset.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.connector.tool_not_in_toolset"
+description: "The tool is not in the connector's toolset: what the Pipelex error code pipelex.connector.tool_not_in_toolset means, who must act and what to do."
+---
+
+# pipelex.connector.tool_not_in_toolset
+
+**The tool is not in the connector's toolset**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.connector.tool_not_in_toolset` |
+| Family | [`pipelex.connector`](../../index.md#pipelex-connector): The toolsets a method's connectors offer a model. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `method`: the method's author acts, by changing the method |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `422` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A model called a tool that the method's connector toolset does not hold, so the runtime refused the call.
+
+## What to do
+
+Compare the tool with those `params.available` lists, then add it to the toolset or steer the prompt away from it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the method's author, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_method` | Add the tool '`{tool}`' to the method's toolset, or steer the prompt away from it, then run the method again. |
+| Any other reader | `contact_owner` | Ask the method's owner to add the tool '`{tool}`' to its toolset. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> A model asked for the tool '`{tool}`', which the method's toolset does not hold.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `tool` | `identifier` | The tool the model asked for. |
+| `available` | list of `identifier` | The tools the toolset holds. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/deployment/custom_code_requires_sandbox.md b/docs/errors/pipelex/deployment/custom_code_requires_sandbox.md
new file mode 100644
index 000000000..ac86fffba
--- /dev/null
+++ b/docs/errors/pipelex/deployment/custom_code_requires_sandbox.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.deployment.custom_code_requires_sandbox"
+description: "Custom code needs a sandbox-hosted deployment: what the Pipelex error code pipelex.deployment.custom_code_requires_sandbox means, who must act and what to do."
+---
+
+# pipelex.deployment.custom_code_requires_sandbox
+
+**Custom code needs a sandbox-hosted deployment**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.deployment.custom_code_requires_sandbox` |
+| Family | [`pipelex.deployment`](../../index.md#pipelex-deployment): The policies of a runner deployment. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `501` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The method ships Python code of its own, and this deployment runs a method's own code only inside the Daytona sandbox, which it does not have.
+
+## What to do
+
+If you run the runtime, configure the Daytona sandbox for custom code. Otherwise, run the method on a runtime that allows its code, or ask its owner for a version without Python.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `fix_configuration` | Configure the Daytona sandbox on this deployment, so that it can run the method's own code. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The method ships Python code in its `{origin}`, and this deployment runs none outside the Daytona sandbox.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `origin` | one of `bundle`, `package` | Where the method ships its code: in its bundle or in its package. |
+
+## See also
+
+- [PipeFunc Requirements](../../../under-the-hood/pipe-func-requirements.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/deployment/orchestration_override_forbidden.md b/docs/errors/pipelex/deployment/orchestration_override_forbidden.md
new file mode 100644
index 000000000..e13ac0c7a
--- /dev/null
+++ b/docs/errors/pipelex/deployment/orchestration_override_forbidden.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.deployment.orchestration_override_forbidden"
+description: "This deployment does not allow choosing the orchestration mode: what the Pipelex error code pipelex.deployment.orchestration_override_forbidden means, who must act and what to do."
+---
+
+# pipelex.deployment.orchestration_override_forbidden
+
+**This deployment does not allow choosing the orchestration mode**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.deployment.orchestration_override_forbidden` |
+| Family | [`pipelex.deployment`](../../index.md#pipelex-deployment): The policies of a runner deployment. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `422` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The deployment's policy fixes the orchestration mode, so a request may not choose one.
+
+## What to do
+
+Leave the orchestration mode out of the request, and let the deployment run it in its own mode.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Send the request without choosing an orchestration mode. |
+| Any other reader | `change_input` | Pass this to the caller, whose request chooses an orchestration mode this deployment fixes. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> This deployment does not let a request choose its orchestration mode, and this one asks for '`{requested_mode}`'.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `requested_mode` | `identifier` | The orchestration mode the request asks for. |
+
+## See also
+
+- [Orchestrator Plugins](../../../under-the-hood/orchestrator-plugins.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/deployment/python_structures_refused.md b/docs/errors/pipelex/deployment/python_structures_refused.md
new file mode 100644
index 000000000..be98037d1
--- /dev/null
+++ b/docs/errors/pipelex/deployment/python_structures_refused.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.deployment.python_structures_refused"
+description: "Python structure classes are not allowed here: what the Pipelex error code pipelex.deployment.python_structures_refused means, who must act and what to do."
+---
+
+# pipelex.deployment.python_structures_refused
+
+**Python structure classes are not allowed here**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.deployment.python_structures_refused` |
+| Family | [`pipelex.deployment`](../../index.md#pipelex-deployment): The policies of a runner deployment. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `method`: the method's author acts, by changing the method |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `422` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The method declares its structures as Python classes, which no hosted runner imports. Concepts declared in the method itself replace them.
+
+## What to do
+
+Rewrite each structure the files in `params.files` declare as a concept with its fields in the method, then run it again.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the method's author, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_method` | Declare the structures as concepts in the method in place of Python classes, then run it again. |
+| Any other reader | `contact_owner` | Ask the method's owner to declare its structures as concepts in the method. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The method declares structures as Python classes, which this runner does not import.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `files` | list of `identifier` | The method's files that declare structures as Python classes. |
+
+## See also
+
+- [Python StructuredContent Classes](../../../building-methods/concepts/python-classes.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/deployment/token_claims_invalid.md b/docs/errors/pipelex/deployment/token_claims_invalid.md
new file mode 100644
index 000000000..4e24d7e22
--- /dev/null
+++ b/docs/errors/pipelex/deployment/token_claims_invalid.md
@@ -0,0 +1,55 @@
+---
+title: "pipelex.deployment.token_claims_invalid"
+description: "The token's claims cannot be used: what the Pipelex error code pipelex.deployment.token_claims_invalid means, who must act and what to do."
+---
+
+# pipelex.deployment.token_claims_invalid
+
+**The token's claims cannot be used**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.deployment.token_claims_invalid` |
+| Family | [`pipelex.deployment`](../../index.md#pipelex-deployment): The policies of a runner deployment. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A verified token carries a user id the runner cannot use, so the token's issuer is misconfigured.
+
+## What to do
+
+If you run the runtime, correct the claims its token issuer writes. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `fix_configuration` | Correct the claim '`{claim}`' (`{reason}`) that the token issuer writes, then send the request again. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The request's verified token carries claims this runner cannot use.
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `claim` | `identifier` (operator-only) | The claim at fault. |
+| `reason` | one of `missing`, `unsafe`, `reserved` (operator-only) | What is wrong with the claim: it is missing, unsafe as an identifier, or reserved. |
+
+## See also
+
+- [API Server Configuration](../../../api-server/configuration.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/docgen/content_unprintable.md b/docs/errors/pipelex/docgen/content_unprintable.md
new file mode 100644
index 000000000..a0bca05c5
--- /dev/null
+++ b/docs/errors/pipelex/docgen/content_unprintable.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.docgen.content_unprintable"
+description: "The document's content cannot be printed: what the Pipelex error code pipelex.docgen.content_unprintable means, who must act and what to do."
+---
+
+# pipelex.docgen.content_unprintable
+
+**The document's content cannot be printed**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.docgen.content_unprintable` |
+| Family | [`pipelex.docgen`](../../index.md#pipelex-docgen): The document engines that print a PipeDocGen step's documents. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `422` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The run's data holds something the print engine cannot lay out or decode.
+
+## What to do
+
+Read `params.reason`, then shorten, resize or replace the content, and run the method again.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Change the input that fills '`{element}`', then run the method again. |
+| Any other reader | `change_input` | Pass this to the caller, whose inputs hold something the document cannot print. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The run's data holds something the print engine cannot lay out (reason: `{reason}`, in '`{element}`').
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `reason` | one of `too_tall_for_page`, `image_unreadable`, `image_too_large`, `image_empty`, `html_too_large` | What cannot be printed: an element taller than a page, an image that cannot be read, is too large or is empty, or HTML past its size limit. |
+| `element` | `identifier` | The element of the document that holds it. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/docgen/engine_unavailable.md b/docs/errors/pipelex/docgen/engine_unavailable.md
new file mode 100644
index 000000000..5b2392356
--- /dev/null
+++ b/docs/errors/pipelex/docgen/engine_unavailable.md
@@ -0,0 +1,56 @@
+---
+title: "pipelex.docgen.engine_unavailable"
+description: "No document engine prints this here: what the Pipelex error code pipelex.docgen.engine_unavailable means, who must act and what to do."
+---
+
+# pipelex.docgen.engine_unavailable
+
+**No document engine prints this here**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.docgen.engine_unavailable` |
+| Family | [`pipelex.docgen`](../../index.md#pipelex-docgen): The document engines that print a PipeDocGen step's documents. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `501` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The engine that prints a PipeDocGen step's format, or a system library it needs, is not installed, declared or enabled in this runtime.
+
+## What to do
+
+If you run the runtime, install and enable the engine. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `fix_configuration` | Install or enable the engine '`{engine}`' (`{gap}`), then restart the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> No document engine prints the format '`{format}`' in this runtime.
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `engine` | `identifier` (operator-only) | The document engine the step needs. |
+| `format` | one of `pdf`, `xlsx`, `docx`, `pptx` | The format the step prints. |
+| `gap` | `identifier` (operator-only) | What is missing: the engine, a system library it needs, its declaration or its enablement. |
+
+## See also
+
+- [Document Engine Plugins](../../../under-the-hood/document-engine-plugins.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/docgen/print_timeout.md b/docs/errors/pipelex/docgen/print_timeout.md
new file mode 100644
index 000000000..28fe8da1f
--- /dev/null
+++ b/docs/errors/pipelex/docgen/print_timeout.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.docgen.print_timeout"
+description: "Printing the document took too long: what the Pipelex error code pipelex.docgen.print_timeout means, who must act and what to do."
+---
+
+# pipelex.docgen.print_timeout
+
+**Printing the document took too long**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.docgen.print_timeout` |
+| Family | [`pipelex.docgen`](../../index.md#pipelex-docgen): The document engines that print a PipeDocGen step's documents. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `runtime`: nobody could have acted beforehand, so whoever made the call waits, retries or reports the problem |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `yes`: repeating the operation may succeed, after `retry_after` seconds when the problem gives it |
+| HTTP status | `504` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The print, or a resource it read, ran past its limit and was stopped.
+
+## What to do
+
+Run the method again. If the print keeps running past its limit, make the document lighter, or report it to whoever runs the runtime.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever made the call, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `retry` | Run the method again, since the print may finish within its limit. |
+| Any other reader | `retry` | Run the method again, since the print may finish within its limit. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> Printing the document ran past its limit of `{limit}` seconds and was stopped.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `limit` | `seconds` | The time the print was allowed. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/docgen/resource_refused.md b/docs/errors/pipelex/docgen/resource_refused.md
new file mode 100644
index 000000000..addb66450
--- /dev/null
+++ b/docs/errors/pipelex/docgen/resource_refused.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.docgen.resource_refused"
+description: "The document names a file it may not read: what the Pipelex error code pipelex.docgen.resource_refused means, who must act and what to do."
+---
+
+# pipelex.docgen.resource_refused
+
+**The document names a file it may not read**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.docgen.resource_refused` |
+| Family | [`pipelex.docgen`](../../index.md#pipelex-docgen): The document engines that print a PipeDocGen step's documents. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `method`: the method's author acts, by changing the method |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `422` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The print engine's fetcher refused a resource the document names, by policy. A plain `http://` URL breaks a transport rule rather than a security one, so its refusal records no security event.
+
+## What to do
+
+Use an absolute `https://` URL, embed the file as a data URL that decodes, or use a font the engine provides.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the method's author, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_method` | Name the file by an absolute https URL or embed it, then run the method again. |
+| Any other reader | `contact_owner` | Ask the method's owner to fix the file its document names. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The document names a file the print engine may not read (reason: `{reason}`).
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `reason` | one of `relative_url`, `plain_http_url`, `undecodable_data_url`, `unknown_font` | Why the file was refused: a relative URL, a plain http URL, a data URL that does not decode, or a font the engine does not know. |
+
+## See also
+
+- [Document Engine Plugins](../../../under-the-hood/document-engine-plugins.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/docgen/template_invalid.md b/docs/errors/pipelex/docgen/template_invalid.md
new file mode 100644
index 000000000..c8a5311b2
--- /dev/null
+++ b/docs/errors/pipelex/docgen/template_invalid.md
@@ -0,0 +1,56 @@
+---
+title: "pipelex.docgen.template_invalid"
+description: "The document template cannot be used: what the Pipelex error code pipelex.docgen.template_invalid means, who must act and what to do."
+---
+
+# pipelex.docgen.template_invalid
+
+**The document template cannot be used**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.docgen.template_invalid` |
+| Family | [`pipelex.docgen`](../../index.md#pipelex-docgen): The document engines that print a PipeDocGen step's documents. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `method`: the method's author acts, by changing the method |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `422` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A PipeDocGen step's template cannot be used to print its document.
+
+## What to do
+
+Read `params.finding`, then fix the template, or the inputs the step maps into it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the method's author, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_method` | Fix the template '`{template}`', then run the method again. |
+| Any other reader | `contact_owner` | Ask the method's owner to fix the template '`{template}`'. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The document template '`{template}`' cannot be used (reason: `{reason}`): `{finding}`
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `template` | `identifier` | The template. |
+| `reason` | one of `unreadable`, `does_not_fit`, `check_failed`, `value_unsupported` | Why it cannot be used: it is not a readable file of its format, it does not fit the step's inputs, it fails the engine's check, or it maps a value no cell can take. |
+| `finding` | `caller_text` | What the engine found, about the method's own template. |
+
+## See also
+
+- [Document Engine Plugins](../../../under-the-hood/document-engine-plugins.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/docgen/template_warning.md b/docs/errors/pipelex/docgen/template_warning.md
new file mode 100644
index 000000000..2161b153c
--- /dev/null
+++ b/docs/errors/pipelex/docgen/template_warning.md
@@ -0,0 +1,55 @@
+---
+title: "pipelex.docgen.template_warning"
+description: "The document template may be faulty: what the Pipelex error code pipelex.docgen.template_warning means, who must act and what to do."
+---
+
+# pipelex.docgen.template_warning
+
+**The document template may be faulty**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.docgen.template_warning` |
+| Family | [`pipelex.docgen`](../../index.md#pipelex-docgen): The document engines that print a PipeDocGen step's documents. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `method`: the method's author acts, by changing the method |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | none (warning) |
+| Raised as | an item of a validate verdict's `warnings`, which never makes a method invalid |
+
+## What it means
+
+An advisory: the check of a PipeDocGen step's template found a likely fault, which does not stop the method from validating.
+
+## What to do
+
+Read `params.finding`, check the template, and fix it if the finding is right.
+
+## Next steps
+
+A warning carries no [step](https://mthds.ai/latest/spec/protocol/#next-steps) of its own, since it is an item of a validate verdict, so its reader takes one of the code's steps: the first when the reader is the domain's actor, the method's author, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_method` | Check the template '`{template}`', and fix it if the finding is right. |
+| Any other reader | `contact_owner` | Ask the method's owner to check the template '`{template}`'. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The document template '`{template}`' may be faulty: `{finding}`
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `template` | `identifier` | The template. |
+| `finding` | `caller_text` | What the check found, about the method's own template. |
+
+## See also
+
+- [Document Engine Plugins](../../../under-the-hood/document-engine-plugins.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/erasure/incomplete.md b/docs/errors/pipelex/erasure/incomplete.md
new file mode 100644
index 000000000..d80b68a5f
--- /dev/null
+++ b/docs/errors/pipelex/erasure/incomplete.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.erasure.incomplete"
+description: "The erasure left data behind: what the Pipelex error code pipelex.erasure.incomplete means, who must act and what to do."
+---
+
+# pipelex.erasure.incomplete
+
+**The erasure left data behind**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.erasure.incomplete` |
+| Family | [`pipelex.erasure`](../../index.md#pipelex-erasure): The erasure of runs and methods. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `runtime`: nobody could have acted beforehand, so whoever made the call waits, retries or reports the problem |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `yes`: repeating the operation may succeed, after `retry_after` seconds when the problem gives it |
+| HTTP status | `503` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A purge of a run, a method, a method's version or a workflow's history did not complete, so part of its data remains. Requesting the erasure again resumes it.
+
+## What to do
+
+Request the erasure again. If it keeps failing, report it to whoever runs the runtime, since data that should be gone remains.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever made the call, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `retry` | Request the erasure of the `{resource}` '`{id}`' again. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The erasure of the `{resource}` '`{id}`' did not complete, and some of its data remains.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `resource` | one of `run`, `method`, `method_version`, `workflow` | What was being erased: a run, a method, a method's version or a workflow's history. |
+| `id` | `identifier` | The id of what was being erased. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/org/already_exists.md b/docs/errors/pipelex/org/already_exists.md
new file mode 100644
index 000000000..45bcfaebe
--- /dev/null
+++ b/docs/errors/pipelex/org/already_exists.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.org.already_exists"
+description: "The organization's resource already exists: what the Pipelex error code pipelex.org.already_exists means, who must act and what to do."
+---
+
+# pipelex.org.already_exists
+
+**The organization's resource already exists**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.org.already_exists` |
+| Family | [`pipelex.org`](../../index.md#pipelex-org): Organizations, their members, their API keys and their promo codes. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `409` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A member, an invitation, a promo code and an API key's name are each unique, and the one the request gives is taken.
+
+## What to do
+
+Use the one that exists, or choose another name, code or address.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Use the `{resource}` that exists, or choose another, then send the request again. |
+| Any other reader | `change_input` | Pass this to the caller, whose `{resource}` already exists. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The `{resource}` the request would create already exists.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `resource` | one of `member`, `invitation`, `promo_code`, `api_key_label` | The kind of resource that already exists. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/org/mismatch.md b/docs/errors/pipelex/org/mismatch.md
new file mode 100644
index 000000000..377785618
--- /dev/null
+++ b/docs/errors/pipelex/org/mismatch.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.org.mismatch"
+description: "The reference belongs to another organization: what the Pipelex error code pipelex.org.mismatch means, who must act and what to do."
+---
+
+# pipelex.org.mismatch
+
+**The reference belongs to another organization**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.org.mismatch` |
+| Family | [`pipelex.org`](../../index.md#pipelex-org): Organizations, their members, their API keys and their promo codes. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `403` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A well-formed reference names an organization other than the one the caller acts for.
+
+## What to do
+
+Check which organization the request acts for, and use a reference that belongs to it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Use a `{reference}` of the organization the request acts for, then send the request again. |
+| Any other reader | `change_input` | Pass this to the caller, whose `{reference}` belongs to another organization. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The request's `{reference}` belongs to an organization other than the caller's.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `reference` | one of `organization_id`, `storage_uri` | The kind of reference that names another organization: an organization's id or a storage address. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/org/not_found.md b/docs/errors/pipelex/org/not_found.md
new file mode 100644
index 000000000..f63312799
--- /dev/null
+++ b/docs/errors/pipelex/org/not_found.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.org.not_found"
+description: "The organization's resource does not exist: what the Pipelex error code pipelex.org.not_found means, who must act and what to do."
+---
+
+# pipelex.org.not_found
+
+**The organization's resource does not exist**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.org.not_found` |
+| Family | [`pipelex.org`](../../index.md#pipelex-org): Organizations, their members, their API keys and their promo codes. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `404` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The organization, member, invitation, API key, user or promo record the request names does not exist.
+
+## What to do
+
+Check the identifier the request gives, and list what the organization holds to find the right one.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Name a `{resource}` that exists, then send the request again. |
+| Any other reader | `change_input` | Pass this to the caller, whose request names a `{resource}` that does not exist. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The `{resource}` the request names does not exist.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `resource` | one of `organization`, `member`, `invitation`, `api_key`, `user`, `promo_code`, `promo_redemption`, `flag_target` | The kind of resource the request names. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/org/not_manageable.md b/docs/errors/pipelex/org/not_manageable.md
new file mode 100644
index 000000000..09616f390
--- /dev/null
+++ b/docs/errors/pipelex/org/not_manageable.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.org.not_manageable"
+description: "The resource cannot be changed this way in its state: what the Pipelex error code pipelex.org.not_manageable means, who must act and what to do."
+---
+
+# pipelex.org.not_manageable
+
+**The resource cannot be changed this way in its state**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.org.not_manageable` |
+| Family | [`pipelex.org`](../../index.md#pipelex-org): Organizations, their members, their API keys and their promo codes. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `409` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The resource's state refuses the change: a personal or an internal organization, the last administrator of an organization, a subject with no directory identity, or a promo code's cap set below the redemptions it already has.
+
+## What to do
+
+Read `params.reason`, then change the request, for instance by naming another administrator before removing the last one.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Change the resource another way, or bring it into a state that allows this change first. |
+| Any other reader | `change_input` | Pass this to the caller, whose change the resource's state does not allow. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The resource cannot be changed this way in its current state (reason: `{reason}`).
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `reason` | `identifier` | What about the resource's state refuses the change. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/org/promo_credit_pending.md b/docs/errors/pipelex/org/promo_credit_pending.md
new file mode 100644
index 000000000..50b1dfb1d
--- /dev/null
+++ b/docs/errors/pipelex/org/promo_credit_pending.md
@@ -0,0 +1,49 @@
+---
+title: "pipelex.org.promo_credit_pending"
+description: "The promo credit is pending: what the Pipelex error code pipelex.org.promo_credit_pending means, who must act and what to do."
+---
+
+# pipelex.org.promo_credit_pending
+
+**The promo credit is pending**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.org.promo_credit_pending` |
+| Family | [`pipelex.org`](../../index.md#pipelex-org): Organizations, their members, their API keys and their promo codes. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `runtime`: nobody could have acted beforehand, so whoever made the call waits, retries or reports the problem |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `502` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The redemption is recorded, but applying its credit failed. A repair sweep applies it later, so redeeming the code again is neither needed nor possible.
+
+## What to do
+
+Wait, then check the organization's credit. If the credit has not arrived after a day, report it to whoever runs the runtime.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever made the call, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `wait` | Wait for the credit to reach the organization, without redeeming the code again. |
+| Any other reader | `wait` | Wait for the credit to reach the organization, without redeeming the code again. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The promo code was redeemed, and its credit has not been applied yet.
+
+## Parameters
+
+This code declares no parameters, so its problems carry no `params`.
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/org/promo_invalid.md b/docs/errors/pipelex/org/promo_invalid.md
new file mode 100644
index 000000000..43253bc7e
--- /dev/null
+++ b/docs/errors/pipelex/org/promo_invalid.md
@@ -0,0 +1,49 @@
+---
+title: "pipelex.org.promo_invalid"
+description: "The promo code cannot be redeemed: what the Pipelex error code pipelex.org.promo_invalid means, who must act and what to do."
+---
+
+# pipelex.org.promo_invalid
+
+**The promo code cannot be redeemed**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.org.promo_invalid` |
+| Family | [`pipelex.org`](../../index.md#pipelex-org): Organizations, their members, their API keys and their promo codes. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `422` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The promo code is not one this organization can redeem. The reason is withheld on purpose, so that a code cannot be guessed by trying.
+
+## What to do
+
+Check the promo code as it was given to you, and ask whoever gave it for one that is valid.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Check the promo code, then redeem one that is valid. |
+| Any other reader | `change_input` | Pass this to the caller, whose promo code cannot be redeemed. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The promo code cannot be redeemed.
+
+## Parameters
+
+This code declares no parameters, so its problems carry no `params`.
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/org/required.md b/docs/errors/pipelex/org/required.md
new file mode 100644
index 000000000..cd6858d89
--- /dev/null
+++ b/docs/errors/pipelex/org/required.md
@@ -0,0 +1,49 @@
+---
+title: "pipelex.org.required"
+description: "An organization is required: what the Pipelex error code pipelex.org.required means, who must act and what to do."
+---
+
+# pipelex.org.required
+
+**An organization is required**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.org.required` |
+| Family | [`pipelex.org`](../../index.md#pipelex-org): Organizations, their members, their API keys and their promo codes. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `account`: the account's owner acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `403` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The caller acts for no organization, and the route acts on an organization's resources.
+
+## What to do
+
+Sign in to an organization, or use an API key that belongs to one, then send the request again.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the account's owner, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `check_account` | Act for an organization, by joining or creating one, then send the request again. |
+| Any other reader | `contact_owner` | Ask the account's owner to add you to an organization. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> This operation acts on an organization, and the request acts for none.
+
+## Parameters
+
+This code declares no parameters, so its problems carry no `params`.
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/plugin/api_mismatch.md b/docs/errors/pipelex/plugin/api_mismatch.md
new file mode 100644
index 000000000..d73d12893
--- /dev/null
+++ b/docs/errors/pipelex/plugin/api_mismatch.md
@@ -0,0 +1,56 @@
+---
+title: "pipelex.plugin.api_mismatch"
+description: "A plugin targets another plugin API: what the Pipelex error code pipelex.plugin.api_mismatch means, who must act and what to do."
+---
+
+# pipelex.plugin.api_mismatch
+
+**A plugin targets another plugin API**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.plugin.api_mismatch` |
+| Family | [`pipelex.plugin`](../../index.md#pipelex-plugin): The plugins installed in the runtime. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+An installed plugin was built for another version of the plugin contract than the one this runtime implements.
+
+## What to do
+
+If you run the runtime, upgrade the plugin or Pipelex so that both target the same plugin API. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `upgrade` | Upgrade the plugin '`{plugin}`', built for the plugin API `{targets_api}`, or Pipelex, which supports the plugin API `{supported_api}`. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> An installed plugin targets a plugin API this runtime does not support.
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `plugin` | `identifier` (operator-only) | The plugin. |
+| `targets_api` | `integer` (operator-only) | The plugin API version the plugin was built for. |
+| `supported_api` | `integer` (operator-only) | The plugin API version this runtime supports. |
+
+## See also
+
+- [Inference Backend Plugins](../../../under-the-hood/inference-backend-plugins.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/plugin/broken.md b/docs/errors/pipelex/plugin/broken.md
new file mode 100644
index 000000000..51f930be5
--- /dev/null
+++ b/docs/errors/pipelex/plugin/broken.md
@@ -0,0 +1,55 @@
+---
+title: "pipelex.plugin.broken"
+description: "A plugin failed to load: what the Pipelex error code pipelex.plugin.broken means, who must act and what to do."
+---
+
+# pipelex.plugin.broken
+
+**A plugin failed to load**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.plugin.broken` |
+| Family | [`pipelex.plugin`](../../index.md#pipelex-plugin): The plugins installed in the runtime. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+An installed plugin raised while it was loading or registering, or breaks the rules a plugin's package follows.
+
+## What to do
+
+If you run the runtime, read its logs for the plugin, then upgrade, fix or uninstall it. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `fix_configuration` | Fix or uninstall the plugin '`{plugin}`' (`{reason}`), then restart the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> An installed plugin failed to load.
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `plugin` | `identifier` (operator-only) | The plugin that failed. |
+| `reason` | `identifier` (operator-only) | What failed: its loading, its registration, or a rule its package breaks. |
+
+## See also
+
+- [Inference Backend Plugins](../../../under-the-hood/inference-backend-plugins.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/plugin/conflict.md b/docs/errors/pipelex/plugin/conflict.md
new file mode 100644
index 000000000..f5b736d54
--- /dev/null
+++ b/docs/errors/pipelex/plugin/conflict.md
@@ -0,0 +1,56 @@
+---
+title: "pipelex.plugin.conflict"
+description: "Two plugins claim the same slot: what the Pipelex error code pipelex.plugin.conflict means, who must act and what to do."
+---
+
+# pipelex.plugin.conflict
+
+**Two plugins claim the same slot**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.plugin.conflict` |
+| Family | [`pipelex.plugin`](../../index.md#pipelex-plugin): The plugins installed in the runtime. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+Two installed plugins register the same name, or claim the same process-wide slot.
+
+## What to do
+
+If you run the runtime, keep only one of the two plugins. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `fix_configuration` | Uninstall '`{plugin}`' or '`{other_plugin}`', which both claim '`{slot}`', then restart the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> Two installed plugins claim the same slot.
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `plugin` | `identifier` (operator-only) | One of the two plugins. |
+| `other_plugin` | `identifier` (operator-only) | The other plugin. |
+| `slot` | `identifier` (operator-only) | The name or the process-wide slot both claim. |
+
+## See also
+
+- [Inference Backend Plugins](../../../under-the-hood/inference-backend-plugins.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/plugin/not_found.md b/docs/errors/pipelex/plugin/not_found.md
new file mode 100644
index 000000000..564cd005d
--- /dev/null
+++ b/docs/errors/pipelex/plugin/not_found.md
@@ -0,0 +1,56 @@
+---
+title: "pipelex.plugin.not_found"
+description: "No plugin provides the configured choice: what the Pipelex error code pipelex.plugin.not_found means, who must act and what to do."
+---
+
+# pipelex.plugin.not_found
+
+**No plugin provides the configured choice**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.plugin.not_found` |
+| Family | [`pipelex.plugin`](../../index.md#pipelex-plugin): The plugins installed in the runtime. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A setting names a storage, a secrets provider, a log sink, an execution mode, an orchestrator or a validator that no installed plugin registers.
+
+## What to do
+
+If you run the runtime, install the plugin that provides the choice, or choose one of those its logs list as available. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `fix_configuration` | Install a plugin that provides '`{value}`' for the setting '`{setting}`', or choose a value an installed plugin provides. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> No installed plugin provides a choice the runtime's configuration makes.
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `setting` | `identifier` (operator-only) | The setting that makes the choice. |
+| `value` | `identifier` (operator-only) | The choice no installed plugin provides. |
+| `available` | list of `identifier` (operator-only) | The choices the installed plugins provide. |
+
+## See also
+
+- [Inference Backend Plugins](../../../under-the-hood/inference-backend-plugins.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/run/already_exists.md b/docs/errors/pipelex/run/already_exists.md
new file mode 100644
index 000000000..04f00fc57
--- /dev/null
+++ b/docs/errors/pipelex/run/already_exists.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.run.already_exists"
+description: "A run with this id already exists: what the Pipelex error code pipelex.run.already_exists means, who must act and what to do."
+---
+
+# pipelex.run.already_exists
+
+**A run with this id already exists**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.run.already_exists` |
+| Family | [`pipelex.run`](../../index.md#pipelex-run): Pipelex's extensions to runs. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `409` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The caller chose the run's id, which Pipelex allows as an extension of the protocol, whose run id is always the runner's, and a run already holds that id.
+
+## What to do
+
+Start the run with a new id, or with none so that the runner assigns it. To see the run that holds the id, read it by that id.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Start the run with another id, or with none so that the runner assigns one. |
+| Any other reader | `change_input` | Pass this to the caller, who chose the run id '`{pipeline_run_id}`', which is already taken. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> A run with the id '`{pipeline_run_id}`' already exists.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `pipeline_run_id` | `identifier` | The run id the caller chose. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/sandbox/unavailable.md b/docs/errors/pipelex/sandbox/unavailable.md
new file mode 100644
index 000000000..8d03b41f1
--- /dev/null
+++ b/docs/errors/pipelex/sandbox/unavailable.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.sandbox.unavailable"
+description: "The Daytona sandbox could not be started: what the Pipelex error code pipelex.sandbox.unavailable means, who must act and what to do."
+---
+
+# pipelex.sandbox.unavailable
+
+**The Daytona sandbox could not be started**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.sandbox.unavailable` |
+| Family | [`pipelex.sandbox`](../../index.md#pipelex-sandbox): The Daytona sandbox that runs a method's own code. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `runtime`: nobody could have acted beforehand, so whoever made the call waits, retries or reports the problem |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `yes`: repeating the operation may succeed, after `retry_after` seconds when the problem gives it |
+| HTTP status | `503` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A Daytona sandbox, or the local subprocess that stands in for it, could not be provisioned or reached. The method's own code never ran, so running the method again is safe.
+
+## What to do
+
+Run the method again after a while. If the Daytona sandbox keeps failing, report it to whoever runs the runtime.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever made the call, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `retry` | Run the method again after a while. |
+| Any other reader | `retry` | Run the method again after a while. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The Daytona sandbox that runs the method's code could not be started (backend: `{backend}`), so the code never ran.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `backend` | one of `daytona`, `subprocess` | What could not be started: a Daytona sandbox, or the local subprocess that stands in for it. |
+
+## See also
+
+- [PipeFunc Requirements](../../../under-the-hood/pipe-func-requirements.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/security/reserved_key.md b/docs/errors/pipelex/security/reserved_key.md
new file mode 100644
index 000000000..c9583ad27
--- /dev/null
+++ b/docs/errors/pipelex/security/reserved_key.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.security.reserved_key"
+description: "The request carries a reserved key: what the Pipelex error code pipelex.security.reserved_key means, who must act and what to do."
+---
+
+# pipelex.security.reserved_key
+
+**The request carries a reserved key**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.security.reserved_key` |
+| Family | [`pipelex.security`](../../index.md#pipelex-security): Pipelex's own refusals made for safety, each recorded as a security event. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `422` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+An object in the request holds a key that Pipelex's decoder would read as a class marker, such as `__class__`, `__module__` or a key starting with `__kajson`. The request is refused, and the refusal is recorded as a security event.
+
+## What to do
+
+Rename or remove each key `params.keys` lists. No input of a method needs one.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Rename or remove the reserved keys in the request, then send it again. |
+| Any other reader | `change_input` | Pass this to the caller, whose request carries reserved keys. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The request carries object keys that Pipelex's decoder reserves for its own markers.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `keys` | list of `identifier` | The reserved keys the request carries. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/security/result_outside_scope.md b/docs/errors/pipelex/security/result_outside_scope.md
new file mode 100644
index 000000000..cc56e30a5
--- /dev/null
+++ b/docs/errors/pipelex/security/result_outside_scope.md
@@ -0,0 +1,49 @@
+---
+title: "pipelex.security.result_outside_scope"
+description: "A result location lies outside the run: what the Pipelex error code pipelex.security.result_outside_scope means, who must act and what to do."
+---
+
+# pipelex.security.result_outside_scope
+
+**A result location lies outside the run**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.security.result_outside_scope` |
+| Family | [`pipelex.security`](../../index.md#pipelex-security): Pipelex's own refusals made for safety, each recorded as a security event. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `runtime`: nobody could have acted beforehand, so whoever made the call waits, retries or reports the problem |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A result location that a step reported, or that storage holds, lies outside the run's own storage scope. The runtime refuses it, and records the refusal as a security event.
+
+## What to do
+
+Report the problem to whoever runs the runtime, with the run's `pipeline_run_id`.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever made the call, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `report` | Report this to whoever runs the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> A result location lies outside the run's storage scope, so the runtime refused it.
+
+## Parameters
+
+This code declares no parameters, so its problems carry no `params`.
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/storage/grant_mismatch.md b/docs/errors/pipelex/storage/grant_mismatch.md
new file mode 100644
index 000000000..7172a6c7c
--- /dev/null
+++ b/docs/errors/pipelex/storage/grant_mismatch.md
@@ -0,0 +1,49 @@
+---
+title: "pipelex.storage.grant_mismatch"
+description: "The upload differs from its grant: what the Pipelex error code pipelex.storage.grant_mismatch means, who must act and what to do."
+---
+
+# pipelex.storage.grant_mismatch
+
+**The upload differs from its grant**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.storage.grant_mismatch` |
+| Family | [`pipelex.storage`](../../index.md#pipelex-storage): Pipelex's storage addresses and uploads. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `runtime`: nobody could have acted beforehand, so whoever made the call waits, retries or reports the problem |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `403` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The upload's size, type, metadata or headers differ from what the grant signed. A client that uploads with the grant exactly as it was handed out never meets this.
+
+## What to do
+
+Report the problem to whoever runs the runtime. If you wrote the client that uploads, send the headers the grant lists, unchanged.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever made the call, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `report` | Report this to whoever runs the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The upload differs from what its grant signed, so storage refused it.
+
+## Parameters
+
+This code declares no parameters, so its problems carry no `params`.
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/storage/grant_unusable.md b/docs/errors/pipelex/storage/grant_unusable.md
new file mode 100644
index 000000000..b3577ef67
--- /dev/null
+++ b/docs/errors/pipelex/storage/grant_unusable.md
@@ -0,0 +1,49 @@
+---
+title: "pipelex.storage.grant_unusable"
+description: "The upload grant is spent or expired: what the Pipelex error code pipelex.storage.grant_unusable means, who must act and what to do."
+---
+
+# pipelex.storage.grant_unusable
+
+**The upload grant is spent or expired**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.storage.grant_unusable` |
+| Family | [`pipelex.storage`](../../index.md#pipelex-storage): Pipelex's storage addresses and uploads. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `runtime`: nobody could have acted beforehand, so whoever made the call waits, retries or reports the problem |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `yes`: repeating the operation may succeed, after `retry_after` seconds when the problem gives it |
+| HTTP status | `403` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+An upload grant writes one file, once, before it expires. This one has expired or has already written its file, and a new grant succeeds.
+
+## What to do
+
+Request a new upload grant, and upload the file with it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever made the call, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `retry` | Ask for a new upload grant, then upload the file with it. |
+| Any other reader | `retry` | Ask for a new upload grant, then upload the file with it. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The upload grant has expired, or has already written its file.
+
+## Parameters
+
+This code declares no parameters, so its problems carry no `params`.
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/storage/not_configured.md b/docs/errors/pipelex/storage/not_configured.md
new file mode 100644
index 000000000..6630d427f
--- /dev/null
+++ b/docs/errors/pipelex/storage/not_configured.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.storage.not_configured"
+description: "This deployment serves no storage for that address: what the Pipelex error code pipelex.storage.not_configured means, who must act and what to do."
+---
+
+# pipelex.storage.not_configured
+
+**This deployment serves no storage for that address**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.storage.not_configured` |
+| Family | [`pipelex.storage`](../../index.md#pipelex-storage): Pipelex's storage addresses and uploads. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `operator`: whoever runs the runtime acts |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A storage address names a scheme for which this deployment configures no bucket.
+
+## What to do
+
+If you run the runtime, configure the storage for the scheme. Otherwise, report the problem to whoever runs it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever runs the runtime, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `fix_configuration` | Configure a storage for the scheme '`{scheme}`' on this deployment, then restart the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> This deployment serves no storage for the scheme '`{scheme}`'.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `scheme` | `identifier` | The scheme of the storage address. |
+
+## See also
+
+- [Storage Provider Plugins](../../../under-the-hood/storage-provider-plugins.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/storage/not_found.md b/docs/errors/pipelex/storage/not_found.md
new file mode 100644
index 000000000..32fc8688c
--- /dev/null
+++ b/docs/errors/pipelex/storage/not_found.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.storage.not_found"
+description: "A stored file is gone: what the Pipelex error code pipelex.storage.not_found means, who must act and what to do."
+---
+
+# pipelex.storage.not_found
+
+**A stored file is gone**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.storage.not_found` |
+| Family | [`pipelex.storage`](../../index.md#pipelex-storage): Pipelex's storage addresses and uploads. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `runtime`: nobody could have acted beforehand, so whoever made the call waits, retries or reports the problem |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A file the run wrote, or that the runtime handed out, is no longer in storage. A caller's own reference to something that does not exist is `input.reference_not_found` instead.
+
+## What to do
+
+Report the problem to whoever runs the runtime, with the run's `pipeline_run_id` when it has one.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever made the call, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `report` | Report this to whoever runs the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> A file the runtime stored is no longer in its `{scheme}` storage.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `scheme` | one of `local`, `s3`, `gcs`, `memory` | The kind of storage that no longer holds the file. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/storage/unavailable.md b/docs/errors/pipelex/storage/unavailable.md
new file mode 100644
index 000000000..4ed1cd71b
--- /dev/null
+++ b/docs/errors/pipelex/storage/unavailable.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.storage.unavailable"
+description: "Storage is unavailable: what the Pipelex error code pipelex.storage.unavailable means, who must act and what to do."
+---
+
+# pipelex.storage.unavailable
+
+**Storage is unavailable**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.storage.unavailable` |
+| Family | [`pipelex.storage`](../../index.md#pipelex-storage): Pipelex's storage addresses and uploads. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `runtime`: nobody could have acted beforehand, so whoever made the call waits, retries or reports the problem |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `yes`: repeating the operation may succeed, after `retry_after` seconds when the problem gives it |
+| HTTP status | `503` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+The storage backend failed a read or a write, which may succeed later.
+
+## What to do
+
+Send the request again after `retry_after` seconds when the problem gives it. If storage keeps failing, report it to whoever runs the runtime.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever made the call, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `retry` | Send the request again after a while. |
+| Any other reader | `wait` | Wait, then send the request again. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The `{scheme}` storage failed a read or a write.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `scheme` | one of `local`, `s3`, `gcs`, `memory` | The kind of storage that failed. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/storage/upload_refused.md b/docs/errors/pipelex/storage/upload_refused.md
new file mode 100644
index 000000000..bc1dd82fd
--- /dev/null
+++ b/docs/errors/pipelex/storage/upload_refused.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.storage.upload_refused"
+description: "Storage refused the upload: what the Pipelex error code pipelex.storage.upload_refused means, who must act and what to do."
+---
+
+# pipelex.storage.upload_refused
+
+**Storage refused the upload**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.storage.upload_refused` |
+| Family | [`pipelex.storage`](../../index.md#pipelex-storage): Pipelex's storage addresses and uploads. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `runtime`: nobody could have acted beforehand, so whoever made the call waits, retries or reports the problem |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `403` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+Storage refused an upload for a reason it does not name.
+
+## What to do
+
+Report the problem to whoever runs the runtime, with the status storage answered.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever made the call, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `report` | Report this to whoever runs the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> Storage refused the upload with the status `{status}`.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `status` | `integer` | The HTTP status storage answered the upload with. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/storage/uri_invalid.md b/docs/errors/pipelex/storage/uri_invalid.md
new file mode 100644
index 000000000..a96c3b2d5
--- /dev/null
+++ b/docs/errors/pipelex/storage/uri_invalid.md
@@ -0,0 +1,50 @@
+---
+title: "pipelex.storage.uri_invalid"
+description: "The storage address is malformed: what the Pipelex error code pipelex.storage.uri_invalid means, who must act and what to do."
+---
+
+# pipelex.storage.uri_invalid
+
+**The storage address is malformed**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.storage.uri_invalid` |
+| Family | [`pipelex.storage`](../../index.md#pipelex-storage): Pipelex's storage addresses and uploads. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `422` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A `pipelex-storage://` address does not parse, or the storage provider refuses it as a key.
+
+## What to do
+
+Use the storage address exactly as an upload or a run's results returned it, without editing it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Send the storage address exactly as storage returned it, then send the request again. |
+| Any other reader | `change_input` | Pass this to the caller, whose request holds a storage address that cannot be parsed. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> A storage address in the request cannot be parsed.
+
+## Parameters
+
+This code declares no parameters, so its problems carry no `params`.
+
+## See also
+
+- [Cloud Storage](../../../features/cloud-storage.md)
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/webhook/delivery_failed.md b/docs/errors/pipelex/webhook/delivery_failed.md
new file mode 100644
index 000000000..6023e584c
--- /dev/null
+++ b/docs/errors/pipelex/webhook/delivery_failed.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.webhook.delivery_failed"
+description: "A webhook was not delivered: what the Pipelex error code pipelex.webhook.delivery_failed means, who must act and what to do."
+---
+
+# pipelex.webhook.delivery_failed
+
+**A webhook was not delivered**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.webhook.delivery_failed` |
+| Family | [`pipelex.webhook`](../../index.md#pipelex-webhook): The webhooks a caller registers to hear about its runs. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `yes`: repeating the operation may succeed, after `retry_after` seconds when the problem gives it |
+| HTTP status | `502` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A caller's webhook receiver answered with an error status, or could not be reached. The failure is recorded on the delivery, never on the run, and the platform repeats the delivery on its own.
+
+## What to do
+
+Fix the receiver so that it answers with a `2xx` status. The platform repeats the delivery, so nothing needs to be sent again.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Check that the webhook's receiver is reachable and answers with a success status. |
+| Any other reader | `change_input` | Pass this to the caller, whose webhook receiver refused the delivery or could not be reached. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The webhook was not delivered to its receiver (reason: `{reason}`).
+
+## Parameters
+
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `reason` | one of `http_status`, `unreachable` | Why the delivery failed: the receiver answered with an error status, or could not be reached. |
+| `receiver_status` | `integer` (optional) | The HTTP status the receiver answered with, when it answered. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipeline-execution-error.md b/docs/errors/pipeline-execution-error.md
deleted file mode 100644
index 242b75d4c..000000000
--- a/docs/errors/pipeline-execution-error.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-title: "Pipeline execution"
-description: "Reference for the `PipelineExecutionError` Pipelex error class."
----
-
-<!-- pipelex:authored -->
-
-# Pipeline execution
-
-Wraps any failure that occurred while running a pipeline, reported as its root fault.
-
-The runner raises it around every failure that happens once a run has started, so a host catches one class whatever went wrong. You will rarely see `PipelineExecutionError` as the `error_type` of a report, though: the report names what actually went wrong.
-
-## What the report says
-
-The report of a `PipelineExecutionError` is the report of its **root fault**, the innermost Pipelex error on its cause chain, located at the pipe that failed:
-
-- `error_type`, `title` and `type_uri` are the root fault's. A run whose model was not found reports [`ModelNotFoundError`](model-not-found-error.md), and a run whose parallel branch could not be combined reports `StuffFactoryError`.
-- `message` is the root fault's own message, prefixed with the failing pipe and its path from the entry pipe: `Pipe 'summarize' failed (two_steps → summarize): Model handle 'x' was not found in the model deck.` When the entry pipe itself failed, the path is left out: `Pipe 'flow' failed: …`.
-- Whether the message is caller-facing is the root fault's call, so under STRICT disclosure a caller-facing root keeps its located message and any other is redacted.
-- `error_category`, `retryable`, `model` and `provider` come from the cause chain. `error_domain` does too, with `runtime` as a floor. When nothing on the chain advises an action, `user_action` falls back to `The run failed in pipe '<code>': the message gives the cause.`
-
-A pipe that raised something that is not a Pipelex error is reported as [`PipelexUnexpectedError`](pipelex-unexpected-error.md), whose message names the original exception's class.
-
-The exception itself carries the location structurally: `pipe_code` is the pipe that failed and `pipe_stack` its path from the entry pipe. When the failure was never located, because it happened outside any pipe, or because it arrived from a remote worker as a report that already names its pipe, `pipe_code` is the entry pipe and `pipe_stack` is empty, and the report is taken as it is. A run therefore gives the same report whether it ran in process or on a remote worker.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelineExecutionError` |
-| `title` | Pipeline execution |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipeline-execution-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipeline.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipeline-input-content-error.md b/docs/errors/pipeline-input-content-error.md
deleted file mode 100644
index 4402145cd..000000000
--- a/docs/errors/pipeline-input-content-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Pipeline input content"
-description: "Reference for the `PipelineInputContentError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipeline input content
-
-A pipeline input's content reference (url) is unusable.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelineInputContentError` |
-| `title` | Pipeline input content |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipeline-input-content-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.pipeline.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-| `user_action` | `change_input` — Provide a valid url on every Image/Document input (https://, data:, pipelex-storage://, or an existing local file when running locally). |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipeline-input-format-error.md b/docs/errors/pipeline-input-format-error.md
deleted file mode 100644
index 0886ec115..000000000
--- a/docs/errors/pipeline-input-format-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Pipeline input format"
-description: "Reference for the `PipelineInputFormatError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipeline input format
-
-A file input's format is one its input slot, or the pipe that consumes it, cannot take.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelineInputFormatError` |
-| `title` | Pipeline input format |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipeline-input-format-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipeline.exceptions` |
-| Parent class | [`PipelineInputContentError`](pipeline-input-content-error.md) |
-| `user_action` | `change_input` — Give the input a file in a format the method can read. |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipeline-input-format-unsupported-error.md b/docs/errors/pipeline-input-format-unsupported-error.md
deleted file mode 100644
index 966b6eb1e..000000000
--- a/docs/errors/pipeline-input-format-unsupported-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Pipeline input format unsupported"
-description: "Reference for the `PipelineInputFormatUnsupportedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipeline input format unsupported
-
-A file input is certain to reach a pipe whose model cannot read its format.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelineInputFormatUnsupportedError` |
-| `title` | Pipeline input format unsupported |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipeline-input-format-unsupported-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipeline.exceptions` |
-| Parent class | [`PipelineInputFormatError`](pipeline-input-format-error.md) |
-| `user_action` | `change_input` — Give each file input in a format the model of the pipe that consumes it reads. |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipeline-input-not-an-image-error.md b/docs/errors/pipeline-input-not-an-image-error.md
deleted file mode 100644
index e4a1861a5..000000000
--- a/docs/errors/pipeline-input-not-an-image-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Pipeline input not an image"
-description: "Reference for the `PipelineInputNotAnImageError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipeline input not an image
-
-An Image input holds a file whose bytes identify it as something other than an image.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelineInputNotAnImageError` |
-| `title` | Pipeline input not an image |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipeline-input-not-an-image-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipeline.exceptions` |
-| Parent class | [`PipelineInputFormatError`](pipeline-input-format-error.md) |
-| `user_action` | `change_input` — Give an image file, such as PNG, JPEG or WebP, to every Image input. |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipeline-input-url-invalid-error.md b/docs/errors/pipeline-input-url-invalid-error.md
deleted file mode 100644
index d6297c495..000000000
--- a/docs/errors/pipeline-input-url-invalid-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Pipeline input url invalid"
-description: "Reference for the `PipelineInputUrlInvalidError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipeline input url invalid
-
-An Image/Document input carries an http(s) url that does not parse as one.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelineInputUrlInvalidError` |
-| `title` | Pipeline input url invalid |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipeline-input-url-invalid-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipeline.exceptions` |
-| Parent class | [`PipelineInputContentError`](pipeline-input-content-error.md) |
-| `user_action` | `change_input` — Provide a well-formed http(s) URL: a scheme, a host, and no whitespace. |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipeline-input-url-missing-error.md b/docs/errors/pipeline-input-url-missing-error.md
deleted file mode 100644
index 9859ab7b6..000000000
--- a/docs/errors/pipeline-input-url-missing-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Pipeline input url missing"
-description: "Reference for the `PipelineInputUrlMissingError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipeline input url missing
-
-An Image/Document input carries a blank url.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelineInputUrlMissingError` |
-| `title` | Pipeline input url missing |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipeline-input-url-missing-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipeline.exceptions` |
-| Parent class | [`PipelineInputContentError`](pipeline-input-content-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipeline-manager-already-exists-error.md b/docs/errors/pipeline-manager-already-exists-error.md
deleted file mode 100644
index 129b89192..000000000
--- a/docs/errors/pipeline-manager-already-exists-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipeline manager already exists"
-description: "Reference for the `PipelineManagerAlreadyExistsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipeline manager already exists
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelineManagerAlreadyExistsError` |
-| `title` | Pipeline manager already exists |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipeline-manager-already-exists-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipeline.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/pipeline-manager-not-found-error.md b/docs/errors/pipeline-manager-not-found-error.md
deleted file mode 100644
index 02e9713d2..000000000
--- a/docs/errors/pipeline-manager-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Pipeline manager not found"
-description: "Reference for the `PipelineManagerNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Pipeline manager not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `PipelineManagerNotFoundError` |
-| `title` | Pipeline manager not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/pipeline-manager-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipeline.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/platform-and-tooling.md b/docs/errors/platform-and-tooling.md
deleted file mode 100644
index cb6105632..000000000
--- a/docs/errors/platform-and-tooling.md
+++ /dev/null
@@ -1,143 +0,0 @@
----
-title: "Platform & tooling"
-description: "Pipelex error classes in the Platform & tooling area, grouped by subsystem."
----
-
-<!-- pipelex:generated -->
-
-# Platform & tooling
-
-Each error class below has a stable RFC 7807 `type` URI that dereferences to its
-own page. Classes are grouped by subsystem.
-
-## Base & root errors
-
-- [`PipelexConfigError`](pipelex-config-error.md) — Pipelex config
-- [`PipelexError`](pipelex-error.md) — Pipelex error
-- [`PipelexSetupError`](pipelex-setup-error.md) — Pipelex setup
-- [`PipelexUnexpectedError`](pipelex-unexpected-error.md) — Unexpected internal error
-- [`SecurityError`](security-error.md) — Security policy violation
-
-## Tools
-
-- [`ArgumentTypeError`](argument-type-error.md) — Argument type
-- [`AwsCredentialsError`](aws-credentials-error.md) — Aws credentials
-- [`ContextProviderError`](context-provider-error.md) — Context provider
-- [`CsvCoercionError`](csv-coercion-error.md) — CSV coercion error
-- [`CsvColumnError`](csv-column-error.md) — CSV column error
-- [`CsvError`](csv-error.md) — CSV error
-- [`CsvFlatnessError`](csv-flatness-error.md) — CSV flatness error
-- [`CsvReadError`](csv-read-error.md) — CSV read error
-- [`FileTypeError`](file-type-error.md) — File type
-- [`GcpLogSinkCredentialsError`](gcp-log-sink-credentials-error.md) — Log sink credentials missing or refused
-- [`Jinja2ContextError`](jinja2-context-error.md) — Jinja 2 context
-- [`Jinja2DetectVariablesError`](jinja2-detect-variables-error.md) — Jinja 2 detect variables
-- [`Jinja2StuffError`](jinja2-stuff-error.md) — Jinja 2 stuff
-- [`Jinja2TemplateBudgetError`](jinja2-template-budget-error.md) — Template render budget exceeded
-- [`Jinja2TemplateRenderError`](jinja2-template-render-error.md) — Jinja 2 template render
-- [`Jinja2TemplateSecurityError`](jinja2-template-security-error.md) — Jinja 2 template security
-- [`Jinja2TemplateSyntaxError`](jinja2-template-syntax-error.md) — Jinja 2 template syntax
-- [`JsonTypeError`](json-type-error.md) — Json type
-- [`LogSinkHeaderValueError`](log-sink-header-value-error.md) — Log sink header value holds a line break
-- [`LogSinkVariableError`](log-sink-variable-error.md) — Log sink variable did not resolve
-- [`ModuleFileError`](module-file-error.md) — Module file
-- [`PyPdfium2RendererError`](py-pdfium2-renderer-error.md) — Py pdfium 2 renderer
-- [`RemoteFileFetchError`](remote-file-fetch-error.md) — Remote file could not be fetched
-- [`SecretNotFoundError`](secret-not-found-error.md) — Secret not found
-- [`SsrfBlockedError`](ssrf-blocked-error.md) — Outbound request blocked (SSRF guard)
-- [`StorageChecksumMismatchError`](storage-checksum-mismatch-error.md) — Storage checksum mismatch
-- [`StorageConfigError`](storage-config-error.md) — Storage config
-- [`StorageError`](storage-error.md) — Storage error
-- [`StorageFileNotFoundError`](storage-file-not-found-error.md) — Storage file not found
-- [`StorageGcpCredentialsError`](storage-gcp-credentials-error.md) — Storage gcp credentials
-- [`StorageGcpError`](storage-gcp-error.md) — Storage gcp
-- [`StorageInvalidKeyError`](storage-invalid-key-error.md) — Storage invalid key
-- [`StorageInvalidUriError`](storage-invalid-uri-error.md) — Storage invalid uri
-- [`StorageLocalError`](storage-local-error.md) — Local storage error
-- [`StorageS3Error`](storage-s3-error.md) — S3 storage error
-- [`TomlError`](toml-error.md) — TOML parse error
-- [`UnknownVarPrefixError`](unknown-var-prefix-error.md) — Unknown var prefix
-- [`UriReadRefusedError`](uri-read-refused-error.md) — Read outside the run's scope refused
-- [`VarFallbackPatternError`](var-fallback-pattern-error.md) — Var fallback pattern
-- [`VarNotFoundError`](var-not-found-error.md) — Var not found
-
-## Kit
-
-- [`KitError`](kit-error.md) — Kit
-- [`KitIndexLoadingError`](kit-index-loading-error.md) — Kit index loading
-
-## System & configuration
-
-- [`ConfigValidationError`](config-validation-error.md) — Config validation
-- [`CredentialsError`](credentials-error.md) — Missing or invalid credentials
-- [`EnvVarNotFoundError`](env-var-not-found-error.md) — Environment variable not set
-- [`FatalError`](fatal-error.md) — Fatal error
-- [`InvocationPathError`](invocation-path-error.md) — Invocation path not derivable
-- [`JobMetadataError`](job-metadata-error.md) — Job metadata
-- [`LangfuseCredentialsError`](langfuse-credentials-error.md) — Langfuse credentials
-- [`MissingDependencyError`](missing-dependency-error.md) — Missing dependency
-- [`NestedKeyConflictError`](nested-key-conflict-error.md) — Nested key conflict
-- [`TelemetryConfigError`](telemetry-config-error.md) — Telemetry config
-- [`TelemetryConfigValidationError`](telemetry-config-validation-error.md) — Telemetry config validation
-- [`ToolError`](tool-error.md) — Tool error
-- [`TracebackMessageError`](traceback-message-error.md) — Traceback message
-
-## CLI
-
-- [`AmbiguousInputsFilesError`](ambiguous-inputs-files-error.md) — Ambiguous inputs files
-- [`AutoDetectedInputsFileError`](auto-detected-inputs-file-error.md) — Auto-detected inputs file is not a regular file
-- [`DriftAckError`](drift-ack-error.md) — Drift ack
-- [`DriftError`](drift-error.md) — Drift
-- [`DriftGitError`](drift-git-error.md) — Drift git
-- [`DriftManifestError`](drift-manifest-error.md) — Drift manifest
-- [`PipelexCLIError`](pipelex-cli-error.md) — Pipelex CLI
-- [`ReadinessCheckError`](readiness-check-error.md) — Readiness check
-
-## Codegen
-
-- [`CodegenError`](codegen-error.md) — Codegen error
-- [`CodegenLockError`](codegen-lock-error.md) — Codegen lock error
-- [`CodegenStampError`](codegen-stamp-error.md) — Codegen stamp error
-
-## Fix ops
-
-- [`FixTransactionError`](fix-transaction-error.md) — Fix transaction
-- [`FixWriteConflictError`](fix-write-conflict-error.md) — Fix write conflict
-
-## Hosted
-
-- [`HostedBaseUrlError`](hosted-base-url-error.md) — Hosted base url
-- [`HostedLocalFileUploadUnavailableError`](hosted-local-file-upload-unavailable-error.md) — Hosted local file upload unavailable
-- [`HostedMethodInvalidError`](hosted-method-invalid-error.md) — Hosted method invalid
-- [`HostedRunError`](hosted-run-error.md) — Hosted run error
-- [`HostedRunInterruptedError`](hosted-run-interrupted-error.md) — Hosted run interrupted
-- [`HostedRunOutcomeUnknownError`](hosted-run-outcome-unknown-error.md) — Hosted run outcome unknown
-- [`HostedRunPollingError`](hosted-run-polling-error.md) — Hosted run polling
-- [`HostedRunSourceError`](hosted-run-source-error.md) — Hosted run source
-
-## Methods
-
-- [`MethodDependencyFetchError`](method-dependency-fetch-error.md) — Method dependency fetch
-- [`MethodDependencyNotShippedError`](method-dependency-not-shipped-error.md) — Method dependency not shipped
-- [`MethodFetchDisabledError`](method-fetch-disabled-error.md) — Method fetch disabled
-- [`MethodFetchError`](method-fetch-error.md) — Method fetch
-- [`MethodInstallError`](method-install-error.md) — Method install
-- [`MethodPackageAmbiguityError`](method-package-ambiguity-error.md) — Method package ambiguity
-- [`MethodPackageNotFoundError`](method-package-not-found-error.md) — Method package not found
-- [`MethodPackageSymlinkError`](method-package-symlink-error.md) — Method package symlink
-- [`MethodPackageTooLargeError`](method-package-too-large-error.md) — Method package too large
-- [`MethodRefError`](method-ref-error.md) — Method reference error
-- [`MethodRefParseError`](method-ref-parse-error.md) — Method ref parse
-- [`MethodStructuresRefusedError`](method-structures-refused-error.md) — Method structures refused
-
-## Migration
-
-- [`FormerReleaseConfigError`](former-release-config-error.md) — Configuration left by a former release
-- [`FunctionNamesMigrationError`](function-names-migration-error.md) — Function names migration error
-- [`MigrationError`](migration-error.md) — Migration error
-- [`MigrationGoldenError`](migration-golden-error.md) — Migration golden error
-- [`MigrationLedgerError`](migration-ledger-error.md) — Migration ledger error
-- [`MigrationRegistryError`](migration-registry-error.md) — Migration registry error
-- [`MigrationSnapshotRefusedError`](migration-snapshot-refused-error.md) — Migration snapshot refused
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/plugin-api-version-mismatch-error.md b/docs/errors/plugin-api-version-mismatch-error.md
deleted file mode 100644
index c6d741b6c..000000000
--- a/docs/errors/plugin-api-version-mismatch-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Plugin api version mismatch"
-description: "Reference for the `PluginApiVersionMismatchError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Plugin api version mismatch
-
-A discovered plugin targets a plugin-API version this Pipelex does not support.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PluginApiVersionMismatchError` |
-| `title` | Plugin api version mismatch |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/plugin-api-version-mismatch-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/plugin-declared-in-multiple-groups-error.md b/docs/errors/plugin-declared-in-multiple-groups-error.md
deleted file mode 100644
index be56d17a8..000000000
--- a/docs/errors/plugin-declared-in-multiple-groups-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Plugin declared in multiple groups"
-description: "Reference for the `PluginDeclaredInMultipleGroupsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Plugin declared in multiple groups
-
-One installed plugin advertises the same name under more than one entry-point group.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PluginDeclaredInMultipleGroupsError` |
-| `title` | Plugin declared in multiple groups |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/plugin-declared-in-multiple-groups-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/plugin-error.md b/docs/errors/plugin-error.md
deleted file mode 100644
index 73e94185d..000000000
--- a/docs/errors/plugin-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Plugin error"
-description: "Reference for the `PluginError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Plugin error
-
-Base for plugin-discovery and plugin-registration failures.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PluginError` |
-| `title` | Plugin error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/plugin-error/` |
-| `error_domain` | `config` |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/plugin-layer-violation-error.md b/docs/errors/plugin-layer-violation-error.md
deleted file mode 100644
index 2a289b664..000000000
--- a/docs/errors/plugin-layer-violation-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Plugin layer violation"
-description: "Reference for the `PluginLayerViolationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Plugin layer violation
-
-A kernel-group plugin registered an interpreter-layer capability.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PluginLayerViolationError` |
-| `title` | Plugin layer violation |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/plugin-layer-violation-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/plugin-model-declaration-error.md b/docs/errors/plugin-model-declaration-error.md
deleted file mode 100644
index 3cc84ad89..000000000
--- a/docs/errors/plugin-model-declaration-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Plugin model declaration"
-description: "Reference for the `PluginModelDeclarationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Plugin model declaration
-
-A model a plugin declares, or a model deck default it sets, cannot be merged into this installation's inference configuration.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PluginModelDeclarationError` |
-| `title` | Plugin model declaration |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/plugin-model-declaration-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/portkey-credentials-error.md b/docs/errors/portkey-credentials-error.md
deleted file mode 100644
index 66d73607e..000000000
--- a/docs/errors/portkey-credentials-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Portkey credentials"
-description: "Reference for the `PortkeyCredentialsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Portkey credentials
-
-| Field | Value |
-|---|---|
-| `error_type` | `PortkeyCredentialsError` |
-| `title` | Portkey credentials |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/portkey-credentials-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.portkey.portkey_exceptions` |
-| Parent class | [`PortkeyError`](portkey-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/portkey-error.md b/docs/errors/portkey-error.md
deleted file mode 100644
index 32b5e55db..000000000
--- a/docs/errors/portkey-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Portkey"
-description: "Reference for the `PortkeyError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Portkey
-
-| Field | Value |
-|---|---|
-| `error_type` | `PortkeyError` |
-| `title` | Portkey |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/portkey-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.portkey.portkey_exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/portkey-factory-error.md b/docs/errors/portkey-factory-error.md
deleted file mode 100644
index 7866f181d..000000000
--- a/docs/errors/portkey-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Portkey factory"
-description: "Reference for the `PortkeyFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Portkey factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `PortkeyFactoryError` |
-| `title` | Portkey factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/portkey-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.portkey.portkey_exceptions` |
-| Parent class | [`PortkeyError`](portkey-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/prompt-document-factory-error.md b/docs/errors/prompt-document-factory-error.md
deleted file mode 100644
index 445f69b3c..000000000
--- a/docs/errors/prompt-document-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Prompt document factory"
-description: "Reference for the `PromptDocumentFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Prompt document factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `PromptDocumentFactoryError` |
-| `title` | Prompt document factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/prompt-document-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/prompt-document-format-error.md b/docs/errors/prompt-document-format-error.md
deleted file mode 100644
index 9b5b0225e..000000000
--- a/docs/errors/prompt-document-format-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Prompt document format"
-description: "Reference for the `PromptDocumentFormatError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Prompt document format
-
-A prompt document's known format is one the LLM does not read.
-
-| Field | Value |
-|---|---|
-| `error_type` | `PromptDocumentFormatError` |
-| `title` | Prompt document format |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/prompt-document-format-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/prompt-image-factory-error.md b/docs/errors/prompt-image-factory-error.md
deleted file mode 100644
index 35b4cf7b9..000000000
--- a/docs/errors/prompt-image-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Prompt image factory"
-description: "Reference for the `PromptImageFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Prompt image factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `PromptImageFactoryError` |
-| `title` | Prompt image factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/prompt-image-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/prompt-image-format-error.md b/docs/errors/prompt-image-format-error.md
deleted file mode 100644
index 5e1b6a36b..000000000
--- a/docs/errors/prompt-image-format-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Prompt image format"
-description: "Reference for the `PromptImageFormatError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Prompt image format
-
-| Field | Value |
-|---|---|
-| `error_type` | `PromptImageFormatError` |
-| `title` | Prompt image format |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/prompt-image-format-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/py-pdfium2-renderer-error.md b/docs/errors/py-pdfium2-renderer-error.md
deleted file mode 100644
index a921532a5..000000000
--- a/docs/errors/py-pdfium2-renderer-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Py pdfium 2 renderer"
-description: "Reference for the `PyPdfium2RendererError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Py pdfium 2 renderer
-
-| Field | Value |
-|---|---|
-| `error_type` | `PyPdfium2RendererError` |
-| `title` | Py pdfium 2 renderer |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/py-pdfium2-renderer-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.pdf.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/readiness-check-error.md b/docs/errors/readiness-check-error.md
deleted file mode 100644
index 79baaa4e0..000000000
--- a/docs/errors/readiness-check-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Readiness check"
-description: "Reference for the `ReadinessCheckError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Readiness check
-
-Raised when readiness checks fail (missing dependencies or dev mode without venv).
-
-| Field | Value |
-|---|---|
-| `error_type` | `ReadinessCheckError` |
-| `title` | Readiness check |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/readiness-check-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cli.exceptions` |
-| Parent class | [`PipelexCLIError`](pipelex-cli-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/remote-file-fetch-error.md b/docs/errors/remote-file-fetch-error.md
deleted file mode 100644
index ca2cfde89..000000000
--- a/docs/errors/remote-file-fetch-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Remote file could not be fetched"
-description: "Reference for the `RemoteFileFetchError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Remote file could not be fetched
-
-A remote file an input or a pipe referenced could not be fetched.
-
-| Field | Value |
-|---|---|
-| `error_type` | `RemoteFileFetchError` |
-| `title` | Remote file could not be fetched |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/remote-file-fetch-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.tools.misc.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-| `user_action` | `change_input` — Check that the URL serves the file to a plain HTTP client, or upload the file and reference it instead. |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/reporting-manager-error.md b/docs/errors/reporting-manager-error.md
deleted file mode 100644
index 08e74e3de..000000000
--- a/docs/errors/reporting-manager-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Reporting manager"
-description: "Reference for the `ReportingManagerError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Reporting manager
-
-| Field | Value |
-|---|---|
-| `error_type` | `ReportingManagerError` |
-| `title` | Reporting manager |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/reporting-manager-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/reserved-service-error-code-error.md b/docs/errors/reserved-service-error-code-error.md
deleted file mode 100644
index a31aa5f9f..000000000
--- a/docs/errors/reserved-service-error-code-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Reserved service error code"
-description: "Reference for the `ReservedServiceErrorCodeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Reserved service error code
-
-A plugin contributed a service error code the runtime classifies itself.
-
-| Field | Value |
-|---|---|
-| `error_type` | `ReservedServiceErrorCodeError` |
-| `title` | Reserved service error code |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/reserved-service-error-code-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/retired-plugin-entry-point-group-error.md b/docs/errors/retired-plugin-entry-point-group-error.md
deleted file mode 100644
index de7216cb5..000000000
--- a/docs/errors/retired-plugin-entry-point-group-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Retired plugin entry point group"
-description: "Reference for the `RetiredPluginEntryPointGroupError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Retired plugin entry point group
-
-An installed plugin still advertises itself under the retired single entry-point group.
-
-| Field | Value |
-|---|---|
-| `error_type` | `RetiredPluginEntryPointGroupError` |
-| `title` | Retired plugin entry point group |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/retired-plugin-entry-point-group-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/routing-profile-blueprint-value-error.md b/docs/errors/routing-profile-blueprint-value-error.md
deleted file mode 100644
index cf6c9dda1..000000000
--- a/docs/errors/routing-profile-blueprint-value-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Routing profile blueprint value"
-description: "Reference for the `RoutingProfileBlueprintValueError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Routing profile blueprint value
-
-| Field | Value |
-|---|---|
-| `error_type` | `RoutingProfileBlueprintValueError` |
-| `title` | Routing profile blueprint value |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/routing-profile-blueprint-value-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/routing-profile-disabled-backend-error.md b/docs/errors/routing-profile-disabled-backend-error.md
deleted file mode 100644
index 6d08a7fdf..000000000
--- a/docs/errors/routing-profile-disabled-backend-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Routing profile disabled backend"
-description: "Reference for the `RoutingProfileDisabledBackendError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Routing profile disabled backend
-
-| Field | Value |
-|---|---|
-| `error_type` | `RoutingProfileDisabledBackendError` |
-| `title` | Routing profile disabled backend |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/routing-profile-disabled-backend-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/routing-profile-library-error.md b/docs/errors/routing-profile-library-error.md
deleted file mode 100644
index ac0c3aaee..000000000
--- a/docs/errors/routing-profile-library-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Routing profile library"
-description: "Reference for the `RoutingProfileLibraryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Routing profile library
-
-| Field | Value |
-|---|---|
-| `error_type` | `RoutingProfileLibraryError` |
-| `title` | Routing profile library |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/routing-profile-library-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/routing-profile-library-not-found-error.md b/docs/errors/routing-profile-library-not-found-error.md
deleted file mode 100644
index 5140d19fd..000000000
--- a/docs/errors/routing-profile-library-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Routing profile library not found"
-description: "Reference for the `RoutingProfileLibraryNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Routing profile library not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `RoutingProfileLibraryNotFoundError` |
-| `title` | Routing profile library not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/routing-profile-library-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/sdk-type-error.md b/docs/errors/sdk-type-error.md
deleted file mode 100644
index 325cc94e7..000000000
--- a/docs/errors/sdk-type-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Sdk type"
-description: "Reference for the `SdkTypeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Sdk type
-
-| Field | Value |
-|---|---|
-| `error_type` | `SdkTypeError` |
-| `title` | Sdk type |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/sdk-type-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/search-handle-not-found-error.md b/docs/errors/search-handle-not-found-error.md
deleted file mode 100644
index cb7ae765f..000000000
--- a/docs/errors/search-handle-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Search handle not found"
-description: "Reference for the `SearchHandleNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Search handle not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `SearchHandleNotFoundError` |
-| `title` | Search handle not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/search-handle-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/search-job-failure-error.md b/docs/errors/search-job-failure-error.md
deleted file mode 100644
index 7d455000b..000000000
--- a/docs/errors/search-job-failure-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Search job failure"
-description: "Reference for the `SearchJobFailureError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Search job failure
-
-| Field | Value |
-|---|---|
-| `error_type` | `SearchJobFailureError` |
-| `title` | Search job failure |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/search-job-failure-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/search-model-not-found-error.md b/docs/errors/search-model-not-found-error.md
deleted file mode 100644
index 372bec702..000000000
--- a/docs/errors/search-model-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Search model not found"
-description: "Reference for the `SearchModelNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Search model not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `SearchModelNotFoundError` |
-| `title` | Search model not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/search-model-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.exceptions` |
-| Parent class | [`ModelNotFoundError`](model-not-found-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/secret-not-found-error.md b/docs/errors/secret-not-found-error.md
deleted file mode 100644
index c9f8c6647..000000000
--- a/docs/errors/secret-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Secret not found"
-description: "Reference for the `SecretNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Secret not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `SecretNotFoundError` |
-| `title` | Secret not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/secret-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.secrets.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/security-error.md b/docs/errors/security-error.md
deleted file mode 100644
index 6cd2e07b5..000000000
--- a/docs/errors/security-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Security policy violation"
-description: "Reference for the `SecurityError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Security policy violation
-
-Base for security-policy violations.
-
-| Field | Value |
-|---|---|
-| `error_type` | `SecurityError` |
-| `title` | Security policy violation |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/security-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.base_exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/ssrf-blocked-error.md b/docs/errors/ssrf-blocked-error.md
deleted file mode 100644
index a42d976e7..000000000
--- a/docs/errors/ssrf-blocked-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Outbound request blocked (SSRF guard)"
-description: "Reference for the `SsrfBlockedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Outbound request blocked (SSRF guard)
-
-Raised when an outbound request is refused because the destination host resolved to a disallowed (private / loopback / link-local / metadata) address.
-
-| Field | Value |
-|---|---|
-| `error_type` | `SsrfBlockedError` |
-| `title` | Outbound request blocked (SSRF guard) |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/ssrf-blocked-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.tools.network.exceptions` |
-| Parent class | [`SecurityError`](security-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/storage-checksum-mismatch-error.md b/docs/errors/storage-checksum-mismatch-error.md
deleted file mode 100644
index 4a8610190..000000000
--- a/docs/errors/storage-checksum-mismatch-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Storage checksum mismatch"
-description: "Reference for the `StorageChecksumMismatchError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Storage checksum mismatch
-
-Raised when the bytes a create-only write was handed do not hash to the checksum it was handed with them.
-
-| Field | Value |
-|---|---|
-| `error_type` | `StorageChecksumMismatchError` |
-| `title` | Storage checksum mismatch |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/storage-checksum-mismatch-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.storage.exceptions` |
-| Parent class | [`StorageError`](storage-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/storage-config-error.md b/docs/errors/storage-config-error.md
deleted file mode 100644
index 334b433ac..000000000
--- a/docs/errors/storage-config-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Storage config"
-description: "Reference for the `StorageConfigError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Storage config
-
-Raised when a storage configuration is invalid.
-
-| Field | Value |
-|---|---|
-| `error_type` | `StorageConfigError` |
-| `title` | Storage config |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/storage-config-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.storage.exceptions` |
-| Parent class | [`StorageError`](storage-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/storage-delivery-error.md b/docs/errors/storage-delivery-error.md
deleted file mode 100644
index 79a65880b..000000000
--- a/docs/errors/storage-delivery-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Storage delivery"
-description: "Reference for the `StorageDeliveryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Storage delivery
-
-| Field | Value |
-|---|---|
-| `error_type` | `StorageDeliveryError` |
-| `title` | Storage delivery |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/storage-delivery-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_run.exceptions` |
-| Parent class | [`DeliveryError`](delivery-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/storage-error.md b/docs/errors/storage-error.md
deleted file mode 100644
index 489a60065..000000000
--- a/docs/errors/storage-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Storage error"
-description: "Reference for the `StorageError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Storage error
-
-Base exception for storage-related errors.
-
-| Field | Value |
-|---|---|
-| `error_type` | `StorageError` |
-| `title` | Storage error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/storage-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.storage.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/storage-file-not-found-error.md b/docs/errors/storage-file-not-found-error.md
deleted file mode 100644
index 3e29061a7..000000000
--- a/docs/errors/storage-file-not-found-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Storage file not found"
-description: "Reference for the `StorageFileNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Storage file not found
-
-Raised when a requested file does not exist in storage.
-
-| Field | Value |
-|---|---|
-| `error_type` | `StorageFileNotFoundError` |
-| `title` | Storage file not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/storage-file-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.storage.exceptions` |
-| Parent class | [`StorageError`](storage-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/storage-gcp-credentials-error.md b/docs/errors/storage-gcp-credentials-error.md
deleted file mode 100644
index b471a926e..000000000
--- a/docs/errors/storage-gcp-credentials-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Storage gcp credentials"
-description: "Reference for the `StorageGcpCredentialsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Storage gcp credentials
-
-Raised when GCP credentials file is not found or invalid.
-
-| Field | Value |
-|---|---|
-| `error_type` | `StorageGcpCredentialsError` |
-| `title` | Storage gcp credentials |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/storage-gcp-credentials-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.storage.exceptions` |
-| Parent class | [`StorageGcpError`](storage-gcp-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/storage-gcp-error.md b/docs/errors/storage-gcp-error.md
deleted file mode 100644
index 03a8d6f58..000000000
--- a/docs/errors/storage-gcp-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Storage gcp"
-description: "Reference for the `StorageGcpError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Storage gcp
-
-Raised when a GCP storage operation fails.
-
-| Field | Value |
-|---|---|
-| `error_type` | `StorageGcpError` |
-| `title` | Storage gcp |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/storage-gcp-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.storage.exceptions` |
-| Parent class | [`StorageError`](storage-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/storage-invalid-key-error.md b/docs/errors/storage-invalid-key-error.md
deleted file mode 100644
index dd0c796e5..000000000
--- a/docs/errors/storage-invalid-key-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Storage invalid key"
-description: "Reference for the `StorageInvalidKeyError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Storage invalid key
-
-Raised when a storage key is invalid (e.g., contains scheme prefix).
-
-| Field | Value |
-|---|---|
-| `error_type` | `StorageInvalidKeyError` |
-| `title` | Storage invalid key |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/storage-invalid-key-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.storage.exceptions` |
-| Parent class | [`StorageError`](storage-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/storage-invalid-uri-error.md b/docs/errors/storage-invalid-uri-error.md
deleted file mode 100644
index 805b01ecf..000000000
--- a/docs/errors/storage-invalid-uri-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Storage invalid uri"
-description: "Reference for the `StorageInvalidUriError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Storage invalid uri
-
-Raised when a URI is invalid (e.g., path traversal attempt or absolute path).
-
-| Field | Value |
-|---|---|
-| `error_type` | `StorageInvalidUriError` |
-| `title` | Storage invalid uri |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/storage-invalid-uri-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.storage.exceptions` |
-| Parent class | [`StorageError`](storage-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/storage-local-error.md b/docs/errors/storage-local-error.md
deleted file mode 100644
index 6a304e232..000000000
--- a/docs/errors/storage-local-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Local storage error"
-description: "Reference for the `StorageLocalError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Local storage error
-
-Raised when a local filesystem storage operation fails.
-
-| Field | Value |
-|---|---|
-| `error_type` | `StorageLocalError` |
-| `title` | Local storage error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/storage-local-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.storage.exceptions` |
-| Parent class | [`StorageError`](storage-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/storage-s3-error.md b/docs/errors/storage-s3-error.md
deleted file mode 100644
index 2ed2e1270..000000000
--- a/docs/errors/storage-s3-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "S3 storage error"
-description: "Reference for the `StorageS3Error` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# S3 storage error
-
-Raised when an S3 storage operation fails.
-
-| Field | Value |
-|---|---|
-| `error_type` | `StorageS3Error` |
-| `title` | S3 storage error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/storage-s3-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.storage.exceptions` |
-| Parent class | [`StorageError`](storage-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/structure-class-error.md b/docs/errors/structure-class-error.md
deleted file mode 100644
index 7ad5a5c23..000000000
--- a/docs/errors/structure-class-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Structure class"
-description: "Reference for the `StructureClassError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Structure class
-
-| Field | Value |
-|---|---|
-| `error_type` | `StructureClassError` |
-| `title` | Structure class |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/structure-class-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.concepts.structure_generation.exceptions` |
-| Parent class | [`ConceptFactoryError`](concept-factory-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/structure-validation-error.md b/docs/errors/structure-validation-error.md
deleted file mode 100644
index c8451b171..000000000
--- a/docs/errors/structure-validation-error.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-title: "Structure validation"
-description: "Reference for the `StructureValidationError` Pipelex error class."
----
-
-<!-- pipelex:authored -->
-
-# Structure validation
-
-A provided input value could not be built as the concept its input declares.
-
-Most often the value is the right JSON kind but does not fit the concept's structure: an object missing a required field, a malformed `{"url": ...}` for an image or a document, a string that is not an ISO date for a `Date` input. The message names the input and the declared concept, and ends with the expected shape rendered from the method's signature. The fix is the value.
-
-The other case is a value that an input reading bare values by their own shape has no reading for, or reads as a concept the input does not accept. An input declared `Dynamic`, as one of the container natives (`Html`, `Page`, `TextAndImages`, `SearchResult`, `Composite`), or as a `Choice` or a `Rating`, reads a bare value that way. A bare string reads as a text, which only a `Dynamic` input takes: at a `Choice` input the message is `Input 'team' could not be built as 'native.Choice': you provided a string ("billing"), which reads as 'native.Text', and a 'native.Text' is not a 'native.Choice'.`, and the fix is the value, sent in the expected shape the message ends with. So it is for the input's own content sent without its envelope: `{"choice": "billing"}` at a `Choice` input is refused as `the content of a 'native.Choice' without the envelope that names its concept`, and declaring the input `JSON` instead would discard the concept the method asked for. A bare number or boolean at a `Rating` or a `Choice` input, such as a level `2` sent alone, is refused the same way, as a value that `takes its value in the envelope that names its concept`, since declaring the input `Anything` would discard the verdict. Some values have no reading at all: a number, or a list of plain objects. The message says so, `Input 'records' could not be built as 'native.Dynamic': you provided a list of 2 item(s), and an input of this concept reads a bare value by its own shape, with no reading for this one.`, and its next step names the declaration that would read the value: `JSON` for an object, `JSON[]` for a list of objects, `Anything` or `Anything[]` for anything else, or a concept with a structure that describes it. The fix is usually the method's declaration rather than the value.
-
-When no declaration reads the value, such as an empty list at a `Html[]` input, a list mixing prebuilt contents of different kinds, or a list holding nulls or nested lists, the message carries the reason itself.
-
-The error is in the `input` domain, so an HTTP surface answers 422.
-
-| Field | Value |
-|---|---|
-| `error_type` | `StructureValidationError` |
-| `title` | Structure validation |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/structure-validation-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`InputShapingError`](input-shaping-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/structured-content-composer-type-error.md b/docs/errors/structured-content-composer-type-error.md
deleted file mode 100644
index 8db1ac607..000000000
--- a/docs/errors/structured-content-composer-type-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Structured content composer type"
-description: "Reference for the `StructuredContentComposerTypeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Structured content composer type
-
-| Field | Value |
-|---|---|
-| `error_type` | `StructuredContentComposerTypeError` |
-| `title` | Structured content composer type |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/structured-content-composer-type-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.compose.exceptions` |
-| Parent class | [`PipeComposeError`](pipe-compose-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/structured-content-composer-validation-error.md b/docs/errors/structured-content-composer-validation-error.md
deleted file mode 100644
index 98e3e7d1e..000000000
--- a/docs/errors/structured-content-composer-validation-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Structured content composer validation"
-description: "Reference for the `StructuredContentComposerValidationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Structured content composer validation
-
-| Field | Value |
-|---|---|
-| `error_type` | `StructuredContentComposerValidationError` |
-| `title` | Structured content composer validation |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/structured-content-composer-validation-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.compose.exceptions` |
-| Parent class | [`PipeComposeError`](pipe-compose-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/structured-content-composer-value-error.md b/docs/errors/structured-content-composer-value-error.md
deleted file mode 100644
index 9e3dd057f..000000000
--- a/docs/errors/structured-content-composer-value-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Structured content composer value"
-description: "Reference for the `StructuredContentComposerValueError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Structured content composer value
-
-| Field | Value |
-|---|---|
-| `error_type` | `StructuredContentComposerValueError` |
-| `title` | Structured content composer value |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/structured-content-composer-value-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.compose.exceptions` |
-| Parent class | [`PipeComposeError`](pipe-compose-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/stuff-artefact-error.md b/docs/errors/stuff-artefact-error.md
deleted file mode 100644
index c477f8c86..000000000
--- a/docs/errors/stuff-artefact-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Stuff artefact"
-description: "Reference for the `StuffArtefactError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Stuff artefact
-
-| Field | Value |
-|---|---|
-| `error_type` | `StuffArtefactError` |
-| `title` | Stuff artefact |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/stuff-artefact-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.stuffs.exceptions` |
-| Parent class | [`StuffError`](stuff-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/stuff-artefact-reserved-field-error.md b/docs/errors/stuff-artefact-reserved-field-error.md
deleted file mode 100644
index 8b42a42b1..000000000
--- a/docs/errors/stuff-artefact-reserved-field-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Stuff artefact reserved field"
-description: "Reference for the `StuffArtefactReservedFieldError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Stuff artefact reserved field
-
-| Field | Value |
-|---|---|
-| `error_type` | `StuffArtefactReservedFieldError` |
-| `title` | Stuff artefact reserved field |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/stuff-artefact-reserved-field-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.stuffs.exceptions` |
-| Parent class | [`StuffArtefactError`](stuff-artefact-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/stuff-content-factory-error.md b/docs/errors/stuff-content-factory-error.md
deleted file mode 100644
index f6b3e67d7..000000000
--- a/docs/errors/stuff-content-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Stuff content factory"
-description: "Reference for the `StuffContentFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Stuff content factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `StuffContentFactoryError` |
-| `title` | Stuff content factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/stuff-content-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.stuffs.exceptions` |
-| Parent class | [`StuffError`](stuff-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/stuff-content-type-error.md b/docs/errors/stuff-content-type-error.md
deleted file mode 100644
index 11fae942f..000000000
--- a/docs/errors/stuff-content-type-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Stuff content type"
-description: "Reference for the `StuffContentTypeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Stuff content type
-
-| Field | Value |
-|---|---|
-| `error_type` | `StuffContentTypeError` |
-| `title` | Stuff content type |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/stuff-content-type-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.stuffs.exceptions` |
-| Parent class | [`StuffError`](stuff-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/stuff-content-validation-error.md b/docs/errors/stuff-content-validation-error.md
deleted file mode 100644
index 87cde87c0..000000000
--- a/docs/errors/stuff-content-validation-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Stuff content validation"
-description: "Reference for the `StuffContentValidationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Stuff content validation
-
-Raised when content validation fails during type conversion.
-
-| Field | Value |
-|---|---|
-| `error_type` | `StuffContentValidationError` |
-| `title` | Stuff content validation |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/stuff-content-validation-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.stuffs.exceptions` |
-| Parent class | [`StuffError`](stuff-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/stuff-error.md b/docs/errors/stuff-error.md
deleted file mode 100644
index 20484358f..000000000
--- a/docs/errors/stuff-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Stuff error"
-description: "Reference for the `StuffError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Stuff error
-
-| Field | Value |
-|---|---|
-| `error_type` | `StuffError` |
-| `title` | Stuff error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/stuff-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.stuffs.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/stuff-factory-error.md b/docs/errors/stuff-factory-error.md
deleted file mode 100644
index cb84f0053..000000000
--- a/docs/errors/stuff-factory-error.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-title: "Stuff factory"
-description: "Reference for the `StuffFactoryError` Pipelex error class."
----
-
-<!-- pipelex:authored -->
-
-# Stuff factory
-
-A stuff could not be built from the content given for its concept. It is raised from many places, and whose fault it is depends on the place.
-
-When a `PipeParallel` combines its branch results into its declared output, a mismatch is the caller's fault: which branch feeds which field, what each branch produces and whether it produces a list are all written in the caller's method. A branch declared `Idea[]` feeding a field that holds one `Idea`, a branch concept its field does not accept, or a required field no branch feeds, all fail there. That error is in the `input` domain, so an HTTP surface answers 422, its message survives STRICT disclosure, and its next step says to change the method. The run's report locates it at the parallel: ``Pipe 'analyze' failed (flow → analyze): Error combining stuffs for concept Report, stuff named `report`: …``, followed by the validation errors of the fields.
-
-When the mismatch is a branch whose multiplicity differs from its field's, a list branch feeding a single field or the reverse, the parallel raises a second `StuffFactoryError` from the combine's, which restates the refusal with the change to make, and its next step is that change. A run failure reports its root fault, and of two faults of the same class the outer one, so every surface, a hosted caller under STRICT disclosure included, reads the restatement: `Pipe 'analyze' failed (flow → analyze): PipeParallel 'analyze' cannot combine its branch results into its output 'Report'. Branch 'gen_ideas' gives result 'ideas' as a list, 'Idea[]', but field 'ideas' of 'Report' holds a single item. …`. When the combine also refused a field the multiplicity does not explain, the restatement keeps its report after `The combine also reported:`.
-
-Raised from any other place, it carries no domain and its message is redacted under STRICT disclosure.
-
-| Field | Value |
-|---|---|
-| `error_type` | `StuffFactoryError` |
-| `title` | Stuff factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/stuff-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.stuffs.exceptions` |
-| Parent class | [`StuffError`](stuff-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/stuff-spec-error.md b/docs/errors/stuff-spec-error.md
deleted file mode 100644
index bb80ad97a..000000000
--- a/docs/errors/stuff-spec-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Stuff spec"
-description: "Reference for the `StuffSpecError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Stuff spec
-
-| Field | Value |
-|---|---|
-| `error_type` | `StuffSpecError` |
-| `title` | Stuff spec |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/stuff-spec-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.pipes.stuff_spec.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/stuff-spec-factory-error.md b/docs/errors/stuff-spec-factory-error.md
deleted file mode 100644
index 799f8444c..000000000
--- a/docs/errors/stuff-spec-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Stuff spec factory"
-description: "Reference for the `StuffSpecFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Stuff spec factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `StuffSpecFactoryError` |
-| `title` | Stuff spec factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/stuff-spec-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.pipes.stuff_spec.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/telemetry-config-error.md b/docs/errors/telemetry-config-error.md
deleted file mode 100644
index 9e89204ba..000000000
--- a/docs/errors/telemetry-config-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Telemetry config"
-description: "Reference for the `TelemetryConfigError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Telemetry config
-
-A telemetry configuration this process cannot use.
-
-| Field | Value |
-|---|---|
-| `error_type` | `TelemetryConfigError` |
-| `title` | Telemetry config |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/telemetry-config-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.system.telemetry.exceptions` |
-| Parent class | [`PipelexConfigError`](pipelex-config-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/telemetry-config-validation-error.md b/docs/errors/telemetry-config-validation-error.md
deleted file mode 100644
index abd4d2659..000000000
--- a/docs/errors/telemetry-config-validation-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Telemetry config validation"
-description: "Reference for the `TelemetryConfigValidationError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Telemetry config validation
-
-| Field | Value |
-|---|---|
-| `error_type` | `TelemetryConfigValidationError` |
-| `title` | Telemetry config validation |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/telemetry-config-validation-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.system.telemetry.exceptions` |
-| Parent class | [`TelemetryConfigError`](telemetry-config-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/template-sigil-syntax-error.md b/docs/errors/template-sigil-syntax-error.md
deleted file mode 100644
index cb0d530cb..000000000
--- a/docs/errors/template-sigil-syntax-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Template sigil syntax"
-description: "Reference for the `TemplateSigilSyntaxError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Template sigil syntax
-
-Raised when a template contains a Pipelex sigil shape that violates the strict line-bounded `@` rule.
-
-| Field | Value |
-|---|---|
-| `error_type` | `TemplateSigilSyntaxError` |
-| `title` | Template sigil syntax |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/template-sigil-syntax-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.templating.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/template-url-refused-error.md b/docs/errors/template-url-refused-error.md
deleted file mode 100644
index f82398a07..000000000
--- a/docs/errors/template-url-refused-error.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-title: "Relative URL refused"
-description: "Reference for the `TemplateUrlRefusedError` Pipelex error class."
----
-
-<!-- pipelex:authored -->
-
-# Relative URL refused
-
-A relative URL of an HTML document names no image, stylesheet or font of its template's method tree, so the print reads nothing.
-
-| Field | Value |
-|---|---|
-| `error_type` | `TemplateUrlRefusedError` |
-| `title` | Relative URL refused |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/template-url-refused-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.cogt.doc_gen.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-## When it is raised
-
-A relative URL in a `PipeDocGen` HTML template names a file of the template's method, resolved against the template file, or against the bundle file of an inline template ([Images, stylesheets and fonts beside a template](../building-methods/pipes/pipe-operators/PipeDocGen.md#images-stylesheets-and-fonts-beside-a-template)). The print refuses it, and reads nothing, when:
-
-- **It names no file of the method.** It climbs above the folder holding `METHODS.toml`, it names a folder or a missing file, or it names a file the method leaves out, such as a hidden or a gitignored one.
-- **It names a file that is not an image, a stylesheet or a font.** A document reads only those from its method, whatever the URL's origin, so a URL a run's input supplies cannot make the document carry the method's Python, its bundles, its manifest or its data, as a `rel="attachment"` link would.
-- **The template belongs to no method's folder**, such as an inline template of a bundle loaded from a string with no file sent beside it, where a relative URL names no file at all.
-- **A document with no HTML names a method file.** Only the relative URLs of an HTML template name one.
-
-A URL the template writes as it is, such as `<img src="logo.png">`, is checked when the method loads, so this error is raised at print for a URL the template builds from the run's inputs. `refusal_code` carries the MTHDS standard's refusal code when the standard names the reason, and is `None` otherwise. The message names the method's files by their paths in the method, never by a path on the machine that prints.
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/toml-error.md b/docs/errors/toml-error.md
deleted file mode 100644
index 8e70fd20f..000000000
--- a/docs/errors/toml-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "TOML parse error"
-description: "Reference for the `TomlError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# TOML parse error
-
-| Field | Value |
-|---|---|
-| `error_type` | `TomlError` |
-| `title` | TOML parse error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/toml-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.misc.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/tool-error.md b/docs/errors/tool-error.md
deleted file mode 100644
index 29c5ffd63..000000000
--- a/docs/errors/tool-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Tool error"
-description: "Reference for the `ToolError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Tool error
-
-| Field | Value |
-|---|---|
-| `error_type` | `ToolError` |
-| `title` | Tool error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/tool-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.system.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/trace-event-mode-error.md b/docs/errors/trace-event-mode-error.md
deleted file mode 100644
index 0f7073a5d..000000000
--- a/docs/errors/trace-event-mode-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Trace event mode"
-description: "Reference for the `TraceEventModeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Trace event mode
-
-Raised when a set of trace events states no single run mode to build a graph in.
-
-| Field | Value |
-|---|---|
-| `error_type` | `TraceEventModeError` |
-| `title` | Trace event mode |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/trace-event-mode-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tracing.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/traceback-message-error.md b/docs/errors/traceback-message-error.md
deleted file mode 100644
index 9075ac35b..000000000
--- a/docs/errors/traceback-message-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Traceback message"
-description: "Reference for the `TracebackMessageError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Traceback message
-
-| Field | Value |
-|---|---|
-| `error_type` | `TracebackMessageError` |
-| `title` | Traceback message |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/traceback-message-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.system.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/tree-module-shadowing-error.md b/docs/errors/tree-module-shadowing-error.md
deleted file mode 100644
index 15671745c..000000000
--- a/docs/errors/tree-module-shadowing-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Tree module shadowing"
-description: "Reference for the `TreeModuleShadowingError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Tree module shadowing
-
-A top-level module of a method tree shares its name with a standard-library module or a module importable outside the tree.
-
-| Field | Value |
-|---|---|
-| `error_type` | `TreeModuleShadowingError` |
-| `title` | Tree module shadowing |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/tree-module-shadowing-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.core.method_trees.exceptions` |
-| Parent class | [`TreePythonError`](tree-python-error.md) |
-| `retryable` | `false` |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/tree-python-error.md b/docs/errors/tree-python-error.md
deleted file mode 100644
index 61cafde32..000000000
--- a/docs/errors/tree-python-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Tree python"
-description: "Reference for the `TreePythonError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Tree python
-
-A method tree's Python cannot be imported in this process.
-
-| Field | Value |
-|---|---|
-| `error_type` | `TreePythonError` |
-| `title` | Tree python |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/tree-python-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.method_trees.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/tree-python-held-error.md b/docs/errors/tree-python-held-error.md
deleted file mode 100644
index 1697e12a9..000000000
--- a/docs/errors/tree-python-held-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Tree python held"
-description: "Reference for the `TreePythonHeldError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Tree python held
-
-Another method tree's Python is held by a run in flight, so this tree's Python cannot load in this process.
-
-| Field | Value |
-|---|---|
-| `error_type` | `TreePythonHeldError` |
-| `title` | Tree python held |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/tree-python-held-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.method_trees.exceptions` |
-| Parent class | [`TreePythonError`](tree-python-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/typesafe-error.md b/docs/errors/typesafe-error.md
deleted file mode 100644
index cdffc1954..000000000
--- a/docs/errors/typesafe-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Typesafe"
-description: "Reference for the `TypesafeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Typesafe
-
-Base for every error this backend raises, so callers can catch the provider as a family.
-
-| Field | Value |
-|---|---|
-| `error_type` | `TypesafeError` |
-| `title` | Typesafe |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/typesafe-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.typesafe.typesafe_exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/typesafe-judgment-response-error.md b/docs/errors/typesafe-judgment-response-error.md
deleted file mode 100644
index 08d4554d8..000000000
--- a/docs/errors/typesafe-judgment-response-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Typesafe judgment response"
-description: "Reference for the `TypesafeJudgmentResponseError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Typesafe judgment response
-
-The TypeSafe API answered a judgment with an answer that is missing, or of the wrong kind.
-
-| Field | Value |
-|---|---|
-| `error_type` | `TypesafeJudgmentResponseError` |
-| `title` | Typesafe judgment response |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/typesafe-judgment-response-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.typesafe.typesafe_exceptions` |
-| Parent class | [`TypesafeError`](typesafe-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/typesafe-question-unsupported-error.md b/docs/errors/typesafe-question-unsupported-error.md
deleted file mode 100644
index 768be068c..000000000
--- a/docs/errors/typesafe-question-unsupported-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Typesafe question unsupported"
-description: "Reference for the `TypesafeQuestionUnsupportedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Typesafe question unsupported
-
-The question is legal MTHDS that this backend will not serve.
-
-| Field | Value |
-|---|---|
-| `error_type` | `TypesafeQuestionUnsupportedError` |
-| `title` | Typesafe question unsupported |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/typesafe-question-unsupported-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.typesafe.typesafe_exceptions` |
-| Parent class | [`TypesafeError`](typesafe-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/unknown-boot-orchestrator-error.md b/docs/errors/unknown-boot-orchestrator-error.md
deleted file mode 100644
index 5e8de5f10..000000000
--- a/docs/errors/unknown-boot-orchestrator-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Unknown boot orchestrator"
-description: "Reference for the `UnknownBootOrchestratorError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Unknown boot orchestrator
-
-An explicit boot orchestrator was requested, but no plugin of that name is registered.
-
-| Field | Value |
-|---|---|
-| `error_type` | `UnknownBootOrchestratorError` |
-| `title` | Unknown boot orchestrator |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/unknown-boot-orchestrator-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/unknown-input-name-error.md b/docs/errors/unknown-input-name-error.md
deleted file mode 100644
index 4114e726f..000000000
--- a/docs/errors/unknown-input-name-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Unknown input name"
-description: "Reference for the `UnknownInputNameError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Unknown input name
-
-A provided input name is not declared by the pipe's signature (D8).
-
-| Field | Value |
-|---|---|
-| `error_type` | `UnknownInputNameError` |
-| `title` | Unknown input name |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/unknown-input-name-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`InputShapingError`](input-shaping-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/unknown-log-sink-error.md b/docs/errors/unknown-log-sink-error.md
deleted file mode 100644
index 5dde9926e..000000000
--- a/docs/errors/unknown-log-sink-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Unknown log sink"
-description: "Reference for the `UnknownLogSinkError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Unknown log sink
-
-A configured log sink has no registered factory.
-
-| Field | Value |
-|---|---|
-| `error_type` | `UnknownLogSinkError` |
-| `title` | Unknown log sink |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/unknown-log-sink-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/unknown-pipe-func-execution-mode-error.md b/docs/errors/unknown-pipe-func-execution-mode-error.md
deleted file mode 100644
index 04ad188aa..000000000
--- a/docs/errors/unknown-pipe-func-execution-mode-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Unknown pipe func execution mode"
-description: "Reference for the `UnknownPipeFuncExecutionModeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Unknown pipe func execution mode
-
-A configured PipeFunc execution mode has no registered executor factory.
-
-| Field | Value |
-|---|---|
-| `error_type` | `UnknownPipeFuncExecutionModeError` |
-| `title` | Unknown pipe func execution mode |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/unknown-pipe-func-execution-mode-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/unknown-secrets-method-error.md b/docs/errors/unknown-secrets-method-error.md
deleted file mode 100644
index 68da6b2df..000000000
--- a/docs/errors/unknown-secrets-method-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Unknown secrets method"
-description: "Reference for the `UnknownSecretsMethodError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Unknown secrets method
-
-A configured secrets method has no registered provider factory.
-
-| Field | Value |
-|---|---|
-| `error_type` | `UnknownSecretsMethodError` |
-| `title` | Unknown secrets method |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/unknown-secrets-method-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/unknown-storage-method-error.md b/docs/errors/unknown-storage-method-error.md
deleted file mode 100644
index 2ca2c0f20..000000000
--- a/docs/errors/unknown-storage-method-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Unknown storage method"
-description: "Reference for the `UnknownStorageMethodError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Unknown storage method
-
-A configured storage method has no registered provider factory.
-
-| Field | Value |
-|---|---|
-| `error_type` | `UnknownStorageMethodError` |
-| `title` | Unknown storage method |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/unknown-storage-method-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.plugins.exceptions` |
-| Parent class | [`PluginError`](plugin-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/unknown-var-prefix-error.md b/docs/errors/unknown-var-prefix-error.md
deleted file mode 100644
index 7f66f2288..000000000
--- a/docs/errors/unknown-var-prefix-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Unknown var prefix"
-description: "Reference for the `UnknownVarPrefixError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Unknown var prefix
-
-Raised when an unknown variable prefix is used in variable substitution.
-
-| Field | Value |
-|---|---|
-| `error_type` | `UnknownVarPrefixError` |
-| `title` | Unknown var prefix |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/unknown-var-prefix-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.secrets.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/unsafe-schema-error.md b/docs/errors/unsafe-schema-error.md
deleted file mode 100644
index 252207366..000000000
--- a/docs/errors/unsafe-schema-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Unsafe schema"
-description: "Reference for the `UnsafeSchemaError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Unsafe schema
-
-| Field | Value |
-|---|---|
-| `error_type` | `UnsafeSchemaError` |
-| `title` | Unsafe schema |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/unsafe-schema-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.cogt.content_generation.exceptions` |
-| Parent class | [`SecurityError`](security-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/uri-read-refused-error.md b/docs/errors/uri-read-refused-error.md
deleted file mode 100644
index 6e08430ea..000000000
--- a/docs/errors/uri-read-refused-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Read outside the run's scope refused"
-description: "Reference for the `UriReadRefusedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Read outside the run's scope refused
-
-Raised when a run asks to read a URL outside what its host lets it read.
-
-| Field | Value |
-|---|---|
-| `error_type` | `UriReadRefusedError` |
-| `title` | Read outside the run's scope refused |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/uri-read-refused-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.tools.uri.exceptions` |
-| Parent class | [`SecurityError`](security-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/validate-bundle-error.md b/docs/errors/validate-bundle-error.md
deleted file mode 100644
index 792f2d3ff..000000000
--- a/docs/errors/validate-bundle-error.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: "Validate bundle"
-description: "Reference for the `ValidateBundleError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Validate bundle
-
-Raised when a bundle is refused while it is loaded or validated: the invalid verdict, carrying one structured item per refusal in ``validation_errors``. Every refusal of the bundle itself becomes one — every parser error, categorized or not, the factory and pipe-validation errors, one ``dry_run`` item per pipe whose dry run failed, an unknown model (``unknown_model``) and any other refusal of the caller's input — each keeping the locators its raise site had, such as a TOML syntax error's ``line`` and ``column`` and an unresolved concept's ``declared_concepts``, while a failure of the tool or its environment propagates as a no-verdict fault instead. A run raises it too, when the bundle it was given is refused while it loads, before any pipe runs: the same verdict, with the same items, that validating the bundle gives.
-
-| Field | Value |
-|---|---|
-| `error_type` | `ValidateBundleError` |
-| `title` | Validate bundle |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/validate-bundle-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.pipeline.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-| `user_action` | `change_input` — Edit the bundle as each validation error says: apply its suggested fix where it has one, after confirming an unsafe one |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/var-fallback-pattern-error.md b/docs/errors/var-fallback-pattern-error.md
deleted file mode 100644
index a5bdf4e2d..000000000
--- a/docs/errors/var-fallback-pattern-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Var fallback pattern"
-description: "Reference for the `VarFallbackPatternError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Var fallback pattern
-
-| Field | Value |
-|---|---|
-| `error_type` | `VarFallbackPatternError` |
-| `title` | Var fallback pattern |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/var-fallback-pattern-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.secrets.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/var-not-found-error.md b/docs/errors/var-not-found-error.md
deleted file mode 100644
index f38c1c246..000000000
--- a/docs/errors/var-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Var not found"
-description: "Reference for the `VarNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Var not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `VarNotFoundError` |
-| `title` | Var not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/var-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.tools.secrets.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/vertex-ai-config-error.md b/docs/errors/vertex-ai-config-error.md
deleted file mode 100644
index 78707314b..000000000
--- a/docs/errors/vertex-ai-config-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "VertexAI configuration error"
-description: "Reference for the `VertexAIConfigError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# VertexAI configuration error
-
-| Field | Value |
-|---|---|
-| `error_type` | `VertexAIConfigError` |
-| `title` | VertexAI configuration error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/vertex-ai-config-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.openai.openai_exceptions` |
-| Parent class | [`CogtError`](cogt-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/vertex-ai-credentials-error.md b/docs/errors/vertex-ai-credentials-error.md
deleted file mode 100644
index d78e2678e..000000000
--- a/docs/errors/vertex-ai-credentials-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "VertexAI credentials error"
-description: "Reference for the `VertexAICredentialsError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# VertexAI credentials error
-
-| Field | Value |
-|---|---|
-| `error_type` | `VertexAICredentialsError` |
-| `title` | VertexAI credentials error |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/vertex-ai-credentials-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.providers.openai.openai_exceptions` |
-| Parent class | [`CredentialsError`](credentials-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/webhook-delivery-error.md b/docs/errors/webhook-delivery-error.md
deleted file mode 100644
index bda1c2fa1..000000000
--- a/docs/errors/webhook-delivery-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Webhook delivery"
-description: "Reference for the `WebhookDeliveryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Webhook delivery
-
-| Field | Value |
-|---|---|
-| `error_type` | `WebhookDeliveryError` |
-| `title` | Webhook delivery |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/webhook-delivery-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_run.exceptions` |
-| Parent class | [`DeliveryError`](delivery-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/with-images-filter-error.md b/docs/errors/with-images-filter-error.md
deleted file mode 100644
index 48a0f6c43..000000000
--- a/docs/errors/with-images-filter-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "With images filter"
-description: "Reference for the `WithImagesFilterError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# With images filter
-
-Raised when | with_images is used on a type without nested images.
-
-| Field | Value |
-|---|---|
-| `error_type` | `WithImagesFilterError` |
-| `title` | With images filter |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/with-images-filter-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.pipe_operators.shared.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/working-memory-consistency-error.md b/docs/errors/working-memory-consistency-error.md
deleted file mode 100644
index 834936f3a..000000000
--- a/docs/errors/working-memory-consistency-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Working memory consistency"
-description: "Reference for the `WorkingMemoryConsistencyError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Working memory consistency
-
-| Field | Value |
-|---|---|
-| `error_type` | `WorkingMemoryConsistencyError` |
-| `title` | Working memory consistency |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/working-memory-consistency-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`WorkingMemoryError`](working-memory-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/working-memory-error.md b/docs/errors/working-memory-error.md
deleted file mode 100644
index 06b26e2ae..000000000
--- a/docs/errors/working-memory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Working memory"
-description: "Reference for the `WorkingMemoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Working memory
-
-| Field | Value |
-|---|---|
-| `error_type` | `WorkingMemoryError` |
-| `title` | Working memory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/working-memory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/working-memory-factory-error.md b/docs/errors/working-memory-factory-error.md
deleted file mode 100644
index a3415c127..000000000
--- a/docs/errors/working-memory-factory-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Working memory factory"
-description: "Reference for the `WorkingMemoryFactoryError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Working memory factory
-
-| Field | Value |
-|---|---|
-| `error_type` | `WorkingMemoryFactoryError` |
-| `title` | Working memory factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/working-memory-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/working-memory-stuff-attribute-not-found-error.md b/docs/errors/working-memory-stuff-attribute-not-found-error.md
deleted file mode 100644
index 864e71f77..000000000
--- a/docs/errors/working-memory-stuff-attribute-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Working memory stuff attribute not found"
-description: "Reference for the `WorkingMemoryStuffAttributeNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Working memory stuff attribute not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `WorkingMemoryStuffAttributeNotFoundError` |
-| `title` | Working memory stuff attribute not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/working-memory-stuff-attribute-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`WorkingMemoryVariableError`](working-memory-variable-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/working-memory-stuff-not-found-error.md b/docs/errors/working-memory-stuff-not-found-error.md
deleted file mode 100644
index 02529993a..000000000
--- a/docs/errors/working-memory-stuff-not-found-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Working memory stuff not found"
-description: "Reference for the `WorkingMemoryStuffNotFoundError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Working memory stuff not found
-
-| Field | Value |
-|---|---|
-| `error_type` | `WorkingMemoryStuffNotFoundError` |
-| `title` | Working memory stuff not found |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/working-memory-stuff-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`WorkingMemoryVariableError`](working-memory-variable-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/working-memory-type-error.md b/docs/errors/working-memory-type-error.md
deleted file mode 100644
index bb64aad07..000000000
--- a/docs/errors/working-memory-type-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Working memory type"
-description: "Reference for the `WorkingMemoryTypeError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Working memory type
-
-| Field | Value |
-|---|---|
-| `error_type` | `WorkingMemoryTypeError` |
-| `title` | Working memory type |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/working-memory-type-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`WorkingMemoryVariableError`](working-memory-variable-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/working-memory-variable-error.md b/docs/errors/working-memory-variable-error.md
deleted file mode 100644
index 2447e8a20..000000000
--- a/docs/errors/working-memory-variable-error.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Working memory variable"
-description: "Reference for the `WorkingMemoryVariableError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Working memory variable
-
-| Field | Value |
-|---|---|
-| `error_type` | `WorkingMemoryVariableError` |
-| `title` | Working memory variable |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/working-memory-variable-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`WorkingMemoryError`](working-memory-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/errors/wrong-scalar-kind-error.md b/docs/errors/wrong-scalar-kind-error.md
deleted file mode 100644
index 5ce95b3fa..000000000
--- a/docs/errors/wrong-scalar-kind-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Wrong scalar kind"
-description: "Reference for the `WrongScalarKindError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Wrong scalar kind
-
-A provided bare value has the wrong JSON kind for the declared concept (D5).
-
-| Field | Value |
-|---|---|
-| `error_type` | `WrongScalarKindError` |
-| `title` | Wrong scalar kind |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/wrong-scalar-kind-error/` |
-| `error_domain` | _(inherited from parent)_ |
-| Defined in | `pipelex.core.memory.exceptions` |
-| Parent class | [`InputShapingError`](input-shaping-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index 38d988607..2e3a8bcff 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -52,7 +52,7 @@ Classification happens once, at **Layer 1**. Layers 2–5 are wrappers: they att
| `error_type` | `str` | The exception class name |
| `message` | `str` | Human-readable message |
| `title` | `str` | Stable human-readable summary — the RFC 7807 `title` |
-| `type_uri` | `str` | Per-class documentation URI — the RFC 7807 `type` |
+| `type_uri` | `str` | Class-derived URI — the RFC 7807 `type`; the per-class pages it named are retired, see [Error codes](#error-codes-and-the-pipelex-error-registry) |
| `error_category` | `str \| None` | `InferenceErrorCategory` value (inference errors only) |
| `error_domain` | `str \| None` | `ErrorDomain` value — `input` / `config` / `runtime`. Declared per class, except on the `CogtError` family where it is [derived from `error_category`](#the-cogterror-family-derives-its-domain-from-its-category) |
| `retryable` | `bool \| None` | Whether a retry could succeed. Declared per class, `retryable = False` on a deterministic refusal of what the caller sent (`BundleResourceNotNamedError`, `BundleResourcePathError`), except on the `CogtError` family where it is derived from `error_category`; left `None`, it is taken from the cause chain, or absent |
@@ -72,6 +72,14 @@ Classification happens once, at **Layer 1**. Layers 2–5 are wrappers: they att
The guard against that is a committed snapshot of the full `(error_type, title, type_uri)` set at `tests/data/errors/error_identity.txt`, regenerated with `make generate-error-identity` (alias `make gei`) and gated by `tests/unit/pipelex/errors/test_error_identity_snapshot.py`. A rename cannot land without producing a reviewable one-line-pair diff on that file at the moment it is made — which is also the moment to plan the matching consumer updates.
+### Error codes and the Pipelex error registry
+
+The MTHDS standard names every error a runner or a client can meet with a code, `input.missing` or `model.unavailable`, and publishes them as its core error registry: one entry per code, declaring its title, the domain whose actor must act, its retry verdict, its steps, its typed parameters and its HTTP status. A problem's `type` is the code's page, `https://mthds.ai/errors/<code>` for a core code. What the standard leaves to implementations, billing, organizations, the hosted catalog, Pipelex's storage, its configuration and plugins and the components it ships, Pipelex names with codes of its own under the `pipelex` extension prefix, which the core registry registers to Pipelex: `pipelex.billing.credit_exhausted`, `pipelex.config.variable_missing`.
+
+The Pipelex codes are authored in one public file, `pipelex/errors/registry/pipelex-error-registry.yaml`, in the standard's registry format. Everything else is generated from it with `make generate-error-registry` (alias `make ger`): the JSON snapshot `pipelex-error-registry.json` beside it, which the package ships, every release publishes as an asset, and `load_pipelex_error_registry()` (`pipelex/errors/registry/registry_document.py`) reads; the typed Python of the codes, `pipelex/errors/registry/pipelex_codes.py`, with a `PipelexErrorCode` member and a closed parameters model per code; and one page per code under `docs/errors/`, which is where a Pipelex code's type URI, `https://docs.pipelex.com/errors/<code>`, leads. [The Error Registry](../contribute/error-registry.md) describes the format's checks and the workflow.
+
+The registry does not yet drive the reports above: `error_type` and the class-derived `type_uri` are still what a report carries, and the per-class pages that `type_uri` named are retired. Moving each raise site and the API's problem documents onto the codes is the next step of this work.
+
### `validation_errors` — structured bundle-validation diagnostics
A bundle-validation failure (`ValidateBundleError`) aggregates per-error data across stages and projects it onto `validation_errors` as a list of typed `ValidationErrorItem`s, so the structured error report an HTTP API surfaces carries machine-mappable diagnostics (not just a single `detail` string). Each item's `category` is one of the **closed** `ValidationErrorCategory` set:
@@ -549,6 +557,8 @@ InferenceErrorCategory.TRANSIENT.is_retryable # True — only TRANSIENT
| File | Purpose |
|------|---------|
| `pipelex/base_exceptions.py` | `PipelexError`, `ErrorReport`, `ErrorDomain`, `ValidationErrorItem`, `error_domain_to_http_status()` |
+| `pipelex/errors/registry/pipelex-error-registry.yaml` | The Pipelex error registry, the single source of the `pipelex.` codes; its snapshot, its typed codes (`pipelex_codes.py`) and its pages are generated from it |
+| `pipelex/errors/registry/registry_document.py` | The typed model of an MTHDS error registry, and `load_pipelex_error_registry()` |
| `pipelex/pipeline/validation_errors.py` | `build_validation_error_items()` — shared CLI/API structured bundle-validation builder |
| `pipelex/validation_error_types.py` | The closed `error_type` registry — `VALIDATION_ERROR_TYPES`, `PipeValidationErrorType`, `PipeFactoryErrorType`, `ValidationResidualErrorType`, `HintLintErrorType` |
| `pipelex/cogt/exceptions.py` | `CogtError`, `InferenceErrorCategory` |
diff --git a/docs/under-the-hood/pipe-func-requirements.md b/docs/under-the-hood/pipe-func-requirements.md
index db7f78382..a9481e26d 100644
--- a/docs/under-the-hood/pipe-func-requirements.md
+++ b/docs/under-the-hood/pipe-func-requirements.md
@@ -105,9 +105,9 @@ For the hosted API, the Daytona sandbox plugin states the package set of the Day
| Error | Domain | When |
| --- | --- | --- |
-| [`MethodRequirementsFileError`](../errors/method-requirements-file-error.md) | `input` | The file holds a line the standard refuses, naming each, or is not UTF-8 text. |
-| [`MethodRequirementsNotMetError`](../errors/method-requirements-not-met-error.md) | `input` | The environment does not meet a requirement, naming each and why, or the deployment refuses the requirements with its own reason, no environment it can build holding them. |
-| [`HostLibraryRequirementsError`](../errors/host-library-requirements-error.md) | `config` | A method of a host's own library directories, loaded beside a caller's bundles, is refused for its requirements. |
-| [`PipeFuncPackageSetUnstatedError`](../errors/pipe-func-package-set-unstated-error.md) | `config` | A sandbox-hosted deployment states no package set for its execution mode. |
+| `MethodRequirementsFileError` | `input` | The file holds a line the standard refuses, naming each, or is not UTF-8 text. |
+| `MethodRequirementsNotMetError` | `input` | The environment does not meet a requirement, naming each and why, or the deployment refuses the requirements with its own reason, no environment it can build holding them. |
+| `HostLibraryRequirementsError` | `config` | A method of a host's own library directories, loaded beside a caller's bundles, is refused for its requirements. |
+| `PipeFuncPackageSetUnstatedError` | `config` | A sandbox-hosted deployment states no package set for its execution mode. |
The first two are `LibraryLoadingError`s carrying one blueprint validation item per line, whose `source` is the file's path in the tree and whose `line` is the line's number, so a validation reports them as an invalid verdict located on the line. They are deliberately not `MethodTreeLoadError`s, which a server reports as its own fault around the library directories it loads.
diff --git a/docs/under-the-hood/template-sandbox.md b/docs/under-the-hood/template-sandbox.md
index 7f35e043e..b22e90bd3 100644
--- a/docs/under-the-hood/template-sandbox.md
+++ b/docs/under-the-hood/template-sandbox.md
@@ -42,11 +42,11 @@ A method template renders without a template loader, so `{% include %}`, `{% ext
Many refusals are visible in the template itself, and validation reports them before anything runs: a template that reads an undeclared underscore name with a dot fails with the `template_private_name` validation error, which names the pipe and the template (`prompt`, `system_prompt`, `template`, `expression`, or `construct field '<path>'`).
-What validation cannot see, because it depends on the values at run time (a method call, a name computed while rendering, or a bracketed key, which is legitimate on a plain dict), is refused where it happens: the render raises [`Jinja2TemplateSecurityError`](../errors/jinja2-template-security-error.md), whose message names the refused attribute or callable and the type it was reached on. A refusal never renders as an empty string, so a prompt is never sent with a hole in it.
+What validation cannot see, because it depends on the values at run time (a method call, a name computed while rendering, or a bracketed key, which is legitimate on a plain dict), is refused where it happens: the render raises `Jinja2TemplateSecurityError`, whose message names the refused attribute or callable and the type it was reached on. A refusal never renders as an empty string, so a prompt is never sent with a hole in it.
-`Jinja2TemplateSecurityError` is a [`SecurityError`](../errors/security-error.md), like `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, the other policy refusals that are never absorbed into a domain answer. A host that treats that family alike, never retrying any of it, catches that base class, and an `except ToolError` around a render does not catch this refusal. The sandbox's budget refusal is a separate error, `Jinja2TemplateBudgetError`, which is a `ToolError` in the input domain (see below). `Jinja2TemplateSecurityError` stays a type of its own, apart from `Jinja2TemplateRenderError`, which a template that fails for any other reason raises.
+`Jinja2TemplateSecurityError` is a `SecurityError`, like `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, the other policy refusals that are never absorbed into a domain answer. A host that treats that family alike, never retrying any of it, catches that base class, and an `except ToolError` around a render does not catch this refusal. The sandbox's budget refusal is a separate error, `Jinja2TemplateBudgetError`, which is a `ToolError` in the input domain (see below). `Jinja2TemplateSecurityError` stays a type of its own, apart from `Jinja2TemplateRenderError`, which a template that fails for any other reason raises.
-A render that would overdraw its budget raises [`Jinja2TemplateBudgetError`](../errors/jinja2-template-budget-error.md), in the input domain, whose message names the operation that was refused and what it would have spent, never the template or a value: for example, *the operator '\*' needs about 1,000,000,000, and 134,217,062 are left*. A template whose macros or includes nest deeper than Python allows raises the same error.
+A render that would overdraw its budget raises `Jinja2TemplateBudgetError`, in the input domain, whose message names the operation that was refused and what it would have spent, never the template or a value: for example, *the operator '\*' needs about 1,000,000,000, and 134,217,062 are left*. A template whose macros or includes nest deeper than Python allows raises the same error.
## How it is built
@@ -99,5 +99,5 @@ A method also writes dotted paths that are not templates: a PipeCompose construc
## Related
- [StuffArtefact & Image Rendering](stuffartefact-and-image-rendering.md): how inputs reach templates, and how images are extracted from them.
-- [`Jinja2TemplateSecurityError`](../errors/jinja2-template-security-error.md): the error a refusal raises at render time.
-- [`Jinja2TemplateBudgetError`](../errors/jinja2-template-budget-error.md): the error a render raises when it would overdraw its budget.
+- `Jinja2TemplateSecurityError`: the error a refusal raises at render time.
+- `Jinja2TemplateBudgetError`: the error a render raises when it would overdraw its budget.
diff --git a/mkdocs.yml b/mkdocs.yml
index b1e643a2c..c32b7bb44 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -59,9 +59,6 @@ plugins:
separator: '[\s\-\.]+'
- redirects:
redirect_maps:
- # `PipelexInterpreterError` was renamed `MthdsParserError`; the error page filename and the
- # `type_uri` it publishes both derive from the class name, so the retired URI needs a redirect.
- 'errors/pipelex-interpreter-error.md': 'errors/mthds-parser-error.md'
'under-the-hood/temporal-deployment.md': 'distributed-execution/index.md'
'distributed-execution/temporal/index.md': 'distributed-execution/index.md'
'distributed-execution/cluster-setup.md': 'distributed-execution/index.md'
@@ -363,6 +360,7 @@ plugins:
- under-the-hood/log-sink-plugins.md: "Log Sink Plugins"
- under-the-hood/document-engine-plugins.md: "Document Engine Plugins"
- under-the-hood/error-model.md: "Error Model"
+ - errors/index.md: "Error Codes"
- under-the-hood/runtime-bridge-and-transport.md: "Runtime Bridge & Transport"
- under-the-hood/distributed-content-generation.md: "Content Generation Across Boundaries"
Project:
@@ -377,6 +375,7 @@ plugins:
- contribute/registration-surface.md: "Registration Surface"
- contribute/inference-family-surface.md: "Inference Family Surface"
- contribute/drift-contracts.md: "Drift Contracts"
+ - contribute/error-registry.md: "The Error Registry"
- contribute/mthds-test-corpus.md: "MTHDS Test Corpus"
- contribute/trace-input-semantics.md: "Tracing Input Semantics"
- contribute/generate-projection-corpus.md: "Projection Fixture Corpus"
@@ -426,24 +425,16 @@ extra_css:
# Pages intentionally excluded from the user-facing nav.
#
# - `CLAUDE.md` is a docs-authoring guide for contributors, not a published page.
-# - `errors/*.md` are generated reference stubs (one per PipelexError subclass) reached
-# via the RFC 7807 `type` URI carried on every ErrorReport. They are not part of any
-# guided navigation flow — the only nav entries are the landing page `errors/index.md`
-# and the macro listing pages (`errors/authoring-and-language.md`, etc., re-included
-# below), and the individual per-class pages live as orphan pages whose existence is
-# declared here so `mkdocs build --strict` does not flag them as accidentally unlisted.
+# - `errors/pipelex/` holds one generated page per code of the Pipelex error registry, reached
+# through the code's type URI and from the index `errors/index.md`, which the nav lists.
+# `pipelex-dev generate-error-registry` writes them all; see docs/contribute/error-registry.md.
# - `agents/*.md` are AI-agent-facing playbooks (debugging workflows, environment
# gotchas) referenced from the root `CLAUDE.md`. They are built and searchable but
# intentionally kept out of the user-facing nav so they don't clutter the reading
# flow for human readers of the docs site.
not_in_nav: |
CLAUDE.md
- errors/*.md
- !errors/index.md
- !errors/authoring-and-language.md
- !errors/execution-and-runtime.md
- !errors/inference-and-providers.md
- !errors/platform-and-tooling.md
+ errors/pipelex/
agents/*.md
nav:
@@ -565,12 +556,7 @@ nav:
- Observer Data Extraction: analytics/data-extraction.md
- Telemetry: setup/telemetry.md
- Usage Statistics: setup/usage-statistics.md
- - Error Reference:
- - Overview: errors/index.md
- - Authoring & language: errors/authoring-and-language.md
- - Execution & runtime: errors/execution-and-runtime.md
- - Inference & providers: errors/inference-and-providers.md
- - Platform & tooling: errors/platform-and-tooling.md
+ - Error Codes: errors/index.md
- Configuration (TOML reference):
- Overview: configuration/index.md
- Pipeline Validation Configuration:
@@ -640,6 +626,7 @@ nav:
- Registration Surface: contribute/registration-surface.md
- Inference Family Surface: contribute/inference-family-surface.md
- Drift Contracts: contribute/drift-contracts.md
+ - The Error Registry: contribute/error-registry.md
- MTHDS Test Corpus: contribute/mthds-test-corpus.md
- Tracing Input Semantics: contribute/trace-input-semantics.md
- Projection Fixture Corpus: contribute/generate-projection-corpus.md
diff --git a/pipelex/base_exceptions.py b/pipelex/base_exceptions.py
index f40604d3a..1572c6883 100644
--- a/pipelex/base_exceptions.py
+++ b/pipelex/base_exceptions.py
@@ -660,15 +660,15 @@ class PipelexError(Exception):
@classmethod
def type_uri(cls) -> str:
- """Return the per-class documentation URI for this error class.
+ """Return the class-derived URI for this error class.
Used as the RFC 7807 ``type`` field on every ``ErrorReport``. Auto-derived
as ``<URLs.error_docs_base>/<kebab-class-name>/`` unless a subclass sets
- :attr:`_declared_type_uri` directly in its own body. The trailing slash
- matches the canonical form MkDocs (with the default
- ``use_directory_urls: true``) and mike's ``/latest/`` alias serve at —
- clients dereferencing the URI hit the docs page directly without a 301
- round-trip.
+ :attr:`_declared_type_uri` directly in its own body. The per-class pages
+ this URI named are retired: an error's documentation is now the page of
+ its code in the MTHDS core registry or the Pipelex error registry
+ (``pipelex/errors/registry/``), and the docs site's ``404.html`` sends a
+ retired class URI to the error codes' index.
Pure function: the base URI is the :data:`pipelex.urls.URLs.error_docs_base`
constant, so this is safe to call before Pipelex bootstrap and inside
@@ -677,8 +677,7 @@ class PipelexError(Exception):
Footgun: ``pascal_case_to_kebab`` is case-folding — acronym-casing
variants of an existing class name collide (``LLMError`` and ``LlmError``
both kebab to ``llm-error``). ``test_pipelex_error_type_uri_uniqueness``
- catches this at CI time, and ``generate_error_pages`` raises loudly at
- docs-generation time. Pick one casing per acronym in the codebase.
+ catches this at CI time. Pick one casing per acronym in the codebase.
"""
declared = cls.__dict__.get("_declared_type_uri")
if isinstance(declared, str):
diff --git a/pipelex/cli/dev_cli/_dev_cli.py b/pipelex/cli/dev_cli/_dev_cli.py
index c1a9a6d91..ce0782c99 100644
--- a/pipelex/cli/dev_cli/_dev_cli.py
+++ b/pipelex/cli/dev_cli/_dev_cli.py
@@ -22,9 +22,13 @@ from pipelex.cli.dev_cli.commands.check_rich_imports_cmd import check_rich_impor
from pipelex.cli.dev_cli.commands.check_rules_sync_cmd import check_rules_sync_cmd
from pipelex.cli.dev_cli.commands.check_urls_cmd import DEFAULT_TIMEOUT, check_urls_cmd
from pipelex.cli.dev_cli.commands.drift.drift_cmd import drift_app
+from pipelex.cli.dev_cli.commands.error_registry.error_registry_cmd import (
+ check_error_registry_cmd,
+ generate_error_registry_cmd,
+ write_error_type_redirects_cmd,
+)
from pipelex.cli.dev_cli.commands.generate_corpus_vocabulary_cmd import generate_corpus_vocabulary_cmd
from pipelex.cli.dev_cli.commands.generate_error_identity_cmd import generate_error_identity_cmd
-from pipelex.cli.dev_cli.commands.generate_error_pages_cmd import generate_error_pages_cmd
from pipelex.cli.dev_cli.commands.generate_mthds_schema_cmd import generate_mthds_schema_cmd
from pipelex.cli.dev_cli.commands.generate_projection_corpus_cmd import generate_projection_corpus_cmd
from pipelex.cli.dev_cli.commands.kit_cmd import kit_app
@@ -49,6 +53,7 @@ class PipelexDevCLI(TyperGroup):
return [
"check-actions-allowlist",
"check-config-sync",
+ "check-error-registry",
"check-hub-layering",
"check-keyword-only",
"check-ledger",
@@ -61,7 +66,7 @@ class PipelexDevCLI(TyperGroup):
"drift",
"generate-corpus-vocabulary",
"generate-error-identity",
- "generate-error-pages",
+ "generate-error-registry",
"generate-mthds-schema",
"generate-projection-corpus",
"kit",
@@ -73,6 +78,7 @@ class PipelexDevCLI(TyperGroup):
"sync-main-config",
"trace-input-semantics",
"update-migration-schemas",
+ "write-error-type-redirects",
]
@override
@@ -229,15 +235,63 @@ def generate_error_identity_command(
sys.exit(1)
[email protected](name="generate-error-pages", help="Generate one docs page per PipelexError subclass under docs/errors/")
-def generate_error_pages_command(
- output: Annotated[str | None, typer.Option("--output", "-o", help="Custom output directory for the error pages")] = None,
+ name="generate-error-registry",
+ help="Write the Pipelex error registry's JSON snapshot, its typed Python and its pages under docs/errors/, from its YAML source",
+)
+def generate_error_registry_command(
quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Output only a single status line")] = False,
) -> None:
- """Generate per-class error documentation pages under ``docs/errors/``."""
+ """Generate every file derived from ``pipelex/errors/registry/pipelex-error-registry.yaml``."""
try:
- output_path = Path(output) if output else None
- generate_error_pages_cmd(output=output_path, quiet=quiet)
+ generate_error_registry_cmd(quiet=quiet)
+ except (typer.Exit, typer.Abort):
+ # Typer control-flow exits carry an intended exit code — not a failure. Let them through.
+ raise
+ except Exception: # ruff: ignore[blind-except]
+ # Dev CLI command root: print a traceback for any unexpected failure and exit non-zero.
+ console = get_console()
+ console.print()
+ console.print("[bold red]Unexpected error occurred[/bold red]")
+ console.print()
+ console.print(Traceback())
+ sys.exit(1)
+
+
+ name="check-error-registry",
+ help="Check the Pipelex error registry against the MTHDS standard, and that every file derived from it is up to date",
+)
+def check_error_registry_command(
+ quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Output only a single status line")] = False,
+) -> None:
+ """Check the error registry and its derived files, without writing anything."""
+ try:
+ check_error_registry_cmd(quiet=quiet)
+ except (typer.Exit, typer.Abort):
+ # Typer control-flow exits carry an intended exit code — not a failure. Let them through.
+ raise
+ except Exception: # ruff: ignore[blind-except]
+ # Dev CLI command root: print a traceback for any unexpected failure and exit non-zero.
+ console = get_console()
+ console.print()
+ console.print("[bold red]Unexpected error occurred[/bold red]")
+ console.print()
+ console.print(Traceback())
+ sys.exit(1)
+
+
+ name="write-error-type-redirects",
+ help="Write, at the root of the published documentation, the redirect that makes each error code's type URI reach its page",
+)
+def write_error_type_redirects_command(
+ site_root: Annotated[str, typer.Option("--site-root", help="The root of the published site: a checkout of its gh-pages branch")],
+ quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Output only a single status line")] = False,
+) -> None:
+ """Write the type URI redirect stubs into a checkout of the published site."""
+ try:
+ write_error_type_redirects_cmd(site_root=Path(site_root), quiet=quiet)
except (typer.Exit, typer.Abort):
# Typer control-flow exits carry an intended exit code — not a failure. Let them through.
raise
diff --git a/pipelex/cli/dev_cli/commands/error_registry/__init__.py b/pipelex/cli/dev_cli/commands/error_registry/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/pipelex/cli/dev_cli/commands/error_registry/codes_generator.py b/pipelex/cli/dev_cli/commands/error_registry/codes_generator.py
new file mode 100644
index 000000000..e82b9fe68
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/error_registry/codes_generator.py
@@ -0,0 +1,282 @@
+"""The generator of ``pipelex/errors/registry/pipelex_codes.py``: the Pipelex codes and their typed parameters.
+
+For each code of the registry the module holds a member of ``PipelexErrorCode`` and a frozen,
+closed and strict pydantic model of its parameters, so that whoever raises a code builds its parameters
+with the types the registry declares and none it does not, a value of another type being refused
+rather than coerced:
+
+- ``identifier`` and ``caller_text`` are ``str``, ``integer`` is ``int``;
+- ``seconds`` is a ``float`` and ``bytes`` an ``int``, neither ever negative;
+- ``sha256`` is a ``str`` of lowercase hexadecimal;
+- ``enum`` is the ``Literal`` of its values, and ``list`` a ``list`` of its items' type, each item
+ constrained as a parameter of that type is;
+- an optional parameter is its type or ``None``, ``None`` by default.
+
+Each model also names its code and its operator-only parameters, which an implementation leaves out of
+every problem it answers to a caller. The text is written so that ``ruff format`` leaves it as it is,
+which the test suite checks by regenerating it.
+"""
+
+from __future__ import annotations
+
+import json
+import textwrap
+from typing import TYPE_CHECKING
+
+from pipelex.cli.dev_cli.commands.error_registry.exceptions import ErrorRegistryError
+from pipelex.errors.registry.registry_document import RegistryItemType, RegistryParam, RegistryParamType
+from pipelex.tools.misc.string_utils import snake_to_pascal_case
+
+if TYPE_CHECKING:
+ from pipelex.errors.registry.registry_document import ErrorRegistryDocument, RegistryEntry
+
+# The builtins the generated annotations name. A field named after one would shadow it in the class's namespace,
+# where pydantic resolves the annotations, so that a later field's `str` or `int` would name that field's default.
+ANNOTATION_BUILTIN_NAMES = frozenset({"str", "int", "float", "list", "frozenset"})
+
+_LINE_LENGTH = 150
+_DOCSTRING_WIDTH = 110
+_SHA256_PATTERN = "^[0-9a-f]{64}$"
+
+
+def _local_code(*, registry: ErrorRegistryDocument, code: str) -> str:
+ """A code without the registry's prefix, which the generated names leave out."""
+ if registry.prefix is not None and code.startswith(f"{registry.prefix}."):
+ return code[len(registry.prefix) + 1 :]
+ return code
+
+
+def code_member_name(*, registry: ErrorRegistryDocument, code: str) -> str:
+ """The ``PipelexErrorCode`` member of a code: its family and name, upper-cased, such as ``BILLING_PLAN_LIMIT``."""
+ return _local_code(registry=registry, code=code).replace(".", "_").upper()
+
+
+def params_class_name(*, registry: ErrorRegistryDocument, code: str) -> str:
+ """The parameters model of a code: its family and name in PascalCase, then ``Params``, such as ``BillingPlanLimitParams``."""
+ return snake_to_pascal_case(_local_code(registry=registry, code=code).replace(".", "_")) + "Params"
+
+
+class _Imports:
+ """Which names the generated module uses, so that it imports exactly those."""
+
+ def __init__(self) -> None:
+ self.uses_annotated = False
+ self.uses_literal = False
+ self.uses_field = False
+
+
+def _literal(*, values: list[str]) -> str:
+ return "Literal[" + ", ".join(json.dumps(value) for value in values) + "]"
+
+
+def _scalar_annotation(*, scalar_type: RegistryParamType, values: list[str] | None, imports: _Imports) -> str:
+ match scalar_type:
+ case RegistryParamType.IDENTIFIER | RegistryParamType.CALLER_TEXT | RegistryParamType.SHA256:
+ return "str"
+ case RegistryParamType.INTEGER | RegistryParamType.BYTES:
+ return "int"
+ case RegistryParamType.SECONDS:
+ return "float"
+ case RegistryParamType.ENUM:
+ imports.uses_literal = True
+ return _literal(values=values or [])
+ case RegistryParamType.LIST:
+ msg = "a list's items are of a scalar type"
+ raise ErrorRegistryError(msg)
+
+
+def _scalar_constraints(*, scalar_type: RegistryParamType) -> list[str]:
+ """The field constraints a scalar type adds to its Python type: none for a list, whose items carry their own."""
+ match scalar_type:
+ case RegistryParamType.SECONDS | RegistryParamType.BYTES:
+ return ["ge=0"]
+ case RegistryParamType.SHA256:
+ return [f"pattern={json.dumps(_SHA256_PATTERN)}"]
+ case (
+ RegistryParamType.IDENTIFIER | RegistryParamType.INTEGER | RegistryParamType.ENUM | RegistryParamType.CALLER_TEXT | RegistryParamType.LIST
+ ):
+ return []
+
+
+def _item_annotation(*, item_type: RegistryItemType, imports: _Imports) -> str:
+ """The annotation of a list's item: its scalar's Python type, constrained as a parameter of that type is."""
+ annotation = _scalar_annotation(scalar_type=item_type.item_type, values=item_type.values, imports=imports)
+ constraints = _scalar_constraints(scalar_type=item_type.item_type)
+ if not constraints:
+ return annotation
+ imports.uses_annotated = True
+ imports.uses_field = True
+ return f"Annotated[{annotation}, Field({', '.join(constraints)})]"
+
+
+def _field_line(*, param_name: str, param: RegistryParam, imports: _Imports) -> str:
+ """The line declaring one parameter's field."""
+ annotation: str
+ if param.param_type.is_list:
+ if param.items is None:
+ msg = f"the list parameter {param_name} declares no items"
+ raise ErrorRegistryError(msg)
+ annotation = f"list[{_item_annotation(item_type=param.items, imports=imports)}]"
+ else:
+ annotation = _scalar_annotation(scalar_type=param.param_type, values=param.values, imports=imports)
+ constraints = _scalar_constraints(scalar_type=param.param_type)
+ if param.optional:
+ annotation = f"{annotation} | None"
+ if constraints:
+ imports.uses_field = True
+ return f" {param_name}: {annotation} = Field(default=None, {', '.join(constraints)})"
+ return f" {param_name}: {annotation} = None"
+ if constraints:
+ imports.uses_field = True
+ return f" {param_name}: {annotation} = Field({', '.join(constraints)})"
+ return f" {param_name}: {annotation}"
+
+
+_DOCSTRING_FAULT = "cannot be written into a docstring as it stands: it holds a backslash or a closing quote"
+
+
+def _breaks_a_docstring(*, text: str) -> bool:
+ """Whether a text would change or end the docstring it is written into: a backslash, or a closing quote."""
+ return "\\" in text or '"""' in text or text.endswith('"')
+
+
+def _docstring_text(*, text: str, where: str) -> str:
+ if _breaks_a_docstring(text=text):
+ msg = f"{where} {_DOCSTRING_FAULT}"
+ raise ErrorRegistryError(msg)
+ return text
+
+
+def generated_code_errors(*, registry: ErrorRegistryDocument, where: str) -> list[str]:
+ """The titles, descriptions and parameters the generated Python cannot hold as they stand.
+
+ A code's title and each parameter's description go into a docstring, where a backslash or a closing
+ quote would change or end it, and each parameter's field is one line, which must stay within the line
+ length the formatter keeps. The generator refuses either, so the checks report them first, as faults of
+ the source, rather than leave the generator to stop on the first one.
+ """
+ errors: list[str] = []
+ for entry in registry.codes:
+ here = f"{where}: {entry.code}"
+ if _breaks_a_docstring(text=entry.title):
+ errors.append(f"{here}: title {_DOCSTRING_FAULT}")
+ for param_name, param in entry.params.items():
+ if _breaks_a_docstring(text=param.description):
+ errors.append(f"{here}: params.{param_name}.description {_DOCSTRING_FAULT}")
+ if len(_field_line(param_name=param_name, param=param, imports=_Imports())) > _LINE_LENGTH:
+ errors.append(f"{here}: the field of the parameter {param_name} runs past {_LINE_LENGTH} characters")
+ return errors
+
+
+def _params_class(*, registry: ErrorRegistryDocument, entry: RegistryEntry, imports: _Imports) -> list[str]:
+ class_name = params_class_name(registry=registry, code=entry.code)
+ member_name = code_member_name(registry=registry, code=entry.code)
+ lines = [f"class {class_name}(PipelexErrorParams):"]
+ title = _docstring_text(text=entry.title, where=f"{entry.code}: title")
+ lines.append(f' """The parameters of `{entry.code}`.')
+ lines.append("")
+ lines.extend(textwrap.wrap(f"{title}.", width=_DOCSTRING_WIDTH, initial_indent=" ", subsequent_indent=" ", break_long_words=False))
+ if entry.params:
+ lines.append("")
+ lines.append(" Attributes:")
+ for param_name, param in entry.params.items():
+ description = _docstring_text(text=param.description, where=f"{entry.code}: params.{param_name}.description")
+ wrapped = textwrap.wrap(
+ f"{param_name}: {description}",
+ width=_DOCSTRING_WIDTH,
+ initial_indent=" ",
+ subsequent_indent=" ",
+ break_long_words=False,
+ break_on_hyphens=False,
+ )
+ lines.extend(wrapped)
+ lines.append(' """')
+ lines.append("")
+ lines.append(f" code: ClassVar[PipelexErrorCode] = PipelexErrorCode.{member_name}")
+ operator_only = [param_name for param_name, param in entry.params.items() if param.operator_only]
+ if operator_only:
+ names = ", ".join(json.dumps(param_name) for param_name in operator_only)
+ lines.append(f" operator_only_params: ClassVar[frozenset[str]] = frozenset({{{names}}})")
+ if entry.params:
+ lines.append("")
+ for param_name, param in entry.params.items():
+ line = _field_line(param_name=param_name, param=param, imports=imports)
+ if len(line) > _LINE_LENGTH:
+ msg = f"{entry.code}: the field of the parameter {param_name} runs past {_LINE_LENGTH} characters"
+ raise ErrorRegistryError(msg)
+ lines.append(line)
+ return lines
+
+
+def render_pipelex_codes(*, registry: ErrorRegistryDocument) -> str:
+ """The text of ``pipelex_codes.py`` for a registry."""
+ imports = _Imports()
+ body: list[str] = [
+ "",
+ "class PipelexErrorCode(StrEnum):",
+ ' """Every code of the Pipelex error registry."""',
+ "",
+ ]
+ body.extend(f" {code_member_name(registry=registry, code=entry.code)} = {json.dumps(entry.code)}" for entry in registry.codes)
+ body.extend(
+ [
+ "",
+ "",
+ "class PipelexErrorParams(BaseModel):",
+ ' """The parameters of a Pipelex code: the base of each code\'s own model, closed, frozen and strict.',
+ "",
+ ' Strict, so that a value of another type is refused rather than coerced: a line given as ``"3"`` or',
+ " ``True`` is refused rather than read as an integer. An integer is still accepted where a number of",
+ " seconds is declared.",
+ "",
+ " Attributes:",
+ " code: The code whose parameters the model holds.",
+ " operator_only_params: The parameters that only whoever runs the runtime may read, which an",
+ " implementation leaves out of every problem it answers to a caller.",
+ ' """',
+ "",
+ ' model_config = ConfigDict(extra="forbid", frozen=True, strict=True)',
+ "",
+ " code: ClassVar[PipelexErrorCode]",
+ " operator_only_params: ClassVar[frozenset[str]] = frozenset()",
+ ]
+ )
+ for entry in registry.codes:
+ body.extend(["", ""])
+ body.extend(_params_class(registry=registry, entry=entry, imports=imports))
+ body.extend(
+ [
+ "",
+ "",
+ "PIPELEX_ERROR_PARAMS: dict[PipelexErrorCode, type[PipelexErrorParams]] = {",
+ ]
+ )
+ for entry in registry.codes:
+ member_name = code_member_name(registry=registry, code=entry.code)
+ body.append(f" PipelexErrorCode.{member_name}: {params_class_name(registry=registry, code=entry.code)},")
+ body.append("}")
+ body.append('"""The parameters model of every Pipelex code."""')
+
+ typing_names = ["ClassVar"]
+ if imports.uses_annotated:
+ typing_names.insert(0, "Annotated")
+ if imports.uses_literal:
+ typing_names.append("Literal")
+ pydantic_names = ["BaseModel", "ConfigDict", "Field"] if imports.uses_field else ["BaseModel", "ConfigDict"]
+ header = [
+ '"""The Pipelex error codes and the typed parameters of each, generated from ``pipelex-error-registry.yaml``.',
+ "",
+ "Generated by ``pipelex-dev generate-error-registry`` (``make generate-error-registry``): never edit it by",
+ "hand. The registry beside it is the single source, and the test suite fails when this module is not what",
+ "the generator writes from it.",
+ '"""',
+ "",
+ "from __future__ import annotations",
+ "",
+ "from enum import StrEnum",
+ f"from typing import {', '.join(typing_names)}",
+ "",
+ f"from pydantic import {', '.join(pydantic_names)}",
+ "",
+ ]
+ return "\n".join([*header, *body]) + "\n"
diff --git a/pipelex/cli/dev_cli/commands/error_registry/error_registry_cmd.py b/pipelex/cli/dev_cli/commands/error_registry/error_registry_cmd.py
new file mode 100644
index 000000000..70319000c
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/error_registry/error_registry_cmd.py
@@ -0,0 +1,90 @@
+"""The commands of Pipelex's error registry: generate its derived files, check them, and write the type URI redirects."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import typer
+
+from pipelex.cli.dev_cli.commands.error_registry.exceptions import ErrorRegistryError
+from pipelex.cli.dev_cli.commands.error_registry.registry_outputs import (
+ check_error_registry,
+ render_outputs,
+ source_errors,
+ summary_line,
+ write_outputs,
+)
+from pipelex.cli.dev_cli.commands.error_registry.type_redirects import write_type_redirects
+from pipelex.runtime_hub import get_console
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+
+def _print_faults(*, heading: str, errors: list[str]) -> None:
+ console = get_console()
+ console.print(f"[bold red]{heading}[/bold red]")
+ for error in errors:
+ console.print(f" - {error}", markup=False, highlight=False)
+
+
+def generate_error_registry_cmd(*, quiet: bool = False) -> None:
+ """Write the registry's snapshot, its typed Python and its documentation pages, from its source and Pipelex's version.
+
+ Nothing is written when the source has a fault: the faults are printed, and the command exits with 1.
+ """
+ console = get_console()
+ checked, errors = source_errors()
+ if checked is None:
+ _print_faults(heading="The error registry is invalid, so nothing was written:", errors=errors)
+ raise typer.Exit(1)
+ report = write_outputs(outputs=render_outputs(checked=checked))
+ if quiet:
+ console.print(
+ f"Error registry: {len(report.written)} written, {len(report.unchanged)} unchanged, {len(report.removed)} removed",
+ markup=False,
+ highlight=False,
+ )
+ return
+ console.print(summary_line(checked=checked), markup=False, highlight=False)
+ for path in report.written:
+ console.print(f" wrote {path}", markup=False, highlight=False)
+ for path in report.removed:
+ console.print(f" removed {path}", markup=False, highlight=False)
+ console.print(f" {len(report.unchanged)} files unchanged", markup=False, highlight=False)
+
+
+def check_error_registry_cmd(*, quiet: bool = False) -> None:
+ """Check the registry, the standard's vendored files and every derived file, and exit with 1 on any fault."""
+ console = get_console()
+ checked, errors = check_error_registry()
+ if errors or checked is None:
+ _print_faults(heading="Error registry check FAILED:", errors=errors)
+ console.print("Run `make generate-error-registry` to rewrite the derived files, after fixing the source.", markup=False, highlight=False)
+ raise typer.Exit(1)
+ line = summary_line(checked=checked)
+ console.print(f"{line}: consistent" if not quiet else f"Error registry {checked.registry.version}: consistent", markup=False, highlight=False)
+
+
+def write_error_type_redirects_cmd(*, site_root: Path, quiet: bool = False) -> None:
+ """Write, at the root of the published documentation, the stub that makes each code's type URI reach its page."""
+ console = get_console()
+ checked, errors = source_errors()
+ if checked is None:
+ _print_faults(heading="The error registry is invalid, so no redirect was written:", errors=errors)
+ raise typer.Exit(1)
+ try:
+ report = write_type_redirects(site_root=site_root, base_url=checked.registry.base_url)
+ except ErrorRegistryError as exc:
+ _print_faults(heading="The published site cannot take the redirects, so none was written:", errors=[str(exc)])
+ raise typer.Exit(1) from exc
+ console.print(
+ f"Error type redirects: {len(report.written)} written, {len(report.unchanged)} unchanged, {len(report.removed)} removed",
+ markup=False,
+ highlight=False,
+ )
+ if not quiet:
+ for code in report.written:
+ console.print(f" wrote {code}", markup=False, highlight=False)
+ for code in report.removed:
+ console.print(f" removed {code}", markup=False, highlight=False)
diff --git a/pipelex/cli/dev_cli/commands/error_registry/exceptions.py b/pipelex/cli/dev_cli/commands/error_registry/exceptions.py
new file mode 100644
index 000000000..b35ed25ce
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/error_registry/exceptions.py
@@ -0,0 +1,7 @@
+"""Exceptions for the error registry tooling (`pipelex-dev generate-error-registry` and its checks)."""
+
+from pipelex.cli.exceptions import PipelexCLIError
+
+
+class ErrorRegistryError(PipelexCLIError):
+ """Raised when the error registry's source, the standard's vendored files or a generated output cannot be used."""
diff --git a/pipelex/cli/dev_cli/commands/error_registry/pages_generator.py b/pipelex/cli/dev_cli/commands/error_registry/pages_generator.py
new file mode 100644
index 000000000..7af0a831b
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/error_registry/pages_generator.py
@@ -0,0 +1,328 @@
+"""The generator of the error code pages under ``docs/errors/``: their index, and one page per Pipelex code.
+
+A code's page is ``docs/errors/<prefix>/<family>/<name>.md``, one directory per segment but the last, as the
+MTHDS standard lays out the core codes' pages, which MkDocs serves at ``/<version>/errors/<prefix>/<family>/<name>/``.
+The type URI, ``https://docs.pipelex.com/errors/<code>``, names no version, so it reaches the page through the
+redirect stub the documentation's deployment writes at the site's root
+(:mod:`pipelex.cli.dev_cli.commands.error_registry.type_redirects`).
+
+The pages follow the MTHDS standard's pages for the core codes, and link to the standard's documentation for
+what a domain, a retry verdict and a step are. They are committed, so that the documentation builds from the
+repository as it stands, and the test suite fails when they are not what this generator writes.
+"""
+
+from __future__ import annotations
+
+import json
+import posixpath
+import re
+from typing import TYPE_CHECKING
+
+from pipelex.cli.dev_cli.commands.error_registry.registry_source import INDEX_PAGE
+from pipelex.errors.registry.registry_document import (
+ RegistryDomain,
+ RegistryItemType,
+ RegistryParam,
+ RegistryParamType,
+ RegistryRaisedAs,
+ RegistryRetry,
+)
+
+if TYPE_CHECKING:
+ from pipelex.errors.registry.registry_document import ErrorRegistryDocument, RegistryEntry
+
+# The pages of the MTHDS standard the generated ones link to.
+MTHDS_DOCS_URL = "https://mthds.ai/latest"
+MTHDS_PROTOCOL_URL = f"{MTHDS_DOCS_URL}/spec/protocol/"
+MTHDS_REGISTRY_URL = f"{MTHDS_DOCS_URL}/spec/error-registry/"
+MTHDS_CORE_CODES_URL = f"{MTHDS_DOCS_URL}/errors/"
+RELEASES_URL = "https://github.com/Pipelex/pipelex/releases"
+
+# The page of this documentation that describes how the registry is maintained.
+CONTRIBUTE_PAGE = "contribute/error-registry.md"
+# The section of this documentation that says how far errors carry the registry's codes.
+ERROR_MODEL_SECTION = "under-the-hood/error-model.md#error-codes-and-the-pipelex-error-registry"
+
+
+def _domain_action(*, domain: RegistryDomain) -> str:
+ """Who acts, per domain, after the protocol's domain table."""
+ match domain:
+ case RegistryDomain.INPUT:
+ return "the caller acts, by changing the request or its inputs"
+ case RegistryDomain.METHOD:
+ return "the method's author acts, by changing the method"
+ case RegistryDomain.ACCOUNT:
+ return "the account's owner acts"
+ case RegistryDomain.OPERATOR:
+ return "whoever runs the runtime acts"
+ case RegistryDomain.RUNTIME:
+ return "nobody could have acted beforehand, so whoever made the call waits, retries or reports the problem"
+
+
+def _domain_actor(*, domain: RegistryDomain) -> str:
+ """The reader the actor's step is aimed at."""
+ match domain:
+ case RegistryDomain.INPUT:
+ return "the caller"
+ case RegistryDomain.METHOD:
+ return "the method's author"
+ case RegistryDomain.ACCOUNT:
+ return "the account's owner"
+ case RegistryDomain.OPERATOR:
+ return "whoever runs the runtime"
+ case RegistryDomain.RUNTIME:
+ return "whoever made the call"
+
+
+def _retry_meaning(*, retry: RegistryRetry) -> str:
+ match retry:
+ case RegistryRetry.NO:
+ return "repeating the operation fails the same way"
+ case RegistryRetry.YES:
+ return "repeating the operation may succeed, after `retry_after` seconds when the problem gives it"
+ case RegistryRetry.OUTCOME_UNKNOWN:
+ return "the operation may already have taken effect, so its outcome is learned before anything is repeated"
+
+
+def _raised_as_meaning(*, raised_as: RegistryRaisedAs) -> str:
+ match raised_as:
+ case RegistryRaisedAs.PROBLEM:
+ return "a problem document, sent as the body of an HTTP response or kept in a run's record"
+ case RegistryRaisedAs.WARNING:
+ return "an item of a validate verdict's `warnings`, which never makes a method invalid"
+ case RegistryRaisedAs.CLIENT:
+ return "an error a client detects itself, never received from a runner"
+
+
+def _link(*, page: str, target: str) -> str:
+ """The relative link from the page ``page`` to ``target``, both from the documentation's root."""
+ path, _, anchor = target.partition("#")
+ relative = posixpath.relpath(path, posixpath.dirname(page))
+ return f"{relative}#{anchor}" if anchor else relative
+
+
+def _front_matter(*, title: str, description: str) -> str:
+ # A JSON string is a valid YAML double-quoted scalar.
+ return f"---\ntitle: {json.dumps(title)}\ndescription: {json.dumps(description, ensure_ascii=False)}\n---\n"
+
+
+def _cell(*, text: str) -> str:
+ """Text made safe for one cell of a Markdown table."""
+ return text.replace("|", "\\|").replace("\n", " ")
+
+
+def _show_template(*, template: str) -> str:
+ """A template as a page shows it: each placeholder as code, a doubled brace as one."""
+ shown = re.sub(r"(?<!\{)\{([a-z][a-z0-9_]*)\}(?!\})", r"`{\1}`", template)
+ return shown.replace("{{", "{").replace("}}", "}")
+
+
+def _family_anchor(*, family: str) -> str:
+ """The anchor of a family's section on the index, set explicitly so that it never depends on the slug rules."""
+ return family.replace(".", "-").replace("_", "-")
+
+
+def _scalar_type_name(*, scalar_type: RegistryParamType, values: list[str] | None) -> str:
+ match scalar_type:
+ case RegistryParamType.ENUM:
+ return "one of " + ", ".join(f"`{value}`" for value in values or [])
+ case (
+ RegistryParamType.IDENTIFIER
+ | RegistryParamType.INTEGER
+ | RegistryParamType.SECONDS
+ | RegistryParamType.BYTES
+ | RegistryParamType.SHA256
+ | RegistryParamType.CALLER_TEXT
+ | RegistryParamType.LIST
+ ):
+ return f"`{scalar_type}`"
+
+
+def _item_type_name(*, item_type: RegistryItemType) -> str:
+ return _scalar_type_name(scalar_type=item_type.item_type, values=item_type.values)
+
+
+def _param_type_name(*, param: RegistryParam) -> str:
+ if param.param_type.is_list and param.items is not None:
+ return f"list of {_item_type_name(item_type=param.items)}"
+ return _scalar_type_name(scalar_type=param.param_type, values=param.values)
+
+
+def _status_cell(*, entry: RegistryEntry) -> str:
+ if entry.status is not None:
+ return f"`{entry.status}`"
+ return f"none ({entry.raised_as})"
+
+
+def render_index_page(*, registry: ErrorRegistryDocument) -> str:
+ """The index of the error codes: every Pipelex code by family, each linking to its page."""
+ page = INDEX_PAGE
+ lines = [
+ _front_matter(
+ title="Error Codes",
+ description="Every Pipelex error code, with its title, domain, retry verdict and HTTP status, each linking to its page.",
+ ),
+ "# Error Codes",
+ "",
+ (
+ "An error code names a situation a runner or a client can meet, and its type URI is the URL of the code's page. "
+ "A code of the MTHDS standard, such as `input.missing`, is a core code, documented with the standard on "
+ f"[mthds.ai]({MTHDS_CORE_CODES_URL}) at `https://mthds.ai/errors/<code>`. A code that starts with `pipelex.` names "
+ "a situation the standard leaves to its implementations, and has its page here, at "
+ f"`{registry.base_url}/<code>`. Each page says what its code means, who must act and what to do, and gives the "
+ "code's steps, parameters and templates."
+ ),
+ "",
+ (
+ "These pages are generated from the Pipelex error registry, which follows the "
+ f"[MTHDS error registry format]({MTHDS_REGISTRY_URL}) under the `{registry.prefix}` prefix the core registry "
+ "registers to Pipelex. The registry is published with every Pipelex release, as the release asset "
+ f"`pipelex-error-registry.json` on [GitHub]({RELEASES_URL}) and inside the `pipelex` package. This is version "
+ f"`{registry.version}` of the registry. [The Error Registry]({_link(page=page, target=CONTRIBUTE_PAGE)}) "
+ "describes how it is maintained."
+ ),
+ "",
+ (
+ "The registry declares the Pipelex codes, but Pipelex's errors do not carry them yet: an error still reports its "
+ "`error_type` and a type URI derived from its class, and giving every error its code is the next step of this "
+ f"work, as the [Error Model]({_link(page=page, target=ERROR_MODEL_SECTION)}) describes."
+ ),
+ "",
+ ]
+ for family in registry.families:
+ name = family.family
+ lines.append(f"## {name} {{ #{_family_anchor(family=name)} }}")
+ lines.append("")
+ lines.append(family.description)
+ lines.append("")
+ lines.append("| Code | Title | Domain | Retry | Status |")
+ lines.append("|---|---|---|---|---|")
+ for entry in registry.codes:
+ if entry.family != name:
+ continue
+ lines.append(
+ f"| [`{entry.code}`]({_link(page=page, target=entry.page_path)}) "
+ f"| {_cell(text=entry.title)} | `{entry.domain}` | `{entry.retry}` | {_status_cell(entry=entry)} |"
+ )
+ lines.append("")
+ return "\n".join(lines)
+
+
+def _next_steps_intro(*, entry: RegistryEntry) -> str:
+ """The sentence above a code's steps, which says who each one is for."""
+ actor = _domain_actor(domain=entry.domain)
+ step = f"[step]({MTHDS_PROTOCOL_URL}#next-steps)"
+ match entry.raised_as:
+ case RegistryRaisedAs.WARNING:
+ return (
+ f"A warning carries no {step} of its own, since it is an item of a validate verdict, so its reader takes "
+ f"one of the code's steps: the first when the reader is the domain's actor, {actor}, and the second for "
+ "any other reader."
+ )
+ case RegistryRaisedAs.CLIENT:
+ return (
+ f"A client that detects this error offers the {step} aimed at whoever reads it: the first when its "
+ f"reader is the domain's actor, {actor}, and the second for any other reader."
+ )
+ case RegistryRaisedAs.PROBLEM:
+ return (
+ f"A problem carries the {step} aimed at whoever reads it: the first when its reader is the domain's "
+ f"actor, {actor}, and the second for any other reader."
+ )
+
+
+def _params_section(*, entry: RegistryEntry) -> list[str]:
+ params = entry.params
+ if not params:
+ return ["This code declares no parameters, so its problems carry no `params`.", ""]
+ lines: list[str] = []
+ if any(param.optional or param.operator_only for param in params.values()):
+ lines.append(
+ "A parameter is present on every occurrence of the code unless it is marked optional, and one marked "
+ "operator-only reaches only whoever runs the runtime, never a caller."
+ )
+ else:
+ lines.append("Every parameter is present on every occurrence of the code.")
+ lines.append("")
+ lines.append("| Name | Type | Description |")
+ lines.append("|---|---|---|")
+ for param_name, param in params.items():
+ marks: list[str] = []
+ if param.optional:
+ marks.append("optional")
+ if param.operator_only:
+ marks.append("operator-only")
+ mark = f" ({', '.join(marks)})" if marks else ""
+ lines.append(f"| `{param_name}` | {_param_type_name(param=param)}{mark} | {_cell(text=param.description)} |")
+ lines.append("")
+ return lines
+
+
+def render_code_page(*, registry: ErrorRegistryDocument, entry: RegistryEntry) -> str:
+ """The page of one code."""
+ code = entry.code
+ page = entry.page_path
+ index = _link(page=page, target=INDEX_PAGE)
+ family_description = next(family.description for family in registry.families if family.family == entry.family)
+ lines = [
+ _front_matter(title=code, description=f"{entry.title}: what the Pipelex error code {code} means, who must act and what to do."),
+ f"# {code}",
+ "",
+ f"**{entry.title}**",
+ "",
+ "| | |",
+ "|---|---|",
+ f"| Type | `{registry.type_uri(code=code)}` |",
+ f"| Family | [`{entry.family}`]({index}#{_family_anchor(family=entry.family)}): {_cell(text=family_description)} |",
+ f"| [Domain]({MTHDS_PROTOCOL_URL}#domain-who-must-act) | `{entry.domain}`: {_domain_action(domain=entry.domain)} |",
+ f"| [Retry]({MTHDS_PROTOCOL_URL}#retry) | `{entry.retry}`: {_retry_meaning(retry=entry.retry)} |",
+ f"| HTTP status | {_status_cell(entry=entry)} |",
+ f"| Raised as | {_raised_as_meaning(raised_as=entry.raised_as)} |",
+ "",
+ "## What it means",
+ "",
+ entry.meaning,
+ "",
+ "## What to do",
+ "",
+ entry.what_to_do,
+ "",
+ "## Next steps",
+ "",
+ _next_steps_intro(entry=entry),
+ "",
+ "| Reader | Kind | Detail |",
+ "|---|---|---|",
+ f"| The domain's actor | `{entry.steps.actor.kind}` | {_cell(text=_show_template(template=entry.steps.actor.detail))} |",
+ f"| Any other reader | `{entry.steps.other.kind}` | {_cell(text=_show_template(template=entry.steps.other.detail))} |",
+ "",
+ "## Detail",
+ "",
+ "The problem's `detail` is written from this template, filled with the occurrence's parameters:",
+ "",
+ f"> {_show_template(template=entry.detail)}",
+ "",
+ "## Parameters",
+ "",
+ *_params_section(entry=entry),
+ "## See also",
+ "",
+ ]
+ lines.extend(f"- [{reference.title}]({_link(page=page, target=reference.href)})" for reference in entry.see or [])
+ lines.append(f"- [The MTHDS error registry format]({MTHDS_REGISTRY_URL}), which describes the members of this page")
+ lines.append(f"- [Error Codes]({index}), every Pipelex code")
+ lines.append("")
+ return "\n".join(lines)
+
+
+def generated_page_paths(*, registry: ErrorRegistryDocument) -> frozenset[str]:
+ """The path of every page :func:`render_pages` writes, from the documentation's root, without rendering them."""
+ return frozenset({INDEX_PAGE, *(entry.page_path for entry in registry.codes)})
+
+
+def render_pages(*, registry: ErrorRegistryDocument) -> dict[str, str]:
+ """Every generated page, by its path from the documentation's root."""
+ pages = {INDEX_PAGE: render_index_page(registry=registry)}
+ for entry in registry.codes:
+ pages[entry.page_path] = render_code_page(registry=registry, entry=entry)
+ return pages
diff --git a/pipelex/cli/dev_cli/commands/error_registry/registry_checks.py b/pipelex/cli/dev_cli/commands/error_registry/registry_checks.py
new file mode 100644
index 000000000..cd12ec505
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/error_registry/registry_checks.py
@@ -0,0 +1,343 @@
+"""The checks of Pipelex's error registry, after the MTHDS standard's own checks of the core registry.
+
+A registry document is checked in three passes, each run only on a document the previous one accepts:
+
+1. the format's JSON Schema, vendored from the standard, which refuses a member missing, unknown or
+ forbidden in its case and a value outside its closed lists;
+2. the typed model Pipelex reads the registry with (:mod:`pipelex.errors.registry.registry_document`),
+ which refuses what the schema refuses, so that the model can never accept a document the schema
+ would not;
+3. the rules a schema cannot state, which the standard's repository applies to the core registry and
+ which apply to an extension registry alike: a family or a code given twice, a code whose family is
+ undeclared, a family no code uses, a code or a family outside the prefix, a template naming a
+ parameter its reader may not see, and a reference to a documentation page that does not exist:
+ one outside the documentation, one under ``docs/errors/`` that this registry does not generate,
+ or one elsewhere that the documentation does not hold.
+ To these, Pipelex adds the rules its own use of the registry needs: the prefix is registered in the
+ core registry under the same base URL, every code a sentence names in backticks exists, every
+ parameter name can be a field of the typed Python generated from the registry, distinct codes
+ generate distinct names in it, and every title, description and parameter can be written into it.
+"""
+
+from __future__ import annotations
+
+import keyword
+import re
+import string
+from typing import TYPE_CHECKING, Any, Protocol, cast
+
+from jsonschema import Draft202012Validator, FormatChecker, ValidationError
+from pydantic import BaseModel
+from pydantic import ValidationError as PydanticValidationError
+
+from pipelex.cli.dev_cli.commands.error_registry.codes_generator import (
+ ANNOTATION_BUILTIN_NAMES,
+ code_member_name,
+ generated_code_errors,
+ params_class_name,
+)
+from pipelex.cli.dev_cli.commands.error_registry.pages_generator import generated_page_paths
+from pipelex.cli.dev_cli.commands.error_registry.registry_source import PAGES_ROOT
+from pipelex.errors.registry.registry_document import ErrorRegistryDocument, RegistryDomain, RegistryEntry
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
+ from pathlib import Path
+
+# A code a sentence names in backticks: segments joined by dots.
+_BACKTICKED_CODE_REGEX = re.compile(r"`([a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+)`")
+_PARAM_NAME_REGEX = re.compile(r"[a-z][a-z0-9_]*")
+
+# The class attributes of a code's generated parameters model, which no parameter may be named after.
+RESERVED_PARAM_NAMES = frozenset({"code", "operator_only_params"})
+
+# The class the generated module defines beside the codes' own models, which no code's model may be named after.
+RESERVED_PARAMS_CLASS_NAMES = frozenset({"PipelexErrorParams"})
+
+
+class _SchemaValidator(Protocol):
+ """The typed view of a jsonschema validator this module uses.
+
+ The `types-jsonschema` stubs type `iter_errors` as an overload whose deprecated second arm carries an unknown
+ type, which strict pyright refuses; this view gives the call a clean type.
+ """
+
+ def iter_errors(self, *, instance: object) -> Iterator[ValidationError]: ...
+
+
+def _code_at(*, document: dict[str, Any], index: str) -> str | None:
+ """The code of the entry at an index of the document's codes, when it has one."""
+ codes: Any = document.get("codes")
+ if not isinstance(codes, list) or not index.isdigit():
+ return None
+ code_list = cast("list[Any]", codes)
+ position = int(index)
+ if position >= len(code_list):
+ return None
+ entry: Any = code_list[position]
+ if not isinstance(entry, dict):
+ return None
+ code: Any = cast("dict[str, Any]", entry).get("code")
+ return code if isinstance(code, str) else None
+
+
+def schema_errors(*, document: dict[str, Any], schema: dict[str, Any], where: str) -> list[str]:
+ """The faults the format's JSON Schema finds, each named by its path in the document, a code's index by the code."""
+ validator = cast("_SchemaValidator", Draft202012Validator(schema, format_checker=FormatChecker()))
+ found_errors: list[ValidationError] = sorted(
+ validator.iter_errors(instance=document), key=lambda found: [str(part) for part in found.absolute_path]
+ )
+ errors: list[str] = []
+ for error in found_errors:
+ parts = [str(part) for part in error.absolute_path]
+ if len(parts) >= 2 and parts[0] == "codes":
+ code = _code_at(document=document, index=parts[1])
+ if code is not None:
+ parts[1] = code
+ path = "/".join(parts) or "(root)"
+ errors.append(f"{where}: {path}: {error.message}")
+ return errors
+
+
+def model_errors(*, document: dict[str, Any], where: str) -> tuple[ErrorRegistryDocument | None, list[str]]:
+ """The typed registry the document validates into, or the faults the typed model finds."""
+ try:
+ return ErrorRegistryDocument.model_validate(document), []
+ except PydanticValidationError as exc:
+ errors: list[str] = []
+ for error in exc.errors():
+ location = "/".join(str(part) for part in error["loc"]) or "(root)"
+ errors.append(f"{where}: {location}: {error['msg']}")
+ return None, errors
+
+
+def placeholders(*, template: str) -> list[str]:
+ """The parameter names a template names.
+
+ Raises:
+ ValueError: When the template is malformed, or a placeholder is not a bare parameter name.
+ """
+ names: list[str] = []
+ for _literal, field_name, format_spec, conversion in string.Formatter().parse(template):
+ if field_name is None:
+ continue
+ if not _PARAM_NAME_REGEX.fullmatch(field_name):
+ msg = f"placeholder {{{field_name}}} is not a parameter name"
+ raise ValueError(msg)
+ if format_spec or conversion:
+ msg = f"placeholder {{{field_name}}} carries a format specification"
+ raise ValueError(msg)
+ names.append(field_name)
+ return names
+
+
+def template_errors(*, entry: RegistryEntry, here: str) -> list[str]:
+ """Templates name declared parameters, and only those the reader of each may see.
+
+ A parameter declared optional may be absent, so no template names it. An operator-only parameter
+ never reaches a caller, so only the actor's step of an operator code, which whoever runs the
+ runtime reads, may name one.
+ """
+ is_operator_code: bool
+ match entry.domain:
+ case RegistryDomain.OPERATOR:
+ is_operator_code = True
+ case RegistryDomain.INPUT | RegistryDomain.METHOD | RegistryDomain.ACCOUNT | RegistryDomain.RUNTIME:
+ is_operator_code = False
+ templates = [
+ ("detail", entry.detail, False),
+ ("steps.actor.detail", entry.steps.actor.detail, is_operator_code),
+ ("steps.other.detail", entry.steps.other.detail, False),
+ ]
+ errors: list[str] = []
+ for template_name, template, operator_reads in templates:
+ try:
+ names = placeholders(template=template)
+ except ValueError as exc:
+ errors.append(f"{here}: {template_name}: {exc}")
+ continue
+ for param_name in names:
+ declared = entry.params.get(param_name)
+ if declared is None:
+ errors.append(f"{here}: {template_name} names {{{param_name}}}, which the code does not declare")
+ elif declared.optional:
+ errors.append(f"{here}: {template_name} names {{{param_name}}}, which is optional and may be absent")
+ elif declared.operator_only and not operator_reads:
+ errors.append(f"{here}: {template_name} names the operator-only {{{param_name}}}, which a caller may read")
+ return errors
+
+
+def _entry_texts(*, entry: RegistryEntry) -> list[tuple[str, str]]:
+ """Every sentence of an entry, with the member it is written in."""
+ texts = [
+ ("title", entry.title),
+ ("detail", entry.detail),
+ ("steps.actor.detail", entry.steps.actor.detail),
+ ("steps.other.detail", entry.steps.other.detail),
+ ("meaning", entry.meaning),
+ ("what_to_do", entry.what_to_do),
+ ]
+ texts.extend((f"params.{param_name}.description", param.description) for param_name, param in entry.params.items())
+ return texts
+
+
+def code_reference_errors(*, text: str, here: str, registry: ErrorRegistryDocument, core: ErrorRegistryDocument) -> list[str]:
+ """A code named in backticks exists: a core code in the core registry, a code of this registry's prefix in this one.
+
+ Only a name shaped like a code of one of the two registries is checked: two segments whose first is
+ a core family, or three whose first is this registry's prefix. A file name such as `codegen.lock`
+ is neither, and is left alone.
+ """
+ core_families = {family.family for family in core.families}
+ errors: list[str] = []
+ for match in _BACKTICKED_CODE_REGEX.finditer(text):
+ name = match.group(1)
+ segments = name.split(".")
+ if len(segments) == 2 and segments[0] in core_families:
+ if core.entry(code=name) is None:
+ errors.append(f"{here} names `{name}`, which the core registry {core.version} does not declare")
+ elif len(segments) == 3 and segments[0] == registry.prefix:
+ if registry.entry(code=name) is None:
+ errors.append(f"{here} names `{name}`, which this registry does not declare")
+ return errors
+
+
+def param_name_errors(*, entry: RegistryEntry, here: str) -> list[str]:
+ """Every parameter name can be a field of the typed Python generated from the registry."""
+ errors: list[str] = []
+ for param_name in entry.params:
+ if keyword.iskeyword(param_name) or keyword.issoftkeyword(param_name):
+ errors.append(f"{here}: the parameter {param_name} is a Python keyword, which the generated parameters model cannot hold")
+ elif param_name in RESERVED_PARAM_NAMES or hasattr(BaseModel, param_name):
+ errors.append(f"{here}: the parameter {param_name} names an attribute of the generated parameters model")
+ elif param_name in ANNOTATION_BUILTIN_NAMES:
+ errors.append(f"{here}: the parameter {param_name} would shadow the builtin {param_name} the generated annotations name")
+ return errors
+
+
+def reference_errors(*, entry: RegistryEntry, here: str, docs_dir: Path, generated_pages: frozenset[str]) -> list[str]:
+ """Every page a code's `see` names is a page of the documentation, its anchor aside.
+
+ The generator owns ``docs/errors/`` whole, and writes its pages from this same registry, so a page there is
+ one the registry generates, whether or not it is on disk yet: a new code may name another new code's page,
+ while a page on disk that the registry no longer generates is one the generator removes. A page anywhere
+ else is one the documentation holds. A page that lies outside the documentation once resolved, through a
+ `..` segment, which the typed model already refuses, or a symbolic link, is refused.
+ """
+ errors: list[str] = []
+ docs_root = docs_dir.resolve()
+ for reference in entry.see or []:
+ page = reference.href.split("#", 1)[0]
+ if not (docs_dir / page).resolve().is_relative_to(docs_root):
+ errors.append(f"{here}: see names {page}, which lies outside the documentation")
+ elif page.startswith(f"{PAGES_ROOT}/"):
+ if page not in generated_pages:
+ errors.append(f"{here}: see names {page}, which this registry does not generate")
+ elif not (docs_dir / page).is_file():
+ errors.append(f"{here}: see names {page}, which the documentation does not hold")
+ return errors
+
+
+def generated_name_errors(*, registry: ErrorRegistryDocument, where: str) -> list[str]:
+ """Distinct codes generate distinct ``PipelexErrorCode`` members and distinct parameters models.
+
+ The generated names drop the prefix and join the segments, so ``pipelex.run_job.failed`` and
+ ``pipelex.run.job_failed`` would both be ``RUN_JOB_FAILED`` and ``RunJobFailedParams``, and the second
+ would silently replace the first in the generated module. A code given twice is reported as such, not here.
+ """
+ codes_by_member: dict[str, list[str]] = {}
+ codes_by_class: dict[str, list[str]] = {}
+ errors: list[str] = []
+ for entry in registry.codes:
+ member_codes = codes_by_member.setdefault(code_member_name(registry=registry, code=entry.code), [])
+ if entry.code not in member_codes:
+ member_codes.append(entry.code)
+ class_name = params_class_name(registry=registry, code=entry.code)
+ class_codes = codes_by_class.setdefault(class_name, [])
+ if entry.code not in class_codes:
+ class_codes.append(entry.code)
+ if class_name in RESERVED_PARAMS_CLASS_NAMES:
+ errors.append(f"{where}: {entry.code}: its parameters model would be named {class_name}, which the generated module already defines")
+ for member, codes in codes_by_member.items():
+ if len(codes) > 1:
+ errors.append(f"{where}: the codes {', '.join(codes)} generate the same PipelexErrorCode member, {member}")
+ for class_name, codes in codes_by_class.items():
+ if len(codes) > 1:
+ errors.append(f"{where}: the codes {', '.join(codes)} generate the same parameters model, {class_name}")
+ return errors
+
+
+def semantic_errors(*, registry: ErrorRegistryDocument, core: ErrorRegistryDocument, docs_dir: Path, where: str) -> list[str]:
+ """The rules a JSON Schema cannot state. Run only on a document the schema and the typed model accept."""
+ errors: list[str] = []
+ prefix = registry.prefix
+ families = [family.family for family in registry.families]
+ used_families: set[str] = set()
+ generated_pages = generated_page_paths(registry=registry)
+
+ for family in sorted({name for name in families if families.count(name) > 1}):
+ errors.append(f"{where}: the family {family} is declared twice")
+ if prefix is None:
+ errors.append(f"{where}: an extension registry names its prefix")
+ else:
+ for family in families:
+ if not family.startswith(f"{prefix}."):
+ errors.append(f"{where}: the family {family} does not start with the prefix {prefix}")
+ errors.extend(_registration_errors(registry=registry, core=core, prefix=prefix, where=where))
+
+ for registry_family in registry.families:
+ errors.extend(
+ code_reference_errors(
+ text=registry_family.description, here=f"{where}: {registry_family.family}: description", registry=registry, core=core
+ )
+ )
+
+ seen_codes: set[str] = set()
+ for entry in registry.codes:
+ code = entry.code
+ here = f"{where}: {code}"
+ if code in seen_codes:
+ errors.append(f"{here}: the code is declared twice")
+ seen_codes.add(code)
+ if prefix is not None and not code.startswith(f"{prefix}."):
+ errors.append(f"{here}: the code does not start with the registry's prefix {prefix}")
+ used_families.add(entry.family)
+ if entry.family not in families:
+ errors.append(f"{here}: its family {entry.family} is not declared under families")
+ errors.extend(template_errors(entry=entry, here=here))
+ errors.extend(param_name_errors(entry=entry, here=here))
+ for member, text in _entry_texts(entry=entry):
+ errors.extend(code_reference_errors(text=text, here=f"{here}: {member}", registry=registry, core=core))
+ errors.extend(reference_errors(entry=entry, here=here, docs_dir=docs_dir, generated_pages=generated_pages))
+
+ for family in families:
+ if family not in used_families:
+ errors.append(f"{where}: the family {family} is declared but no code belongs to it")
+ errors.extend(generated_name_errors(registry=registry, where=where))
+ errors.extend(generated_code_errors(registry=registry, where=where))
+ return errors
+
+
+def _registration_errors(*, registry: ErrorRegistryDocument, core: ErrorRegistryDocument, prefix: str, where: str) -> list[str]:
+ """The prefix is registered in the core registry, under the base URL this registry publishes its pages at."""
+ for registered in core.extension_prefixes or []:
+ if registered.prefix == prefix:
+ if registered.base_url != registry.base_url:
+ msg = (
+ f"{where}: the base URL {registry.base_url} is not the {registered.base_url} that the core registry "
+ f"{core.version} registers the prefix {prefix} with"
+ )
+ return [msg]
+ return []
+ return [f"{where}: the core registry {core.version} does not register the prefix {prefix}"]
+
+
+def registry_errors(*, document: dict[str, Any], schema: dict[str, Any], core: ErrorRegistryDocument, docs_dir: Path, where: str) -> list[str]:
+ """Every fault of a registry document: the schema's, then the typed model's, then the rules beyond them."""
+ errors = schema_errors(document=document, schema=schema, where=where)
+ if errors:
+ return errors
+ registry, errors = model_errors(document=document, where=where)
+ if registry is None:
+ return errors
+ return semantic_errors(registry=registry, core=core, docs_dir=docs_dir, where=where)
diff --git a/pipelex/cli/dev_cli/commands/error_registry/registry_outputs.py b/pipelex/cli/dev_cli/commands/error_registry/registry_outputs.py
new file mode 100644
index 000000000..076dd9d24
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/error_registry/registry_outputs.py
@@ -0,0 +1,187 @@
+"""The files derived from Pipelex's error registry: how they are rendered, written and checked.
+
+From the YAML source and Pipelex's version come, and only come:
+
+- the JSON snapshot, ``pipelex/errors/registry/pipelex-error-registry.json``, which the package ships and
+ every release publishes as an asset;
+- the typed Python of the codes, ``pipelex/errors/registry/pipelex_codes.py``;
+- the documentation pages, ``docs/errors/index.md`` and one page per code beneath it.
+
+The generator owns ``docs/errors/`` whole: a page there that it does not write is removed when it writes,
+and reported when it checks. A hidden file, such as ``.DS_Store``, is no page, and is left alone.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from pipelex.cli.dev_cli.commands.error_registry.codes_generator import render_pipelex_codes
+from pipelex.cli.dev_cli.commands.error_registry.exceptions import ErrorRegistryError
+from pipelex.cli.dev_cli.commands.error_registry.pages_generator import render_pages
+from pipelex.cli.dev_cli.commands.error_registry.registry_checks import registry_errors
+from pipelex.cli.dev_cli.commands.error_registry.registry_source import (
+ DOCS_DIR,
+ PAGES_ROOT,
+ PIPELEX_CODES_PATH,
+ REGISTRY_SNAPSHOT_PATH,
+ REGISTRY_SOURCE_PATH,
+ STANDARD_CORE_SNAPSHOT_PATH,
+ STANDARD_SCHEMA_PATH,
+ load_composed_document,
+ load_json_file,
+ load_vendored_record,
+ relative_to_repo,
+ render_snapshot_text,
+ vendored_file_errors,
+)
+from pipelex.errors.registry.registry_document import ErrorRegistryDocument
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+
+class RegistryOutputsReport(BaseModel):
+ """What a write of the derived files did, each file named from the repository's root."""
+
+ model_config = ConfigDict(frozen=True)
+
+ written: list[str] = Field(default_factory=list)
+ unchanged: list[str] = Field(default_factory=list)
+ removed: list[str] = Field(default_factory=list)
+
+
+class CheckedRegistry(BaseModel):
+ """A registry that passed every check of its own, with the document its snapshot holds."""
+
+ model_config = ConfigDict(frozen=True)
+
+ document: dict[str, Any]
+ registry: ErrorRegistryDocument
+ core: ErrorRegistryDocument
+
+
+def load_core_registry() -> ErrorRegistryDocument:
+ """The MTHDS core registry, from the snapshot vendored from the standard."""
+ try:
+ return ErrorRegistryDocument.model_validate(load_json_file(path=STANDARD_CORE_SNAPSHOT_PATH))
+ except ValidationError as exc:
+ msg = f"{relative_to_repo(path=STANDARD_CORE_SNAPSHOT_PATH)} is not a registry the typed model reads: {exc}"
+ raise ErrorRegistryError(msg) from exc
+
+
+def source_errors() -> tuple[CheckedRegistry | None, list[str]]:
+ """The faults of the registry's source and of the standard's vendored files, or the checked registry when there are none.
+
+ A file that cannot be read or parsed, such as a source that is not valid YAML or holds a key twice, a core
+ snapshot that is not valid JSON, or a ``pyproject.toml`` version the registry cannot be published under,
+ is reported as a fault like any other, never raised.
+ """
+ try:
+ return _checked_source()
+ except ErrorRegistryError as exc:
+ return None, [str(exc)]
+
+
+def _checked_source() -> tuple[CheckedRegistry | None, list[str]]:
+ errors = vendored_file_errors(record=load_vendored_record())
+ if errors:
+ return None, errors
+ schema: Any = load_json_file(path=STANDARD_SCHEMA_PATH)
+ if not isinstance(schema, dict):
+ return None, [f"{relative_to_repo(path=STANDARD_SCHEMA_PATH)} is not a JSON Schema"]
+ core = load_core_registry()
+ document = load_composed_document()
+ errors = registry_errors(
+ document=document,
+ schema=schema, # pyright: ignore[reportUnknownArgumentType]
+ core=core,
+ docs_dir=DOCS_DIR,
+ where=relative_to_repo(path=REGISTRY_SOURCE_PATH),
+ )
+ if errors:
+ return None, errors
+ registry = ErrorRegistryDocument.model_validate(document)
+ return CheckedRegistry(document=document, registry=registry, core=core), []
+
+
+def render_outputs(*, checked: CheckedRegistry) -> dict[Path, str]:
+ """Every derived file's text, by its path."""
+ outputs: dict[Path, str] = {
+ REGISTRY_SNAPSHOT_PATH: render_snapshot_text(document=checked.document),
+ PIPELEX_CODES_PATH: render_pipelex_codes(registry=checked.registry),
+ }
+ for page, text in render_pages(registry=checked.registry).items():
+ outputs[DOCS_DIR / page] = text
+ return outputs
+
+
+def orphan_pages(*, outputs: dict[Path, str], pages_dir: Path = DOCS_DIR / PAGES_ROOT) -> list[Path]:
+ """The pages under ``docs/errors/`` that the generator does not write.
+
+ A hidden file, or a file in a hidden directory, is no page: MkDocs skips it, and a file a desktop or an
+ editor leaves there, such as ``.DS_Store``, is neither reported nor removed.
+ """
+ if not pages_dir.is_dir():
+ return []
+ orphans: list[Path] = []
+ for path in sorted(pages_dir.rglob("*")):
+ if not path.is_file() or path in outputs:
+ continue
+ if any(part.startswith(".") for part in path.relative_to(pages_dir).parts):
+ continue
+ orphans.append(path)
+ return orphans
+
+
+def stale_output_errors(*, outputs: dict[Path, str]) -> list[str]:
+ """The derived files that are missing or differ from what the generator writes, and the pages it does not write."""
+ errors: list[str] = []
+ for path, text in outputs.items():
+ if not path.is_file():
+ errors.append(f"{relative_to_repo(path=path)} is missing")
+ elif path.read_text(encoding="utf-8") != text:
+ errors.append(f"{relative_to_repo(path=path)} is not what the generator writes from the registry")
+ errors.extend(f"{relative_to_repo(path=path)} is not a page of the registry" for path in orphan_pages(outputs=outputs))
+ return errors
+
+
+def write_outputs(*, outputs: dict[Path, str]) -> RegistryOutputsReport:
+ """Write every derived file that differs, and remove the pages under ``docs/errors/`` the generator does not write."""
+ written: list[str] = []
+ unchanged: list[str] = []
+ removed: list[str] = []
+ for path, text in outputs.items():
+ if path.is_file() and path.read_text(encoding="utf-8") == text:
+ unchanged.append(relative_to_repo(path=path))
+ continue
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(text, encoding="utf-8", newline="\n")
+ written.append(relative_to_repo(path=path))
+ for path in orphan_pages(outputs=outputs):
+ path.unlink()
+ removed.append(relative_to_repo(path=path))
+ pages_dir = DOCS_DIR / PAGES_ROOT
+ for directory in sorted((path for path in pages_dir.rglob("*") if path.is_dir()), key=lambda found: len(found.parts), reverse=True):
+ if not any(directory.iterdir()):
+ directory.rmdir()
+ return RegistryOutputsReport(written=written, unchanged=unchanged, removed=removed)
+
+
+def check_error_registry() -> tuple[CheckedRegistry | None, list[str]]:
+ """Every fault of the registry: its source's, the vendored files', and every derived file that is stale."""
+ checked, errors = source_errors()
+ if checked is None:
+ return None, errors
+ return checked, stale_output_errors(outputs=render_outputs(checked=checked))
+
+
+def summary_line(*, checked: CheckedRegistry) -> str:
+ """The one line that names the registry, its version and its size."""
+ registry = checked.registry
+ return (
+ f"Pipelex error registry {registry.version} ({relative_to_repo(path=REGISTRY_SOURCE_PATH)}): "
+ f"{len(registry.codes)} codes in {len(registry.families)} families under the prefix {registry.prefix}, "
+ f"checked against the MTHDS core registry {checked.core.version}"
+ )
diff --git a/pipelex/cli/dev_cli/commands/error_registry/registry_source.py b/pipelex/cli/dev_cli/commands/error_registry/registry_source.py
new file mode 100644
index 000000000..bb230dc96
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/error_registry/registry_source.py
@@ -0,0 +1,243 @@
+"""Where Pipelex's error registry and its derived files live, and how its source is read.
+
+The registry is authored once, in ``pipelex/errors/registry/pipelex-error-registry.yaml``, without a
+version: its snapshot takes Pipelex's own version from ``pyproject.toml``, so the number is written in
+one place and every release publishes the registry under it, a pre-release's number in the SemVer form
+the registry format requires (:mod:`pipelex.cli.dev_cli.commands.error_registry.registry_version`).
+Everything else is derived from the source and the version: the JSON snapshot beside it, the typed
+Python of the codes, and the documentation pages under ``docs/errors/``.
+
+The development CLI is not shipped in the wheel, so this module always runs from a checkout and finds
+the repository from its own location.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import tomllib
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from pipelex.cli.dev_cli.commands.error_registry.exceptions import ErrorRegistryError
+from pipelex.cli.dev_cli.commands.error_registry.registry_version import registry_version_of
+
+REPO_ROOT = Path(__file__).resolve().parents[5]
+PYPROJECT_PATH = REPO_ROOT / "pyproject.toml"
+DOCS_DIR = REPO_ROOT / "docs"
+
+REGISTRY_DIR = REPO_ROOT / "pipelex" / "errors" / "registry"
+REGISTRY_SOURCE_PATH = REGISTRY_DIR / "pipelex-error-registry.yaml"
+REGISTRY_SNAPSHOT_PATH = REGISTRY_DIR / "pipelex-error-registry.json"
+PIPELEX_CODES_PATH = REGISTRY_DIR / "pipelex_codes.py"
+
+# The pages, as paths from the documentation's root: the index, and one page per code beneath it.
+PAGES_ROOT = "errors"
+INDEX_PAGE = f"{PAGES_ROOT}/index.md"
+
+STANDARD_DIR = Path(__file__).resolve().parent / "standard"
+STANDARD_SCHEMA_PATH = STANDARD_DIR / "mthds-error-registry.schema.json"
+STANDARD_CORE_SNAPSHOT_PATH = STANDARD_DIR / "mthds-error-registry.json"
+STANDARD_RECORD_PATH = STANDARD_DIR / "vendored.toml"
+
+
+def relative_to_repo(*, path: Path) -> str:
+ """A path as a reader of the repository names it, from its root."""
+ try:
+ return path.resolve().relative_to(REPO_ROOT).as_posix()
+ except ValueError:
+ return str(path)
+
+
+class _UniqueKeyLoader(yaml.SafeLoader):
+ """A safe loader that refuses a mapping holding the same key twice, which a YAML loader would otherwise keep silently.
+
+ It also refuses a complex key, a sequence or a mapping written after `?`, which the registry format never
+ uses and which no Python mapping can hold, as a load fault rather than an unhashable key's `TypeError`.
+ """
+
+
+def _construct_unique_mapping(loader: _UniqueKeyLoader, node: yaml.MappingNode) -> dict[Any, Any]: # kw-only: ignore
+ # A PyYAML constructor, which the loader calls positionally with itself and the node.
+ seen: set[Any] = set()
+ for key_node, _value_node in node.value:
+ if not isinstance(key_node, yaml.ScalarNode):
+ msg = "found a key that is a sequence or a mapping, where the registry's keys are plain names"
+ raise yaml.constructor.ConstructorError(None, None, msg, key_node.start_mark)
+ key: Any = loader.construct_object(key_node, deep=True) # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
+ if key in seen:
+ msg = f"duplicate key {key!r}"
+ raise yaml.constructor.ConstructorError(None, None, msg, key_node.start_mark)
+ seen.add(key)
+ return loader.construct_mapping(node, deep=True)
+
+
+_UniqueKeyLoader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, _construct_unique_mapping)
+
+
+def load_registry_source(*, path: Path = REGISTRY_SOURCE_PATH) -> dict[str, Any]:
+ """The registry's YAML source, as a mapping.
+
+ Raises:
+ ErrorRegistryError: When the file cannot be read, does not parse, holds a key twice or a key that is a
+ sequence or a mapping, or is not a mapping.
+ """
+ try:
+ with path.open(encoding="utf-8") as stream:
+ loaded: Any = yaml.load(stream, Loader=_UniqueKeyLoader) # ruff: ignore[unsafe-yaml-load] - the loader is a SafeLoader subclass
+ except (OSError, UnicodeDecodeError) as exc:
+ msg = f"{relative_to_repo(path=path)} cannot be read: {exc}"
+ raise ErrorRegistryError(msg) from exc
+ except yaml.YAMLError as exc:
+ msg = f"{relative_to_repo(path=path)}: {exc}"
+ raise ErrorRegistryError(msg) from exc
+ if not isinstance(loaded, dict):
+ msg = f"{relative_to_repo(path=path)}: the registry is a mapping of its members"
+ raise ErrorRegistryError(msg)
+ source: dict[str, Any] = {str(key): value for key, value in cast("dict[Any, Any]", loaded).items()}
+ return source
+
+
+def read_pipelex_version(*, pyproject_path: Path = PYPROJECT_PATH) -> str:
+ """Pipelex's version, the `[project].version` of ``pyproject.toml``, which the registry is published under.
+
+ Raises:
+ ErrorRegistryError: When ``pyproject.toml`` cannot be read, does not parse or has no version.
+ """
+ try:
+ project: Any = tomllib.loads(pyproject_path.read_text(encoding="utf-8")).get("project", {})
+ except (OSError, UnicodeDecodeError) as exc:
+ msg = f"{relative_to_repo(path=pyproject_path)} cannot be read: {exc}"
+ raise ErrorRegistryError(msg) from exc
+ except tomllib.TOMLDecodeError as exc:
+ msg = f"{relative_to_repo(path=pyproject_path)} is not valid TOML: {exc}"
+ raise ErrorRegistryError(msg) from exc
+ version: Any = cast("dict[str, Any]", project).get("version") if isinstance(project, dict) else None
+ if not isinstance(version, str):
+ msg = f"{relative_to_repo(path=pyproject_path)} has no [project].version"
+ raise ErrorRegistryError(msg)
+ return version
+
+
+def read_registry_version(*, pyproject_path: Path = PYPROJECT_PATH) -> str:
+ """The version the registry is published under: Pipelex's version, a pre-release's written in SemVer form.
+
+ Raises:
+ ErrorRegistryError: When ``pyproject.toml`` has no version, or one the registry cannot be published under.
+ """
+ package_version = read_pipelex_version(pyproject_path=pyproject_path)
+ try:
+ return registry_version_of(package_version=package_version)
+ except ValueError as exc:
+ msg = f"{relative_to_repo(path=pyproject_path)}: {exc}"
+ raise ErrorRegistryError(msg) from exc
+
+
+def compose_registry_document(*, source: dict[str, Any], version: str) -> dict[str, Any]:
+ """The registry document the snapshot holds: the version first, then the source's members in their order.
+
+ Raises:
+ ErrorRegistryError: When the source writes a version of its own, which only ``pyproject.toml`` holds.
+ """
+ if "version" in source:
+ msg = (
+ f"{relative_to_repo(path=REGISTRY_SOURCE_PATH)} writes a version, but the registry takes Pipelex's version from "
+ f"{relative_to_repo(path=PYPROJECT_PATH)}: remove it"
+ )
+ raise ErrorRegistryError(msg)
+ return {"version": version, **source}
+
+
+def render_snapshot_text(*, document: dict[str, Any]) -> str:
+ """The JSON snapshot's text: two-space indented, its non-ASCII text kept, and a final newline."""
+ return json.dumps(document, indent=2, ensure_ascii=False) + "\n"
+
+
+def load_composed_document() -> dict[str, Any]:
+ """The registry document composed from the committed source and Pipelex's current version, in its SemVer form."""
+ return compose_registry_document(source=load_registry_source(), version=read_registry_version())
+
+
+def load_json_file(*, path: Path) -> Any:
+ """A JSON file's content.
+
+ Raises:
+ ErrorRegistryError: When the file cannot be read or is not valid JSON.
+ """
+ try:
+ return json.loads(path.read_text(encoding="utf-8"))
+ except (OSError, UnicodeDecodeError) as exc:
+ msg = f"{relative_to_repo(path=path)} cannot be read: {exc}"
+ raise ErrorRegistryError(msg) from exc
+ except json.JSONDecodeError as exc:
+ msg = f"{relative_to_repo(path=path)} is not valid JSON: {exc}"
+ raise ErrorRegistryError(msg) from exc
+
+
+class VendoredFile(BaseModel):
+ """One file of the standard copied here: where it lives in the standard's repository, and its digest."""
+
+ model_config = ConfigDict(extra="forbid", frozen=True)
+
+ path: str
+ sha256: str
+
+
+class VendoredSource(BaseModel):
+ """The release or the commit of the standard the vendored files were copied from."""
+
+ model_config = ConfigDict(extra="forbid", frozen=True)
+
+ repository: str
+ ref: str
+ commit: str
+ standard_version: str
+
+
+class VendoredRecord(BaseModel):
+ """The record of the standard's files copied here, which ``vendored.toml`` holds."""
+
+ model_config = ConfigDict(extra="forbid", frozen=True)
+
+ source: VendoredSource
+ files: dict[str, VendoredFile]
+
+
+def load_vendored_record(*, path: Path = STANDARD_RECORD_PATH) -> VendoredRecord:
+ """The record of the vendored standard files.
+
+ Raises:
+ ErrorRegistryError: When the record cannot be read, does not parse or is not such a record.
+ """
+ try:
+ return VendoredRecord.model_validate(tomllib.loads(path.read_text(encoding="utf-8")))
+ except (OSError, UnicodeDecodeError) as exc:
+ msg = f"{relative_to_repo(path=path)} cannot be read: {exc}"
+ raise ErrorRegistryError(msg) from exc
+ except (tomllib.TOMLDecodeError, ValidationError) as exc:
+ msg = f"{relative_to_repo(path=path)} is not a valid record of the vendored standard files: {exc}"
+ raise ErrorRegistryError(msg) from exc
+
+
+def vendored_file_errors(*, record: VendoredRecord, standard_dir: Path = STANDARD_DIR) -> list[str]:
+ """The vendored files that are missing or whose content no longer has the digest the record holds."""
+ errors: list[str] = []
+ for file_name, vendored_file in record.files.items():
+ file_path = standard_dir / file_name
+ if not file_path.is_file():
+ errors.append(f"{relative_to_repo(path=file_path)} is missing, though {relative_to_repo(path=STANDARD_RECORD_PATH)} records it")
+ continue
+ try:
+ digest = hashlib.sha256(file_path.read_bytes()).hexdigest()
+ except OSError as exc:
+ errors.append(f"{relative_to_repo(path=file_path)} cannot be read: {exc}")
+ continue
+ if digest != vendored_file.sha256:
+ errors.append(
+ f"{relative_to_repo(path=file_path)} has the digest {digest}, not the {vendored_file.sha256} that "
+ f"{relative_to_repo(path=STANDARD_RECORD_PATH)} records: the standard's files are copied verbatim and never edited here"
+ )
+ return errors
diff --git a/pipelex/cli/dev_cli/commands/error_registry/registry_version.py b/pipelex/cli/dev_cli/commands/error_registry/registry_version.py
new file mode 100644
index 000000000..f9d09228c
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/error_registry/registry_version.py
@@ -0,0 +1,60 @@
+"""The version Pipelex's error registry is published under: Pipelex's own version, written as SemVer.
+
+Pipelex's version, the ``[project].version`` of ``pyproject.toml``, is a PEP 440 version: ``X.Y.Z`` for a
+release, and ``X.Y.Z`` followed by ``a``, ``b`` or ``rc`` and a number for a pre-release, such as ``0.88.0rc1``.
+The MTHDS registry format writes a registry's version as SemVer, a pre-release following a hyphen, and refuses
+``0.88.0rc1``. So the registry writes a release's number as it is, and a pre-release's with its phase and its
+number as two dot-separated identifiers after a hyphen: ``0.88.0a1`` is ``0.88.0-a.1``, ``0.88.0b2`` is
+``0.88.0-b.2`` and ``0.88.0rc1`` is ``0.88.0-rc.1``. SemVer then orders them as PEP 440 does: ``a`` before ``b``
+before ``rc``, ``rc.2`` before ``rc.10`` because a numeric identifier is compared as a number, and every
+pre-release before its release.
+
+The module needs nothing but the standard library, so that the release workflow runs it on a bare runner, without
+the repository's environment, to learn the version the registry's snapshot must carry:
+
+ python3 -I pipelex/cli/dev_cli/commands/error_registry/registry_version.py 0.88.0rc1
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+
+_PEP440_VERSION_REGEX = re.compile(r"^(?P<release>\d+\.\d+\.\d+)(?:(?P<phase>a|b|rc)(?P<number>\d+))?$")
+
+
+def registry_version_of(*, package_version: str) -> str:
+ """The registry's version for a Pipelex version: a release's number as it is, a pre-release's in SemVer form.
+
+ Raises:
+ ValueError: When the version is neither ``X.Y.Z`` nor ``X.Y.Z`` followed by ``a``, ``b`` or ``rc`` and a
+ number, the only forms Pipelex releases under.
+ """
+ match = _PEP440_VERSION_REGEX.fullmatch(package_version)
+ if match is None:
+ msg = (
+ f"the version '{package_version}' is neither a release, X.Y.Z, nor a pre-release, X.Y.Z followed by a, b or rc "
+ "and a number, so the error registry cannot be published under it"
+ )
+ raise ValueError(msg)
+ phase = match.group("phase")
+ if phase is None:
+ return match.group("release")
+ return f"{match.group('release')}-{phase}.{match.group('number')}"
+
+
+def main() -> None:
+ """Print the registry's version for the Pipelex version given as the only argument, or exit with 2."""
+ arguments = sys.argv[1:]
+ if len(arguments) != 1:
+ print("usage: registry_version.py <pipelex version>", file=sys.stderr)
+ sys.exit(2)
+ try:
+ print(registry_version_of(package_version=arguments[0]))
+ except ValueError as exc:
+ print(f"error: {exc}", file=sys.stderr)
+ sys.exit(2)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/pipelex/cli/dev_cli/commands/error_registry/standard/mthds-error-registry.json b/pipelex/cli/dev_cli/commands/error_registry/standard/mthds-error-registry.json
new file mode 100644
index 000000000..e34490b44
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/error_registry/standard/mthds-error-registry.json
@@ -0,0 +1,4900 @@
+{
+ "version": "7.1.0",
+ "base_url": "https://mthds.ai/errors",
+ "extension_prefixes": [
+ {
+ "prefix": "pipelex",
+ "owner": "Pipelex",
+ "base_url": "https://docs.pipelex.com/errors"
+ }
+ ],
+ "families": [
+ {
+ "family": "request",
+ "description": "The HTTP request itself, before any run."
+ },
+ {
+ "family": "auth",
+ "description": "Credentials and permissions."
+ },
+ {
+ "family": "account",
+ "description": "The account's limits."
+ },
+ {
+ "family": "input",
+ "description": "A run's inputs."
+ },
+ {
+ "family": "method",
+ "description": "The method as written, the validation vocabulary included."
+ },
+ {
+ "family": "pipe",
+ "description": "A pipe failing at run time because of what the method does."
+ },
+ {
+ "family": "model",
+ "description": "The model a step names."
+ },
+ {
+ "family": "provider",
+ "description": "The inference provider behind a model."
+ },
+ {
+ "family": "run",
+ "description": "A run's lifecycle and its reads."
+ },
+ {
+ "family": "security",
+ "description": "Refusals made for safety. An implementation may also record each one as a security event."
+ },
+ {
+ "family": "runtime",
+ "description": "The runtime itself."
+ },
+ {
+ "family": "client",
+ "description": "What a client detects itself, and never receives as a response body."
+ }
+ ],
+ "codes": [
+ {
+ "code": "request.malformed",
+ "title": "The request body cannot be parsed",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The runner cannot parse the request body (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Fix the body so that it parses, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must send a request body that parses."
+ }
+ },
+ "params": {
+ "reason": {
+ "type": "enum",
+ "values": [
+ "not_json",
+ "not_utf8",
+ "bad_base64",
+ "bad_zip"
+ ],
+ "description": "What could not be parsed: the body as JSON, a text entry as UTF-8, a Base64 entry, or a zip archive the request carries."
+ }
+ },
+ "meaning": "The body is not parseable JSON, a Base64 or zip payload it carries is corrupt, or a text entry holds a code point UTF-8 cannot encode. The protocol answers a malformed body with a `422`.",
+ "what_to_do": "Check how the client builds the body: that it serializes valid JSON, writes text in UTF-8, and encodes every Base64 entry in standard padded Base64 with its pad bits zero. Then send the request again.",
+ "see": [
+ {
+ "title": "Method files",
+ "href": "spec/protocol.md#method-files"
+ }
+ ]
+ },
+ {
+ "code": "request.invalid",
+ "title": "The request does not match the route's schema",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The request's field '{field}' does not match the route's schema.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Correct the field '{field}' as the route's schema requires, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must correct the field '{field}' of the request."
+ }
+ },
+ "params": {
+ "field": {
+ "type": "identifier",
+ "description": "The field of the request body that fails the route's schema, as a dotted path."
+ }
+ },
+ "meaning": "The body parses, but a field fails the route's schema. A problem with several such faults carries one item per fault in `errors`, each naming its field in `location.field`. The protocol's refusals of one hash given twice with different sizes, of a blob upload whose bytes differ from the hash in its path, and of an undefined `?type=` category on `GET /models` are this code.",
+ "what_to_do": "Read each fault's `location.field`, compare the request with the route's schema in the protocol's OpenAPI document, correct the request and send it again.",
+ "see": [
+ {
+ "title": "Route reference",
+ "href": "spec/protocol.md#route-reference"
+ }
+ ]
+ },
+ {
+ "code": "request.too_large",
+ "title": "The request exceeds a size limit",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 413,
+ "detail": "The request reaches {size} bytes, past the runner's limit of {limit} bytes.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Make the request smaller than {limit} bytes, then send it again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must make the request smaller than {limit} bytes."
+ }
+ },
+ "params": {
+ "limit": {
+ "type": "bytes",
+ "description": "The bound the request passes."
+ },
+ "size": {
+ "type": "bytes",
+ "description": "The size the request, or the file in it, reached."
+ }
+ },
+ "meaning": "The body, or a file in it, is larger than a size bound of the route. Each implementation sets its own bounds.",
+ "what_to_do": "Make the request fit under `params.limit`. A method's large files can travel by hash to a runner whose `GET /version` declares `blob_store: true`, which keeps them out of the body.",
+ "see": [
+ {
+ "title": "Sending files by hash",
+ "href": "spec/protocol.md#sending-files-by-hash"
+ }
+ ]
+ },
+ {
+ "code": "request.not_found",
+ "title": "No such route",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 404,
+ "detail": "This runner serves no such route.",
+ "steps": {
+ "actor": {
+ "kind": "upgrade",
+ "detail": "Use a client written for the protocol version this runner reports in GET /version, or upgrade the runner."
+ },
+ "other": {
+ "kind": "upgrade",
+ "detail": "Upgrade the client or the runner so that both implement the same protocol version."
+ }
+ },
+ "params": {},
+ "meaning": "The route does not exist on this runner. The client was usually written for a newer or an older protocol version than the runner implements, or it called an optional route the runner does not serve.",
+ "what_to_do": "Read the runner's `GET /version`, which reports the protocol version it implements and whether it keeps a blob store, and use a client that matches it, or upgrade the runner.",
+ "see": [
+ {
+ "title": "The routes",
+ "href": "spec/protocol.md#the-routes"
+ }
+ ]
+ },
+ {
+ "code": "request.method_not_allowed",
+ "title": "The route does not accept this HTTP method",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 405,
+ "detail": "This route does not accept the request's HTTP method.",
+ "steps": {
+ "actor": {
+ "kind": "upgrade",
+ "detail": "Use a client written for the protocol version this runner reports in GET /version, which sends each route the HTTP method the protocol defines."
+ },
+ "other": {
+ "kind": "upgrade",
+ "detail": "Upgrade the client or the runner so that both implement the same protocol version."
+ }
+ },
+ "params": {},
+ "meaning": "The route exists, but not for the HTTP method the request used, which usually means that the client and the runner implement different protocol versions.",
+ "what_to_do": "Check the HTTP method the protocol defines for the route, and use a client that matches the protocol version the runner reports in `GET /version`.",
+ "see": [
+ {
+ "title": "The routes",
+ "href": "spec/protocol.md#the-routes"
+ }
+ ]
+ },
+ {
+ "code": "request.unsupported",
+ "title": "The request uses a form this runtime does not accept",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "This runtime does not accept the form the request's field '{field}' uses (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Send the field '{field}' in a form this runtime accepts, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must send the field '{field}' in a form this runtime accepts."
+ }
+ },
+ "params": {
+ "field": {
+ "type": "identifier",
+ "description": "The field of the request, as a dotted path, that uses the form."
+ },
+ "reason": {
+ "type": "identifier",
+ "description": "Which form the runtime refuses."
+ }
+ },
+ "meaning": "The request is well formed, but uses a form this runtime never supports, such as a method address in a form it does not resolve, or a member that only an extension of another implementation defines.",
+ "what_to_do": "Remove the member, or change its form to one this runtime documents. A request written against the protocol alone uses no form this code refuses."
+ },
+ {
+ "code": "request.idempotency_conflict",
+ "title": "The idempotency key was used for a different request",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The request's idempotency key was already used with a different body.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Send this request with a new idempotency key."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must send the request with a new idempotency key."
+ }
+ },
+ "params": {},
+ "meaning": "An earlier request with the same idempotency key carried another body, so the runtime cannot treat this one as its repeat.",
+ "what_to_do": "Generate a new idempotency key for every distinct request, and reuse a key only to repeat the very same request.",
+ "see": [
+ {
+ "title": "HTTP Runner Protocol",
+ "href": "spec/protocol.md"
+ }
+ ]
+ },
+ {
+ "code": "request.idempotency_key_in_use",
+ "title": "A request under this idempotency key is still running",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "An earlier request with the same idempotency key and the same body is still in flight.",
+ "steps": {
+ "actor": {
+ "kind": "wait",
+ "detail": "Wait for the earlier request to finish, then repeat this one unchanged."
+ },
+ "other": {
+ "kind": "wait",
+ "detail": "Wait for the earlier request to finish, then repeat this one unchanged."
+ }
+ },
+ "params": {},
+ "meaning": "An earlier request with the same idempotency key and the same body has not finished, so the runtime neither runs this one again nor has an answer to return yet.",
+ "what_to_do": "Repeat the request unchanged, after `retry_after` seconds when the problem gives it. Once the first request has finished, the repeat returns its outcome.",
+ "see": [
+ {
+ "title": "HTTP Runner Protocol",
+ "href": "spec/protocol.md"
+ }
+ ]
+ },
+ {
+ "code": "request.already_executed",
+ "title": "The request already ran and its answer is not kept",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The request under this idempotency key already ran, and its answer is not kept.",
+ "steps": {
+ "actor": {
+ "kind": "read_run",
+ "detail": "Read what the first request created, such as its run, rather than sending the request again."
+ },
+ "other": {
+ "kind": "read_run",
+ "detail": "Read what the first request created, such as its run, rather than sending the request again."
+ }
+ },
+ "params": {},
+ "meaning": "The request under this idempotency key ran, and the runtime cannot return its answer a second time.",
+ "what_to_do": "Read the outcome where it is kept, such as the run the first request started. Sending the request again with a new key would run it a second time.",
+ "see": [
+ {
+ "title": "HTTP Runner Protocol",
+ "href": "spec/protocol.md"
+ }
+ ]
+ },
+ {
+ "code": "request.pipe_not_found",
+ "title": "The selected pipe is not in the method",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The method declares no pipe '{pipe}'.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Select a pipe the method declares, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must select a pipe the method declares."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe the request selects."
+ },
+ "suggestions": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The pipes of the method the selection most likely meant, the likeliest first."
+ }
+ },
+ "meaning": "The `pipe_code` the request selects is not a pipe the method declares.",
+ "what_to_do": "Look in `params.suggestions` for the pipe the selection most likely meant, or list the method's pipes, and send the request again with one of them.",
+ "see": [
+ {
+ "title": "Executing a method",
+ "href": "spec/protocol.md#executing-a-method"
+ }
+ ]
+ },
+ {
+ "code": "request.pipe_ambiguous",
+ "title": "The pipe selection matches several pipes",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The pipe selection '{pipe}' matches several pipes: {candidates}.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Select one of the matching pipes by a reference that names it alone, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must select one of the matching pipes unambiguously."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe selection the request gives."
+ },
+ "candidates": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The pipes the selection matches."
+ }
+ },
+ "meaning": "A bare pipe code matches pipes in several domains or methods, so the runtime cannot tell which one the request means.",
+ "what_to_do": "Pick one of `params.candidates` and select it by a reference that names it alone, such as its domain-qualified reference.",
+ "see": [
+ {
+ "title": "Namespace Resolution Rules",
+ "href": "spec/namespace-resolution.md"
+ }
+ ]
+ },
+ {
+ "code": "request.pipe_unspecified",
+ "title": "No pipe is selected",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The request selects no pipe, and the method gives no main pipe to start from.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Select a pipe with pipe_code, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must select a pipe with pipe_code."
+ }
+ },
+ "params": {
+ "candidates": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The pipes the request could select."
+ }
+ },
+ "meaning": "The request names no `pipe_code`, and the method gives no `main_pipe` to start from: its manifest declares none or, with no manifest, its bundles declare none or several.",
+ "what_to_do": "Send a `pipe_code` naming one of `params.candidates`. The method's author can instead declare a `main_pipe`, so that a request without `pipe_code` starts there.",
+ "see": [
+ {
+ "title": "Executing a method",
+ "href": "spec/protocol.md#executing-a-method"
+ }
+ ]
+ },
+ {
+ "code": "request.blobs_missing",
+ "title": "The runner does not hold some files sent by hash",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "This runner does not hold a file the request sends by hash.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Upload each listed blob, or send its file inline if this runner keeps no blob store, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must upload each listed blob, or send its file inline if this runner keeps no blob store."
+ }
+ },
+ "params": {
+ "missing_blobs": {
+ "type": "list",
+ "items": {
+ "type": "sha256"
+ },
+ "description": "Each hash of the request that the runner does not hold, in lowercase hexadecimal."
+ }
+ },
+ "meaning": "A hash entry of the request's `files` names bytes this runner does not hold, or the runner keeps no blob store at all, so it cannot assemble the method's tree. This is the protocol's own refusal of hash entries.",
+ "what_to_do": "Read `params.missing_blobs`. To a runner whose `GET /version` declares `blob_store: true`, upload each listed blob as `POST /blobs/missing` says; to any other runner, send each listed file inline. Then send the request again.",
+ "see": [
+ {
+ "title": "Method files",
+ "href": "spec/protocol.md#method-files"
+ },
+ {
+ "title": "Sending files by hash",
+ "href": "spec/protocol.md#sending-files-by-hash"
+ }
+ ]
+ },
+ {
+ "code": "auth.missing_credential",
+ "title": "No credential was sent",
+ "domain": "account",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 401,
+ "detail": "This route needs a credential, and the request carried none.",
+ "steps": {
+ "actor": {
+ "kind": "check_credentials",
+ "detail": "Send the request with a credential this runtime accepts."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the account's owner for a credential this runtime accepts."
+ }
+ },
+ "params": {},
+ "meaning": "The route requires a credential, and the request carried none. How a runtime authenticates is implementation-defined; the protocol reserves a bearer-token slot, and `GET /version` needs no credential.",
+ "what_to_do": "Configure the client with a credential for this runtime, such as a bearer token in the `Authorization` header, and send the request again.",
+ "see": [
+ {
+ "title": "The routes",
+ "href": "spec/protocol.md#the-routes"
+ }
+ ]
+ },
+ {
+ "code": "auth.invalid_credential",
+ "title": "The credential was refused",
+ "domain": "account",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 401,
+ "detail": "The runtime refused the request's credential.",
+ "steps": {
+ "actor": {
+ "kind": "check_credentials",
+ "detail": "Check that the credential is the one issued for this runtime and that it was not revoked, then send the request again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the account's owner for a valid credential."
+ }
+ },
+ "params": {},
+ "meaning": "The credential is unknown to the runtime, revoked or malformed.",
+ "what_to_do": "Compare the configured credential with the one the account issued, issue a new one if it was revoked, and send the request again."
+ },
+ {
+ "code": "auth.credential_expired",
+ "title": "The credential has expired",
+ "domain": "account",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 401,
+ "detail": "The request's credential has expired.",
+ "steps": {
+ "actor": {
+ "kind": "refresh",
+ "detail": "Fetch a fresh credential, then send the request again with it."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the account's owner for a fresh credential."
+ }
+ },
+ "params": {},
+ "meaning": "The credential was valid and is past its expiry.",
+ "what_to_do": "Fetch a fresh credential, through the refresh its issuer provides, and send the request again with it."
+ },
+ {
+ "code": "auth.forbidden",
+ "title": "The credential does not permit this",
+ "domain": "account",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 403,
+ "detail": "The request's identity lacks '{requirement}', which this operation needs.",
+ "steps": {
+ "actor": {
+ "kind": "request_access",
+ "detail": "Ask for '{requirement}' on this account, then send the request again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the account's owner to grant '{requirement}'."
+ }
+ },
+ "params": {
+ "requirement": {
+ "type": "identifier",
+ "description": "The role, flag or session the operation needs."
+ }
+ },
+ "meaning": "The request is authenticated, but its identity lacks the role, the flag or the session the operation needs.",
+ "what_to_do": "Have the account's owner grant what `params.requirement` names, or send the request with an identity that holds it."
+ },
+ {
+ "code": "account.rate_limited",
+ "title": "The account is over its request rate",
+ "domain": "account",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 429,
+ "detail": "The account sent more than {limit} requests in {window} seconds.",
+ "steps": {
+ "actor": {
+ "kind": "wait",
+ "detail": "Wait for the rate window to pass, then send the request again."
+ },
+ "other": {
+ "kind": "wait",
+ "detail": "Wait for the rate window to pass, then send the request again."
+ }
+ },
+ "params": {
+ "limit": {
+ "type": "integer",
+ "description": "The number of requests the account may send in one window."
+ },
+ "window": {
+ "type": "seconds",
+ "description": "The length of the window."
+ }
+ },
+ "meaning": "The account sent more requests than its rate allows.",
+ "what_to_do": "Send the request again after `retry_after` seconds when the problem gives it, and spread later requests so that they stay under the rate."
+ },
+ {
+ "code": "account.quota_exhausted",
+ "title": "The account's quota is used up",
+ "domain": "account",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 429,
+ "detail": "The account's quota '{quota}' is used up.",
+ "steps": {
+ "actor": {
+ "kind": "check_account",
+ "detail": "Check the account's quota '{quota}', and raise it or wait for it to renew."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the account's owner to raise the quota '{quota}'."
+ }
+ },
+ "params": {
+ "quota": {
+ "type": "identifier",
+ "description": "The quota that is spent."
+ }
+ },
+ "meaning": "A quota of the account other than its request rate is spent, so the operation is refused until the quota renews or is raised.",
+ "what_to_do": "Check the account's quotas, then raise the one `params.quota` names or wait until it renews. Repeating the request before then fails the same way."
+ },
+ {
+ "code": "input.missing",
+ "title": "A required input is missing",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The request does not give the input '{input}', which the method requires.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Add the input '{input}' to the request, then send it again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must add the input '{input}' to the request."
+ }
+ },
+ "params": {
+ "input": {
+ "type": "identifier",
+ "description": "The input the method requires and the request omits."
+ }
+ },
+ "meaning": "The request omits an input that the selected pipe requires.",
+ "what_to_do": "Give every input the selected pipe declares as required. A runner that reports `input_form` on `/validate` lists them, with the concept each one takes.",
+ "see": [
+ {
+ "title": "Input-Form Descriptor",
+ "href": "spec/input-form-descriptor.md"
+ }
+ ]
+ },
+ {
+ "code": "input.unexpected",
+ "title": "An input the method does not declare",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The request gives the input '{input}', which the method does not declare.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Remove the input '{input}' from the request, or give it under the name the method declares, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must remove the input '{input}' from the request."
+ }
+ },
+ "params": {
+ "input": {
+ "type": "identifier",
+ "description": "The input the request gives and the method does not declare."
+ }
+ },
+ "meaning": "The request carries an input that the selected pipe does not declare.",
+ "what_to_do": "Check the input's name against the pipe's declared inputs, for a misspelling in particular, and send only those."
+ },
+ {
+ "code": "input.wrong_concept",
+ "title": "An input is not the declared concept",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The input '{input}' is given as '{provided}', but the method accepts '{expected}' there.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Give the input '{input}' as '{expected}', then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must give the input '{input}' as '{expected}'."
+ }
+ },
+ "params": {
+ "input": {
+ "type": "identifier",
+ "description": "The input at fault."
+ },
+ "expected": {
+ "type": "identifier",
+ "description": "The concept the method accepts for the input."
+ },
+ "provided": {
+ "type": "identifier",
+ "description": "The concept the request gives."
+ }
+ },
+ "meaning": "An input names or holds a concept that the method does not accept there, an unknown concept included.",
+ "what_to_do": "Give the input as the concept the method declares, or as one that refines it. A stuff names its concept by its crate key, in its `concept` member.",
+ "see": [
+ {
+ "title": "Stuffs on the wire",
+ "href": "spec/cli-io-contract.md#stuffs-on-the-wire"
+ }
+ ]
+ },
+ {
+ "code": "input.wrong_multiplicity",
+ "title": "An input has the wrong number of items",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The input '{input}' gives {provided_count} item or items, which does not fit the multiplicity the method declares ({expected}).",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Give the input '{input}' with the multiplicity the method declares, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must give the input '{input}' with the multiplicity the method declares."
+ }
+ },
+ "params": {
+ "input": {
+ "type": "identifier",
+ "description": "The input at fault."
+ },
+ "expected": {
+ "type": "enum",
+ "values": [
+ "single",
+ "list",
+ "count"
+ ],
+ "description": "What the method expects: one item, a list of any length, or a list of a fixed length."
+ },
+ "expected_count": {
+ "type": "integer",
+ "optional": true,
+ "description": "The number of items the method expects, when it expects a fixed count."
+ },
+ "provided_count": {
+ "type": "integer",
+ "description": "The number of items the request gives."
+ }
+ },
+ "meaning": "The request gives a list where the method expects one item, one item where it expects a list, or a list of the wrong length.",
+ "what_to_do": "Give one item for a single input, a list for a list input, and exactly `params.expected_count` items for an input of a fixed count.",
+ "see": [
+ {
+ "title": "Multiplicity",
+ "href": "language/multiplicity.md"
+ }
+ ]
+ },
+ {
+ "code": "input.invalid",
+ "title": "An input does not fit its concept's structure",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The input '{input}' does not fit its concept's structure at '{field}'.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Correct the field '{field}' of the input '{input}', then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must correct the field '{field}' of the input '{input}'."
+ }
+ },
+ "params": {
+ "input": {
+ "type": "identifier",
+ "description": "The input at fault."
+ },
+ "field": {
+ "type": "identifier",
+ "description": "The field of the input that fails, as a dotted path."
+ }
+ },
+ "meaning": "An input's value fails its concept's structure, such as a required field that is missing or a value of the wrong type, or breaks the rules of its content type. The problem names the field and never what the check found in the value, which a validator's message can quote and which is the content of the run's input.",
+ "what_to_do": "Compare the input with its concept's structure at the field `params.field` names, and correct the value.",
+ "see": [
+ {
+ "title": "Concepts",
+ "href": "language/concepts.md"
+ }
+ ]
+ },
+ {
+ "code": "input.file_unreadable",
+ "title": "An input file cannot be read",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The file of the input '{input}' cannot be read as '{file_type}' (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Give a readable file as the input '{input}', then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must give a readable file as the input '{input}'."
+ }
+ },
+ "params": {
+ "input": {
+ "type": "identifier",
+ "description": "The input at fault."
+ },
+ "file_type": {
+ "type": "identifier",
+ "description": "The kind of file the input was read as, such as a PDF or an image."
+ },
+ "reason": {
+ "type": "identifier",
+ "description": "Why it could not be read."
+ }
+ },
+ "meaning": "A file given as an input does not decode, parse or open, such as a corrupt PDF or an image whose bytes are not of the format it claims.",
+ "what_to_do": "Open the file locally to check that it is intact and of the format it claims, then send a sound copy."
+ },
+ {
+ "code": "input.file_type_unsupported",
+ "title": "An input file's type is not supported here",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The model '{model}' cannot take the file of the input '{input}', whose format is '{format}'.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Give the input '{input}' in a format the model '{model}' takes, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must give the input '{input}' in a format the model takes."
+ }
+ },
+ "params": {
+ "input": {
+ "type": "identifier",
+ "description": "The input at fault."
+ },
+ "format": {
+ "type": "identifier",
+ "description": "The file's format."
+ },
+ "model": {
+ "type": "identifier",
+ "description": "The model the pipe would send the file to."
+ }
+ },
+ "meaning": "The file's format is one that the pipe, or the model it calls, cannot take.",
+ "what_to_do": "Convert the file to a format the model takes, such as a PDF or a common image format, or use a method whose model takes this one."
+ },
+ {
+ "code": "input.too_large",
+ "title": "An input exceeds a size limit",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The input '{input}' reaches {size}, past the limit of {limit}.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Make the input '{input}' smaller than {limit}, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must make the input '{input}' smaller."
+ }
+ },
+ "params": {
+ "input": {
+ "type": "identifier",
+ "description": "The input at fault."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The bound the input passes."
+ },
+ "size": {
+ "type": "integer",
+ "description": "The size the input, or what a template renders from it, reached."
+ }
+ },
+ "meaning": "An input, or what a template renders from it, passes a bound of the runtime or of the pipe that reads it.",
+ "what_to_do": "Shrink the input below `params.limit`, by splitting a document or reducing an image's resolution, for instance."
+ },
+ {
+ "code": "input.reference_not_found",
+ "title": "An input refers to something that does not exist",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The input '{input}' refers to something that does not exist.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Point the input '{input}' at something that exists, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose input '{input}' refers to something that does not exist."
+ }
+ },
+ "params": {
+ "input": {
+ "type": "identifier",
+ "description": "The input at fault."
+ }
+ },
+ "meaning": "A file path, a stored object or a URL that an input names is not there.",
+ "what_to_do": "Check the reference the input carries: that the file or the object exists, and that the runtime can reach it."
+ },
+ {
+ "code": "input.url_unreachable",
+ "title": "An input's URL could not be fetched",
+ "domain": "input",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The URL of the input '{input}', on '{host}', did not answer or answered with an error.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Send the request again later, or point the input '{input}' at a URL that answers."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose input '{input}' names a URL that did not answer."
+ }
+ },
+ "params": {
+ "input": {
+ "type": "identifier",
+ "description": "The input at fault."
+ },
+ "host": {
+ "type": "identifier",
+ "description": "The host of the URL."
+ }
+ },
+ "meaning": "A URL given in an input did not answer, or answered with an error, when the runtime fetched it. It may answer later.",
+ "what_to_do": "Check that the URL opens from outside your network, then send the request again. If the host keeps failing, send the file itself rather than its URL."
+ },
+ {
+ "code": "method.invalid",
+ "title": "The method does not validate",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The method does not validate.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Fix each fault the problem's errors list, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to fix the faults the problem's errors list."
+ }
+ },
+ "params": {},
+ "meaning": "The umbrella refusal of a method that does not validate. It carries one item per fault in `errors`, each with its own code, and it is the refusal only when at least one of its items is a fault of the method itself.",
+ "what_to_do": "Read each item of `errors`: its code says what is wrong and its `location` where. Fix them, then validate the method with `POST /validate`, which answers its verdict without running it.",
+ "see": [
+ {
+ "title": "Validating a bundle",
+ "href": "spec/protocol.md#validating-a-bundle"
+ },
+ {
+ "title": "Validation Rules",
+ "href": "implementers/validation-rules.md"
+ }
+ ]
+ },
+ {
+ "code": "method.syntax",
+ "title": "The method does not parse",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The method does not parse ({finding}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Fix the syntax at the place the problem's location names, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to fix the method's syntax."
+ }
+ },
+ "params": {
+ "finding": {
+ "type": "caller_text",
+ "description": "What the parser found."
+ }
+ },
+ "meaning": "A `.mthds` file is not valid TOML, or not valid MTHDS syntax. The problem's `location` names the file, the line and the column.",
+ "what_to_do": "Open the file `location.file` names at `location.line`, fix the syntax, and validate the method again. An editor with MTHDS support reports such faults as you type.",
+ "see": [
+ {
+ "title": ".mthds File Format",
+ "href": "spec/mthds-format.md"
+ }
+ ]
+ },
+ {
+ "code": "method.schema_violation",
+ "title": "The method breaks a rule of the language",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The declaration at '{field_path}' breaks a rule of the language ({finding}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Correct the declaration at '{field_path}', then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to correct the declaration at '{field_path}'."
+ }
+ },
+ "params": {
+ "field_path": {
+ "type": "identifier",
+ "description": "The key path of the declaration that breaks the rule."
+ },
+ "finding": {
+ "type": "caller_text",
+ "description": "What the check found."
+ }
+ },
+ "meaning": "A declaration fails the language's schema, or a rule of its pipe type that no sharper code names. It is also the code of a fault of the method that no other code describes.",
+ "what_to_do": "Read the rule for the declaration's section or pipe type in the `.mthds` file format, correct the declaration, and validate the method again.",
+ "see": [
+ {
+ "title": ".mthds File Format",
+ "href": "spec/mthds-format.md"
+ },
+ {
+ "title": "Validation Rules",
+ "href": "implementers/validation-rules.md"
+ }
+ ]
+ },
+ {
+ "code": "method.not_found",
+ "title": "No method at this address",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 404,
+ "detail": "No method is found at '{method_ref}'.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Correct the method's address, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose request names a method that does not exist."
+ }
+ },
+ "params": {
+ "method_ref": {
+ "type": "identifier",
+ "description": "The method address, name or path the request gives."
+ }
+ },
+ "meaning": "The method address, name or path the caller gave names no method.",
+ "what_to_do": "Check the address for a misspelling, and for the version or the path it names, then send the request again.",
+ "see": [
+ {
+ "title": "Distribution",
+ "href": "packages/distribution.md"
+ }
+ ]
+ },
+ {
+ "code": "method.ambiguous",
+ "title": "The method address matches several methods",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The method address '{method_ref}' matches several methods: {candidates}.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Name one of the matching methods by an address that matches it alone, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must name one of the matching methods unambiguously."
+ }
+ },
+ "params": {
+ "method_ref": {
+ "type": "identifier",
+ "description": "The method address, name or directory the request gives."
+ },
+ "candidates": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The methods the address matches."
+ }
+ },
+ "meaning": "The address, the name or the directory matches several packages or installed methods.",
+ "what_to_do": "Pick one of `params.candidates`, and name it by an address that matches it alone."
+ },
+ {
+ "code": "method.fetch_failed",
+ "title": "The method could not be fetched",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 502,
+ "detail": "The method '{method_ref}', or one of its dependencies, could not be fetched.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Send the request again, since the host serving the method may answer later."
+ },
+ "other": {
+ "kind": "retry",
+ "detail": "Send the request again, since the host serving the method may answer later."
+ }
+ },
+ "params": {
+ "method_ref": {
+ "type": "identifier",
+ "description": "The method or the dependency that could not be fetched."
+ }
+ },
+ "meaning": "The host serving the method, or one of its dependencies, did not answer or failed while the runtime fetched it.",
+ "what_to_do": "Send the request again after a while. If the host keeps failing, check that the method's repository is reachable from the runtime.",
+ "see": [
+ {
+ "title": "Distribution",
+ "href": "packages/distribution.md"
+ }
+ ]
+ },
+ {
+ "code": "method.package_invalid",
+ "title": "The method's package breaks a package rule",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The method's package breaks a package rule (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Bring the method's tree within the package rules, then send it again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to bring the method's tree within the package rules."
+ }
+ },
+ "params": {
+ "reason": {
+ "type": "identifier",
+ "description": "The package rule the method breaks."
+ },
+ "path": {
+ "type": "identifier",
+ "optional": true,
+ "description": "The tree path at fault, when one is."
+ },
+ "limit": {
+ "type": "integer",
+ "optional": true,
+ "description": "The limit the package passes, when the rule is a limit."
+ }
+ },
+ "meaning": "The package's layout, manifest, lock, files or size break a rule: a symbolic link, too many files or bytes, no manifest, no source, or file names that clash or cannot be loaded. The protocol's refusals of a `files` map that is not a tree, and of a blob or a tree past a runner's limits, are this code.",
+ "what_to_do": "Read `params.reason`, and `params.path` or `params.limit` when they are given, then fix the tree: remove the symbolic link, rename the clashing file, or trim the tree under the limit.",
+ "see": [
+ {
+ "title": "Method Tree",
+ "href": "spec/method-tree.md"
+ },
+ {
+ "title": "Method files",
+ "href": "spec/protocol.md#method-files"
+ }
+ ]
+ },
+ {
+ "code": "method.dependency_missing",
+ "title": "A dependency of the method is not available",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The method depends on the {kind} '{name}', which is not available here (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Declare a dependency this runtime can satisfy in place of '{name}', then send the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to declare a dependency this runtime can satisfy in place of '{name}'."
+ }
+ },
+ "params": {
+ "kind": {
+ "type": "enum",
+ "values": [
+ "package",
+ "function",
+ "requirement"
+ ],
+ "description": "What is missing: a package, a function the method calls, or a Python requirement of the tree's `requirements.txt`."
+ },
+ "name": {
+ "type": "identifier",
+ "description": "The missing dependency's name."
+ },
+ "reason": {
+ "type": "enum",
+ "values": [
+ "not_found",
+ "no_matching_version",
+ "cycle"
+ ],
+ "description": "Why it is not available: it exists nowhere this runtime looks, no version satisfies the method's constraints, or the dependencies form a cycle."
+ }
+ },
+ "meaning": "A package or a function the method depends on is not available here, no version satisfies the method's constraints, the dependencies form a cycle, or this runtime cannot satisfy a Python requirement of the tree's `requirements.txt`.",
+ "what_to_do": "Check the dependency's name and version constraint, in the manifest or in `requirements.txt`, and correct or loosen it so that an available version satisfies it.",
+ "see": [
+ {
+ "title": "Dependencies",
+ "href": "packages/dependencies.md"
+ },
+ {
+ "title": "Method Tree",
+ "href": "spec/method-tree.md"
+ }
+ ]
+ },
+ {
+ "code": "method.dependency_invalid",
+ "title": "A dependency of the method does not load",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "A file of the dependency '{package}' does not load ({finding}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Depend on a version of '{package}' whose files load, then send the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to depend on a version of '{package}' whose files load."
+ }
+ },
+ "params": {
+ "package": {
+ "type": "identifier",
+ "description": "The dependency package that does not load."
+ },
+ "finding": {
+ "type": "caller_text",
+ "description": "What the parser found."
+ }
+ },
+ "meaning": "A file of a dependency package is not UTF-8, or does not parse.",
+ "what_to_do": "Report the fault to the dependency's owner, and pin a version of it that loads in the meantime.",
+ "see": [
+ {
+ "title": "Dependencies",
+ "href": "packages/dependencies.md"
+ }
+ ]
+ },
+ {
+ "code": "method.resource_missing",
+ "title": "A file the method refers to is not in its tree",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The file reference '{file}' resolves to no file of the method's tree (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Point the reference '{file}' at a file of the method's tree, written as a relative path with forward slashes, then send the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to point the reference '{file}' at a file of the method's tree."
+ }
+ },
+ "params": {
+ "file": {
+ "type": "identifier",
+ "description": "The file reference at fault."
+ },
+ "reason": {
+ "type": "enum",
+ "values": [
+ "not_in_tree",
+ "leaves_tree",
+ "absolute",
+ "backslash",
+ "scheme"
+ ],
+ "description": "Why the reference resolves to no file of the tree: it names none, it climbs above the root, or it is written as an absolute path, with a backslash or with a scheme."
+ }
+ },
+ "meaning": "A file reference names no file of the method's tree, climbs above its root, or is written as an absolute path, with a backslash or with a scheme. Resolving a reference is a lookup in the tree's set of paths and never opens a file, so this is a fault of the method rather than a security matter.",
+ "what_to_do": "Check that the file is in the tree the request sends, and write its reference relative to the referring file, with forward slashes.",
+ "see": [
+ {
+ "title": "File references",
+ "href": "spec/method-tree.md#file-references"
+ }
+ ]
+ },
+ {
+ "code": "method.concept_unresolved",
+ "title": "The method names a concept no library declares",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The method names the concept '{concept}', which no library declares.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Declare the concept '{concept}', or correct the reference, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to declare or correct the concept '{concept}'."
+ }
+ },
+ "params": {
+ "concept": {
+ "type": "identifier",
+ "description": "The concept reference that resolves nowhere."
+ },
+ "suggestions": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The concepts the reference most likely meant, the likeliest first."
+ }
+ },
+ "meaning": "A concept reference resolves to no concept of the bundle, of its domain, of its dependencies or of the native set.",
+ "what_to_do": "Look in `params.suggestions` for the concept the reference most likely meant, then correct the reference or declare the concept.",
+ "see": [
+ {
+ "title": "Namespace Resolution Rules",
+ "href": "spec/namespace-resolution.md"
+ }
+ ]
+ },
+ {
+ "code": "method.pipe_unresolved",
+ "title": "The method names a pipe that does not exist",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' names the pipe '{missing}', which does not exist.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Declare the pipe '{missing}', or correct the reference in pipe '{pipe}', then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to declare or correct the pipe '{missing}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe whose declaration names the missing pipe."
+ },
+ "missing": {
+ "type": "identifier",
+ "description": "The pipe reference that names nothing."
+ },
+ "candidates": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The pipes the reference most likely meant, the likeliest first."
+ }
+ },
+ "meaning": "A controller's step, a branch, an outcome or the manifest's `main_pipe` names a pipe that does not exist.",
+ "what_to_do": "Look in `params.candidates` for the pipe the reference most likely meant, then correct the reference or declare the pipe.",
+ "see": [
+ {
+ "title": "Namespace Resolution Rules",
+ "href": "spec/namespace-resolution.md"
+ }
+ ]
+ },
+ {
+ "code": "method.pipe_not_exported",
+ "title": "The method calls a pipe its dependency does not export",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The method calls the pipe '{pipe}' of '{package}', which does not export it.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Call a pipe that '{package}' exports, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to call only the pipes '{package}' exports."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The dependency's pipe the method calls."
+ },
+ "package": {
+ "type": "identifier",
+ "description": "The dependency that declares the pipe."
+ }
+ },
+ "meaning": "A pipe of a dependency is called, but the dependency does not export it.",
+ "what_to_do": "Read the dependency's `[exports]` for the pipes it offers and call one of them, or ask its owner to export the pipe.",
+ "see": [
+ {
+ "title": "Exports & Visibility",
+ "href": "packages/exports-visibility.md"
+ }
+ ]
+ },
+ {
+ "code": "method.ref_ambiguous",
+ "title": "A reference matches several declarations",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The reference '{ref}' matches several declarations: {candidates}.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Qualify the reference '{ref}' so that it names one declaration, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to qualify the reference '{ref}'."
+ }
+ },
+ "params": {
+ "ref": {
+ "type": "identifier",
+ "description": "The bare reference."
+ },
+ "candidates": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The declarations it matches."
+ }
+ },
+ "meaning": "A bare pipe or concept reference resolves in several packages.",
+ "what_to_do": "Write the reference package-qualified, as `alias->domain.Name`, or domain-qualified, so that it names one of `params.candidates`.",
+ "see": [
+ {
+ "title": "Namespace Resolution Rules",
+ "href": "spec/namespace-resolution.md"
+ }
+ ]
+ },
+ {
+ "code": "method.name_conflict",
+ "title": "A name is declared twice or collides with a reserved one",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The name '{name}' collides with another declaration (conflict: {conflict}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Rename '{name}' so that it is unique and reserved by nothing, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to rename '{name}'."
+ }
+ },
+ "params": {
+ "name": {
+ "type": "identifier",
+ "description": "The name declared twice, or colliding."
+ },
+ "conflict": {
+ "type": "enum",
+ "values": [
+ "duplicate_declaration",
+ "native_concept",
+ "batch_item",
+ "reserved_domain"
+ ],
+ "description": "What the name collides with: another declaration, a native concept, another batch item, or a reserved domain."
+ }
+ },
+ "meaning": "Two declarations share a name, or a name collides with a native concept, with another batch item or with a reserved domain.",
+ "what_to_do": "Rename one of the colliding declarations. A domain may not be one of the reserved domains, and a concept may not take the name of a native one.",
+ "see": [
+ {
+ "title": "Namespace Resolution Rules",
+ "href": "spec/namespace-resolution.md"
+ }
+ ]
+ },
+ {
+ "code": "method.cycle",
+ "title": "Declarations form a cycle",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "These declarations form a cycle: {cycle}.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Break the cycle by removing one of its links, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to break the cycle."
+ }
+ },
+ "params": {
+ "kind": {
+ "type": "enum",
+ "values": [
+ "refines",
+ "structure",
+ "pipe"
+ ],
+ "description": "What forms the cycle: concepts refining each other, structures referring to each other, or pipes calling each other."
+ },
+ "cycle": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The declarations around the cycle, in order."
+ }
+ },
+ "meaning": "Concepts refine or refer to each other, or pipes call each other, in a loop.",
+ "what_to_do": "Follow `params.cycle` and remove one of its links, such as a refinement or a call that leads back to its start."
+ },
+ {
+ "code": "method.identifier_invalid",
+ "title": "A name is not a valid identifier",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The name '{name}' breaks the naming rules of a {identifier_kind}.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Rename '{name}' to a plain snake_case identifier, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to rename '{name}'."
+ }
+ },
+ "params": {
+ "identifier_kind": {
+ "type": "enum",
+ "values": [
+ "pipe_code",
+ "main_pipe",
+ "input_name"
+ ],
+ "description": "What the name is: a pipe code, the main pipe, or an input name, which a stored name takes the form of."
+ },
+ "name": {
+ "type": "caller_text",
+ "description": "The name as the method writes it."
+ }
+ },
+ "meaning": "A pipe code, a main pipe or an input name breaks the naming rules: each is a plain `snake_case` identifier matching `[a-z][a-z0-9_]*`. A stored name, such as a step's `result` or `batch_as` or a PipeBatch's `input_item_name`, takes the form of an input name, so one that breaks it is this code too, and so is a plain `batch_over` starting with the reserved prefix `_bound_`.",
+ "what_to_do": "Rename it to a plain `snake_case` identifier, with no dot and no capital letter, and update every reference to it.",
+ "see": [
+ {
+ "title": "Input names",
+ "href": "spec/mthds-format.md#input-names"
+ },
+ {
+ "title": "Stored names",
+ "href": "spec/mthds-format.md#stored-names"
+ }
+ ]
+ },
+ {
+ "code": "method.pipe_type_invalid",
+ "title": "A pipe's type is missing, unknown or retired",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' has no usable type (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Give pipe '{pipe}' one of the language's pipe types, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to give pipe '{pipe}' a valid type."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe at fault."
+ },
+ "reason": {
+ "type": "enum",
+ "values": [
+ "missing",
+ "unknown",
+ "retired"
+ ],
+ "description": "Whether the type is missing, unknown or retired."
+ },
+ "pipe_type": {
+ "type": "caller_text",
+ "optional": true,
+ "description": "The type as the method writes it, when it writes one."
+ }
+ },
+ "meaning": "A pipe names no type, an unknown one, or one the language has retired.",
+ "what_to_do": "Set the pipe's `type` to one of the operators or controllers the language defines, and give it that type's fields.",
+ "see": [
+ {
+ "title": "Pipes — Operators",
+ "href": "language/pipes-operators.md"
+ },
+ {
+ "title": "Pipes — Controllers",
+ "href": "language/pipes-controllers.md"
+ }
+ ]
+ },
+ {
+ "code": "method.signature_mismatch",
+ "title": "A pipe differs from its signature",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' differs from the signature it implements ({finding}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Make pipe '{pipe}' take the inputs and give the output its signature declares, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to make pipe '{pipe}' match its signature."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The concrete pipe."
+ },
+ "finding": {
+ "type": "caller_text",
+ "description": "How the pipe differs from its signature."
+ }
+ },
+ "meaning": "A concrete pipe's inputs or output differ from those of the signature it implements.",
+ "what_to_do": "Compare the pipe with its signature's `inputs` and `output`, and change one or the other so that they agree.",
+ "see": [
+ {
+ "title": "Contract-only pipe signatures",
+ "href": "spec/mthds-format.md#contract-only-pipe-signatures"
+ }
+ ]
+ },
+ {
+ "code": "method.not_runnable",
+ "title": "The method still holds pipe signatures",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The run reached pipe '{pipe}', a signature with no implementation.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Implement the signature '{pipe}', then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to implement the signature '{pipe}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The signature the run reached."
+ }
+ },
+ "meaning": "A run reached a pipe that is still declared as a signature, with no implementation. Validation reports such pipes as a runnability fact, `pending_signatures`, rather than as a fault.",
+ "what_to_do": "Implement each pipe that `pending_signatures` lists on the `/validate` verdict before running the method.",
+ "see": [
+ {
+ "title": "Validating a bundle",
+ "href": "spec/protocol.md#validating-a-bundle"
+ }
+ ]
+ },
+ {
+ "code": "method.input_undeclared",
+ "title": "A pipe reads an input it does not declare",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' reads names its inputs do not declare: {variables}.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Declare what pipe '{pipe}' reads in its inputs, or stop reading it, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to declare the inputs pipe '{pipe}' reads."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe at fault."
+ },
+ "variables": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The names it reads and does not declare."
+ }
+ },
+ "meaning": "A template or a step reads a variable that the pipe's inputs do not declare.",
+ "what_to_do": "Add each of `params.variables` to the pipe's `inputs` with its concept, or correct the name the template reads.",
+ "see": [
+ {
+ "title": "Inputs read through templates",
+ "href": "spec/mthds-format.md#inputs-read-through-templates"
+ }
+ ]
+ },
+ {
+ "code": "method.input_unused",
+ "title": "A pipe declares an input it never reads",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' declares inputs it never reads: {variables}.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Remove the inputs pipe '{pipe}' never reads, or read them, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to remove the inputs pipe '{pipe}' never reads."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe at fault."
+ },
+ "variables": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The declared inputs nothing reads."
+ }
+ },
+ "meaning": "A pipe declares an input that nothing it runs reads.",
+ "what_to_do": "Remove each of `params.variables` from the pipe's `inputs`, or read it where it was meant to be read. The item's `suggested_fix` may carry the removal.",
+ "see": [
+ {
+ "title": "Suggested fixes",
+ "href": "spec/protocol.md#suggested-fixes"
+ }
+ ]
+ },
+ {
+ "code": "method.input_concept_mismatch",
+ "title": "A pipe's input concept does not fit its use",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' declares the input '{input}' as '{declared}', which its use does not accept. It accepts: {expected}.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Declare the input '{input}' of pipe '{pipe}' with a concept its use accepts, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to declare the input '{input}' of pipe '{pipe}' with a concept its use accepts."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe at fault."
+ },
+ "input": {
+ "type": "identifier",
+ "description": "The input."
+ },
+ "declared": {
+ "type": "identifier",
+ "description": "The concept the input is declared as."
+ },
+ "expected": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The concepts its use accepts."
+ }
+ },
+ "meaning": "An input is declared as a concept that its use does not accept, such as a step that hands it to a pipe expecting another concept.",
+ "what_to_do": "Declare the input as one of `params.expected`, or as a concept that refines one, or change what reads it."
+ },
+ {
+ "code": "method.output_concept_mismatch",
+ "title": "A pipe's output concept does not fit",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}', a {pipe_type}, declares its output as '{declared}', which does not fit. It accepts: {expected}.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Declare the output of pipe '{pipe}' with a concept that fits, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to declare the output of pipe '{pipe}' with a concept that fits."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe at fault."
+ },
+ "declared": {
+ "type": "identifier",
+ "description": "The concept the output is declared as."
+ },
+ "expected": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The concepts that would fit."
+ },
+ "pipe_type": {
+ "type": "identifier",
+ "description": "The pipe's type."
+ }
+ },
+ "meaning": "The output concept breaks the rule of the pipe's type or its wiring, such as a `PipeLLM` declaring an image as its output.",
+ "what_to_do": "Declare the output as one of `params.expected`, or use a pipe type that produces the concept you need.",
+ "see": [
+ {
+ "title": "Pipes — Operators",
+ "href": "language/pipes-operators.md"
+ }
+ ]
+ },
+ {
+ "code": "method.output_multiplicity_mismatch",
+ "title": "A pipe's declared multiplicity does not fit its use",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' declares its output with the multiplicity '{declared}', but its use expects '{expected}'.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Declare the output of pipe '{pipe}' with the multiplicity '{expected}', or change its use, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to fix the output multiplicity of pipe '{pipe}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe at fault."
+ },
+ "declared": {
+ "type": "identifier",
+ "description": "The multiplicity the pipe declares."
+ },
+ "expected": {
+ "type": "enum",
+ "values": [
+ "single",
+ "list",
+ "fixed"
+ ],
+ "description": "The multiplicity its use expects: one item, a list, or a list of a fixed length."
+ }
+ },
+ "meaning": "A pipe's declared output multiplicity does not fit how the method uses it. Validation finds it before any run; its run-time twin is `pipe.output_multiplicity`.",
+ "what_to_do": "Make the output one item, a list, or a list of a fixed length, as its consumer expects, or change the consumer.",
+ "see": [
+ {
+ "title": "Multiplicity",
+ "href": "language/multiplicity.md"
+ }
+ ]
+ },
+ {
+ "code": "method.wiring_invalid",
+ "title": "A pipe's wiring does not give it what it reads",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' reads '{variable_path}' in a shape its wiring does not give it ({finding}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Wire pipe '{pipe}' so that '{variable_path}' reaches it in the shape it reads, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to fix the wiring of pipe '{pipe}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe at fault."
+ },
+ "variable_path": {
+ "type": "identifier",
+ "description": "The variable or the attribute path the pipe reads."
+ },
+ "finding": {
+ "type": "caller_text",
+ "description": "How the wiring differs from what the pipe reads."
+ }
+ },
+ "meaning": "A pipe reads a variable or an attribute in a shape its wiring does not give it, or a controller's steps do not connect.",
+ "what_to_do": "Follow the variable from the step that stores it to the pipe that reads it, and make the stored concept and multiplicity match what the reader declares.",
+ "see": [
+ {
+ "title": "Working Memory",
+ "href": "language/working-memory.md"
+ }
+ ]
+ },
+ {
+ "code": "method.field_path_unresolved",
+ "title": "A path names a field its concept does not have",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "In pipe '{pipe}', the path '{path}' cannot follow '{segment}', which is not a field of the value before it.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Correct the path '{path}' so that it names fields its concepts hold, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to correct the path '{path}' in pipe '{pipe}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe holding the path."
+ },
+ "path": {
+ "type": "identifier",
+ "description": "The path."
+ },
+ "segment": {
+ "type": "identifier",
+ "description": "The segment the walk cannot follow."
+ },
+ "available_fields": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The fields the structure holds where the walk stops, empty when the walk stops at a leaf."
+ }
+ },
+ "meaning": "A binding's `from`, a construct's `from` or a template's field read walks past what the declared structures hold, such as a segment naming no field, or one following a native that holds its value in a single field.",
+ "what_to_do": "Compare the path with the concepts' structures, using `params.available_fields` at the failing segment, and correct it, or bind the field first and walk on from the bound value.",
+ "see": [
+ {
+ "title": "The concept of the result",
+ "href": "spec/mthds-format.md#the-concept-of-the-result"
+ }
+ ]
+ },
+ {
+ "code": "method.binding_step_invalid",
+ "title": "A binding step is malformed",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "A binding step of pipe '{pipe}', at '{field_path}', is malformed.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Correct the binding step at '{field_path}', then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to correct the binding step at '{field_path}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The controller holding the step."
+ },
+ "field_path": {
+ "type": "identifier",
+ "description": "The step's place, as a key path."
+ }
+ },
+ "meaning": "A controller's binding step breaks its shape: a step carrying both `pipe` and `from`, a binding step lacking `result` or carrying `nb_output`, `multiple_output`, `batch_over` or `batch_as`, a `result` that is not a plain input name, a `from` or a dotted `batch_over` that breaks the path grammar, or a binding step or a dotted `batch_over` in a PipeParallel's branches.",
+ "what_to_do": "Give the step exactly one of `pipe` and `from`, give a binding step only `from` and a plain `result`, and bind a field in a sequence step before a PipeParallel rather than in one of its branches.",
+ "see": [
+ {
+ "title": "Binding steps",
+ "href": "spec/mthds-format.md#binding-steps"
+ }
+ ]
+ },
+ {
+ "code": "method.optional_marker_invalid",
+ "title": "An optional marker is misplaced",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' carries a presence marker at '{field_path}', where the language does not allow one.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Remove or move the marker at '{field_path}', then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to fix the presence marker at '{field_path}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe at fault."
+ },
+ "field_path": {
+ "type": "identifier",
+ "description": "Where the marker sits, as a key path."
+ }
+ },
+ "meaning": "A presence marker sits where the language does not allow one, such as a `?` on a plural reference or a `!` on an output.",
+ "what_to_do": "Read where `?` and `!` may appear, and move or remove the marker.",
+ "see": [
+ {
+ "title": "Optionality",
+ "href": "language/optionality.md"
+ }
+ ]
+ },
+ {
+ "code": "method.optional_unhandled",
+ "title": "An optional value reaches a place that needs a required one",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "In pipe '{pipe}', the maybe-absent '{input}' reaches a place that needs a value (site: {site}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Guard '{input}' where it is used, or declare the receiving side optional, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to guard the optional '{input}' in pipe '{pipe}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe at fault."
+ },
+ "input": {
+ "type": "identifier",
+ "description": "The maybe-absent input or output."
+ },
+ "site": {
+ "type": "enum",
+ "values": [
+ "sequence_step",
+ "condition",
+ "condition_output",
+ "template",
+ "parallel_branch"
+ ],
+ "description": "Where the value escapes: `sequence_step` when it escapes through a step or a sequence whose boundary is not optional, `condition` when it escapes through a condition whose boundary is not optional, `condition_output` when a `PipeCondition` can continue without producing its output while that output is not `?`, `template` when a template reads it without a guard, and `parallel_branch` when a maybe-absent PipeParallel branch feeds a required structured field."
+ }
+ },
+ "meaning": "A maybe-absent input or output is used where a value is required: it escapes through a step, a sequence or a condition whose boundary is not optional, a `PipeCondition` can continue without producing its output while that output is not `?`, a template reads it without a guard, or a maybe-absent PipeParallel branch feeds a required structured field.",
+ "what_to_do": "Guard the read, declare the receiving output or field optional with `?`, or force the input with `!` when it is always present at that point.",
+ "see": [
+ {
+ "title": "Optionality",
+ "href": "language/optionality.md#validation-surface"
+ }
+ ]
+ },
+ {
+ "code": "method.template_invalid",
+ "title": "A template in the method is invalid",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The template '{template}' of pipe '{pipe}' is invalid ({finding}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Correct the template '{template}' of pipe '{pipe}', then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to correct the template '{template}' of pipe '{pipe}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe at fault."
+ },
+ "template": {
+ "type": "identifier",
+ "description": "The template's field, such as the pipe's prompt."
+ },
+ "finding": {
+ "type": "caller_text",
+ "description": "What the check found."
+ }
+ },
+ "meaning": "A prompt, an expression or a construct template does not parse, cannot be read, or misuses an input or a filter. The problem's `location` gives the place.",
+ "what_to_do": "Open the template at the place `location` names and correct it, checking each variable it reads against the pipe's inputs.",
+ "see": [
+ {
+ "title": "Inputs read through templates",
+ "href": "spec/mthds-format.md#inputs-read-through-templates"
+ }
+ ]
+ },
+ {
+ "code": "method.template_private_name",
+ "title": "A template reads a name reserved to the runtime",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "A template of pipe '{pipe}' reads names reserved to the runtime: {variables}.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Stop reading the reserved names in the templates of pipe '{pipe}', then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to remove the reserved names from the templates of pipe '{pipe}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe at fault."
+ },
+ "variables": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The reserved names the template reads."
+ }
+ },
+ "meaning": "A template reaches for a name the runtime reserves for its own context, such as a name starting with an underscore.",
+ "what_to_do": "Read only the pipe's declared inputs, and their fields, in its templates."
+ },
+ {
+ "code": "method.function_invalid",
+ "title": "A function the method declares cannot be used",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The function '{function}' of pipe '{pipe}' cannot be used ({finding}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Correct the function '{function}' of pipe '{pipe}', then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to correct the function '{function}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The PipeFunc at fault."
+ },
+ "function": {
+ "type": "identifier",
+ "description": "The function's import path."
+ },
+ "finding": {
+ "type": "caller_text",
+ "description": "What is wrong with the function."
+ }
+ },
+ "meaning": "A `PipeFunc`'s function cannot be imported from the method's tree under the import path it names, lacks or breaks its return type, or shares its name with another.",
+ "what_to_do": "Check that `function_name` is the function's import path from the root of the method's tree, that its module is in the tree, and that the function declares the return type the pipe's output needs.",
+ "see": [
+ {
+ "title": "Operator: PipeFunc",
+ "href": "spec/mthds-format.md#operator-pipefunc"
+ }
+ ]
+ },
+ {
+ "code": "method.concept_invalid",
+ "title": "A concept's structure cannot be built or described",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The structure of the concept '{concept}' cannot be built ({finding}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Correct the structure of the concept '{concept}', then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to correct the concept '{concept}'."
+ }
+ },
+ "params": {
+ "concept": {
+ "type": "identifier",
+ "description": "The concept at fault."
+ },
+ "finding": {
+ "type": "caller_text",
+ "description": "What the check found."
+ }
+ },
+ "meaning": "A concept's structure cannot be generated, found, completed or described as a JSON Schema.",
+ "what_to_do": "Check the concept's fields against the concept structure language, the type and the references of each field in particular.",
+ "see": [
+ {
+ "title": "Concepts",
+ "href": "language/concepts.md"
+ }
+ ]
+ },
+ {
+ "code": "method.model_setting_invalid",
+ "title": "A model setting in the method is invalid",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The model setting '{field}' is invalid ({finding}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Correct the model setting '{field}', then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to correct the model setting '{field}'."
+ }
+ },
+ "params": {
+ "field": {
+ "type": "identifier",
+ "description": "The setting at fault."
+ },
+ "finding": {
+ "type": "caller_text",
+ "description": "What the check found."
+ }
+ },
+ "meaning": "A model reference does not parse, or the settings a step gives conflict with each other.",
+ "what_to_do": "Check the reference and the inline settings against the rules for model references, and remove the settings that conflict.",
+ "see": [
+ {
+ "title": "Model References",
+ "href": "language/model-references.md"
+ }
+ ]
+ },
+ {
+ "code": "method.mock_unsatisfiable",
+ "title": "The dry run cannot mock an output concept",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The dry run cannot mock the concept '{concept}', since no value satisfies its constraints.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Loosen the constraints of the concept '{concept}' so that a value can satisfy them, then validate the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to make the concept '{concept}' satisfiable."
+ }
+ },
+ "params": {
+ "concept": {
+ "type": "identifier",
+ "description": "The concept no mock value satisfies."
+ }
+ },
+ "meaning": "Validation's dry run needs a mock value of an output concept, and no value satisfies the concept's constraints together.",
+ "what_to_do": "Find the constraints of the concept that contradict each other, such as a default outside its choices, and relax one of them."
+ },
+ {
+ "code": "method.changed_concurrently",
+ "title": "A method file changed while it was being fixed",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "A file of the method changed after the fix read it and before the fix wrote it.",
+ "steps": {
+ "actor": {
+ "kind": "refresh",
+ "detail": "Read the method's files again, then apply the fix to their current content."
+ },
+ "other": {
+ "kind": "refresh",
+ "detail": "Read the method's files again, then apply the fix to their current content."
+ }
+ },
+ "params": {},
+ "meaning": "A file a fix read was changed by someone else before the fix wrote it, so the fix stopped rather than overwrite the change.",
+ "what_to_do": "Reload the method's files, and apply the fix to their current content.",
+ "see": [
+ {
+ "title": "Suggested fixes",
+ "href": "spec/protocol.md#suggested-fixes"
+ }
+ ]
+ },
+ {
+ "code": "method.hint_invalid",
+ "title": "A hint is not understood",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "warning",
+ "detail": "The hint '{hint}' is not understood (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Correct or remove the hint '{hint}'."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to correct the hint '{hint}'."
+ }
+ },
+ "params": {
+ "reason": {
+ "type": "enum",
+ "values": [
+ "unknown_key",
+ "unknown_intent",
+ "inapplicable_intent"
+ ],
+ "description": "Whether the hint's key is unknown, its intent word is unknown, or its intent does not apply where it is written."
+ },
+ "hint": {
+ "type": "caller_text",
+ "description": "The hint as the method writes it."
+ }
+ },
+ "meaning": "An advisory finding: a hint's key or intent word is unknown, or its intent does not apply where it is written. It never makes a method invalid.",
+ "what_to_do": "Check the hint against the intent hints the standard defines, and correct or remove it.",
+ "see": [
+ {
+ "title": "Intent Hints",
+ "href": "spec/intent-hints.md"
+ }
+ ]
+ },
+ {
+ "code": "method.input_presence_vacuous",
+ "title": "A presence check always holds",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "warning",
+ "detail": "Pipe '{pipe}' checks whether '{input}' is present, and it always is.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Remove the presence check on '{input}' in pipe '{pipe}'."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to remove the presence check on '{input}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe holding the check."
+ },
+ "input": {
+ "type": "identifier",
+ "description": "The input it checks."
+ }
+ },
+ "meaning": "An advisory finding: a presence check tests an input that is always present, so it always holds.",
+ "what_to_do": "Remove the check, or declare the input optional if it can in fact be absent.",
+ "see": [
+ {
+ "title": "Optionality",
+ "href": "language/optionality.md"
+ }
+ ]
+ },
+ {
+ "code": "method.optional_force_redundant",
+ "title": "An optional force is redundant",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "warning",
+ "detail": "The force marker on '{input}' in pipe '{pipe}' changes nothing.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Remove the force marker on '{input}' in pipe '{pipe}'."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to remove the redundant force marker on '{input}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe holding the marker."
+ },
+ "input": {
+ "type": "identifier",
+ "description": "The input it forces."
+ }
+ },
+ "meaning": "An advisory finding: a `!` marker forces an input that is already present wherever it is read.",
+ "what_to_do": "Remove the `!`.",
+ "see": [
+ {
+ "title": "Optionality",
+ "href": "language/optionality.md"
+ }
+ ]
+ },
+ {
+ "code": "pipe.output_multiplicity",
+ "title": "A pipe's output does not have the declared multiplicity",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' produced an output of the multiplicity '{produced}', but its output '{output}' is declared '{declared}'.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Declare the output '{output}' as '{produced}', or make pipe '{pipe}' produce '{declared}'."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to make the output '{output}' of pipe '{pipe}' match its declared multiplicity."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe at fault."
+ },
+ "output": {
+ "type": "identifier",
+ "description": "The output whose multiplicity differs."
+ },
+ "declared": {
+ "type": "enum",
+ "values": [
+ "single",
+ "list"
+ ],
+ "description": "The multiplicity the method declares."
+ },
+ "produced": {
+ "type": "enum",
+ "values": [
+ "single",
+ "list"
+ ],
+ "description": "The multiplicity the pipe produced."
+ }
+ },
+ "meaning": "At run time a pipe produced a list where its output is declared as a single item, or the reverse. Validation catches what it can before any run as `method.output_multiplicity_mismatch`; this code is what a run finds.",
+ "what_to_do": "Declare the output with the multiplicity the pipe produces, or change the pipe so that it produces the declared one, such as by telling a PipeLLM how many items to give.",
+ "see": [
+ {
+ "title": "Multiplicity",
+ "href": "language/multiplicity.md"
+ },
+ {
+ "title": "Errors",
+ "href": "spec/protocol.md#errors"
+ }
+ ]
+ },
+ {
+ "code": "pipe.output_invalid",
+ "title": "A pipe's output does not fit its concept",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' produced an output that does not fit the concept '{output_concept}', at the fields {fields}.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Make pipe '{pipe}' produce an output that fits '{output_concept}', or loosen the concept, then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to make pipe '{pipe}' produce an output that fits its concept."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe at fault."
+ },
+ "output_concept": {
+ "type": "identifier",
+ "description": "The concept the output is declared as."
+ },
+ "fields": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The fields of the output that fail the concept's structure."
+ }
+ },
+ "meaning": "What a pipe produced fails its declared concept's structure, such as a required field that is missing or a value of the wrong type.",
+ "what_to_do": "Compare the pipe's output with the concept's structure at `params.fields`, then change the pipe, its prompt or its function, or the concept, so that they agree.",
+ "see": [
+ {
+ "title": "Concepts",
+ "href": "language/concepts.md"
+ }
+ ]
+ },
+ {
+ "code": "pipe.function_raised",
+ "title": "The method's function raised",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The function '{function}' of pipe '{pipe}' raised an error.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Fix the function '{function}' so that it does not raise on these inputs, then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to fix the function '{function}' of pipe '{pipe}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The PipeFunc whose function raised."
+ },
+ "function": {
+ "type": "identifier",
+ "description": "The function's import path."
+ }
+ },
+ "meaning": "A PipeFunc's own code raised an error. The problem does not carry the error's message, which the runtime cannot inspect and which can quote the run's inputs or outputs; an implementation keeps it for whoever runs the runtime, in its logs for instance.",
+ "what_to_do": "Run the function locally on the same inputs to reproduce the error and read its message, or read the message where whoever runs the runtime keeps it, then fix the function and run the method again.",
+ "see": [
+ {
+ "title": "Operator: PipeFunc",
+ "href": "spec/mthds-format.md#operator-pipefunc"
+ }
+ ]
+ },
+ {
+ "code": "pipe.function_timed_out",
+ "title": "The method's function ran past its time limit",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The function '{function}' of pipe '{pipe}' ran past its limit of {timeout} seconds.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Make the function '{function}' finish within {timeout} seconds, then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to make the function '{function}' finish in time."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The PipeFunc whose function timed out."
+ },
+ "function": {
+ "type": "identifier",
+ "description": "The function's import path."
+ },
+ "timeout": {
+ "type": "seconds",
+ "description": "The time limit it passed."
+ }
+ },
+ "meaning": "A PipeFunc's function ran longer than the runtime lets one run.",
+ "what_to_do": "Make the function do less work per call, such as by splitting it across a PipeBatch, or move its slow part out of the method.",
+ "see": [
+ {
+ "title": "Operator: PipeFunc",
+ "href": "spec/mthds-format.md#operator-pipefunc"
+ }
+ ]
+ },
+ {
+ "code": "pipe.template_render_failed",
+ "title": "A template failed to render",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "A template of pipe '{pipe}' failed to render at '{variable}'.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Fix the template of pipe '{pipe}' where it reads '{variable}', then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to fix the template of pipe '{pipe}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe whose template failed."
+ },
+ "variable": {
+ "type": "identifier",
+ "description": "The variable the template was reading when it failed."
+ }
+ },
+ "meaning": "A method's template raised while rendering with this run's values, such as a filter applied to a value it cannot take. The problem does not carry what the template engine reported, which can quote the run's inputs or outputs; an implementation keeps it for whoever runs the runtime, in its logs for instance.",
+ "what_to_do": "Check how the template uses the variable `params.variable` names, rendering it locally on the same inputs to read the engine's report, or reading the report where whoever runs the runtime keeps it. Guard the read if the value can be absent, and run the method again.",
+ "see": [
+ {
+ "title": "Inputs read through templates",
+ "href": "spec/mthds-format.md#inputs-read-through-templates"
+ }
+ ]
+ },
+ {
+ "code": "pipe.template_budget_exceeded",
+ "title": "A template exceeded its render budget",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "A template of pipe '{pipe}' passed its render budget in a {operation} operation (limit {limit}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Make the template of pipe '{pipe}' do less in one render, then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to make the template of pipe '{pipe}' do less in one render."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe whose template passed the budget."
+ },
+ "operation": {
+ "type": "enum",
+ "values": [
+ "repeat",
+ "pad",
+ "join",
+ "loop",
+ "recursion",
+ "output"
+ ],
+ "description": "The kind of operation that passed the budget."
+ },
+ "limit": {
+ "type": "integer",
+ "description": "The bound it passed."
+ }
+ },
+ "meaning": "A method's template tried to allocate or compute more than one render may, such as a loop over too many items or an output too long.",
+ "what_to_do": "Simplify the template, or move the work it does into a pipe of its own, such as a PipeBatch over the items it loops on."
+ },
+ {
+ "code": "pipe.condition_unmatched",
+ "title": "A condition matched no outcome",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The condition of pipe '{pipe}' rendered a value that no outcome maps.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Map every value the condition of pipe '{pipe}' can render to an outcome, or give it a default outcome."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to map every value of the condition of pipe '{pipe}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The PipeCondition at fault."
+ }
+ },
+ "meaning": "A PipeCondition's expression rendered a value that none of its outcomes maps, and the pipe gives no default.",
+ "what_to_do": "Add the missing value to the pipe's `outcomes`, or set a `default_outcome`.",
+ "see": [
+ {
+ "title": "Controller: PipeCondition",
+ "href": "spec/mthds-format.md#controller-pipecondition"
+ }
+ ]
+ },
+ {
+ "code": "pipe.condition_refused",
+ "title": "The method refused these inputs",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' chose the outcome '{outcome}', which the method maps to a refusal of these inputs.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Change the inputs so that the method accepts them, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose inputs the method refuses."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The PipeCondition that refused."
+ },
+ "outcome": {
+ "type": "identifier",
+ "description": "The outcome it chose."
+ }
+ },
+ "meaning": "A PipeCondition chose an outcome that the method maps to failure, so the method itself refuses these inputs.",
+ "what_to_do": "Read what the method expects of its inputs, from its description or its author, and send inputs it accepts.",
+ "see": [
+ {
+ "title": "Controller: PipeCondition",
+ "href": "spec/mthds-format.md#controller-pipecondition"
+ }
+ ]
+ },
+ {
+ "code": "pipe.binding_failed",
+ "title": "A binding step could not bind its value",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The binding '{binding}' of pipe '{pipe}' could not follow '{segment}' in this run's value.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Correct the binding '{binding}' of pipe '{pipe}', or the structure it reads, then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to fix the binding '{binding}' of pipe '{pipe}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The controller holding the binding step."
+ },
+ "binding": {
+ "type": "identifier",
+ "description": "The name the step binds."
+ },
+ "segment": {
+ "type": "identifier",
+ "description": "The path segment the binding could not follow."
+ }
+ },
+ "meaning": "At run time a bound value contradicts the structure its concept declares, so the binding step cannot walk its path. The problem names the segment and never what the runtime found there, which is the run's own data.",
+ "what_to_do": "Check the step's `from` path against the value the earlier step produced, and correct the path or the concept.",
+ "see": [
+ {
+ "title": "Binding steps",
+ "href": "spec/mthds-format.md#binding-steps"
+ }
+ ]
+ },
+ {
+ "code": "pipe.input_unresolved",
+ "title": "A pipe could not read a value it needs",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' could not read '{variable}', which an earlier step should have produced.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Make an earlier step produce '{variable}' for pipe '{pipe}', then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to make an earlier step produce '{variable}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe that could not read its input."
+ },
+ "variable": {
+ "type": "identifier",
+ "description": "The input it could not read."
+ }
+ },
+ "meaning": "A nested pipe's input is absent, or of the wrong kind, because an earlier step did not produce it.",
+ "what_to_do": "Follow the variable back to the step that should store it, and check that the step runs and stores it under that name before the pipe reads it.",
+ "see": [
+ {
+ "title": "Working Memory",
+ "href": "language/working-memory.md"
+ }
+ ]
+ },
+ {
+ "code": "pipe.forced_input_absent",
+ "title": "A forced input was absent",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' forces '{variable}' with '!', and it was absent in this run.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Remove the '!' on '{variable}' and handle its absence, then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to handle the absence of '{variable}' in pipe '{pipe}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe forcing the input."
+ },
+ "variable": {
+ "type": "identifier",
+ "description": "The forced input."
+ }
+ },
+ "meaning": "An input the method forces with `!`, asserting that it is always present at that point, resolved absent at run time.",
+ "what_to_do": "Remove the `!` and guard the input where it is read, or make sure an earlier step always produces it.",
+ "see": [
+ {
+ "title": "Optionality",
+ "href": "language/optionality.md"
+ }
+ ]
+ },
+ {
+ "code": "pipe.prompt_empty",
+ "title": "A pipe's prompt is empty",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The {part} of pipe '{pipe}' rendered empty from these inputs.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Give the inputs that the prompt of pipe '{pipe}' is written from, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose inputs leave the prompt of pipe '{pipe}' empty."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe whose prompt is empty."
+ },
+ "part": {
+ "type": "enum",
+ "values": [
+ "user_text",
+ "system_text",
+ "image_prompt"
+ ],
+ "description": "Which part of the prompt rendered empty."
+ }
+ },
+ "meaning": "The prompt rendered from the method's template and the inputs holds no text, usually because the inputs it is written from are empty.",
+ "what_to_do": "Check that the inputs the prompt reads hold text, and send them again."
+ },
+ {
+ "code": "pipe.stack_overflow",
+ "title": "The run nested pipes deeper than the limit",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The run nested pipes deeper than the limit of {limit}.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Find the pipes that call each other without end, and break the loop, then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to stop the method's pipes from nesting without end."
+ }
+ },
+ "params": {
+ "limit": {
+ "type": "integer",
+ "description": "The depth the run passed."
+ }
+ },
+ "meaning": "The pipe stack reached the runtime's limit, usually through pipes that call each other in a loop.",
+ "what_to_do": "Look for a controller that calls itself, directly or through other pipes, and give the recursion an end."
+ },
+ {
+ "code": "model.unknown",
+ "title": "The method names a model that does not exist",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The method names the {model_type} model '{model}', which no catalog knows.",
+ "steps": {
+ "actor": {
+ "kind": "change_model",
+ "detail": "Name a model that exists in place of '{model}', then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to name a model that exists in place of '{model}'."
+ }
+ },
+ "params": {
+ "model": {
+ "type": "identifier",
+ "description": "The model reference the method gives."
+ },
+ "model_type": {
+ "type": "identifier",
+ "description": "The kind of model, such as an LLM or an image generator."
+ },
+ "suggestions": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The models the reference most likely meant, the likeliest first."
+ }
+ },
+ "meaning": "A model reference that no catalog the runtime reads knows.",
+ "what_to_do": "Look in `params.suggestions` for the model the reference most likely meant, or list the runner's models with `GET /models`, and correct the reference.",
+ "see": [
+ {
+ "title": "Model References",
+ "href": "language/model-references.md"
+ }
+ ]
+ },
+ {
+ "code": "model.unavailable",
+ "title": "This deployment serves no backend for the model",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 501,
+ "detail": "The {model_type} model '{model}' exists, but this deployment does not serve it (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Configure a backend for the model '{model}' on this deployment."
+ },
+ "other": {
+ "kind": "change_model",
+ "detail": "Use a model this deployment serves in place of '{model}', or ask whoever runs the runtime to serve it."
+ }
+ },
+ "params": {
+ "model": {
+ "type": "identifier",
+ "description": "The model the method names."
+ },
+ "model_type": {
+ "type": "identifier",
+ "description": "The kind of model."
+ },
+ "reason": {
+ "type": "enum",
+ "values": [
+ "not_served",
+ "not_allowed",
+ "unknown_at_provider",
+ "fallback_disabled",
+ "no_fallback_served"
+ ],
+ "description": "Why it is not served: no backend serves it, the deployment does not allow it, its provider does not know it, or the fallback that would serve it is disabled or served by no backend."
+ }
+ },
+ "meaning": "The model exists, but this deployment serves no backend for it, so the fix lies with whoever runs the runtime rather than with the method.",
+ "what_to_do": "If you run the runtime, configure a backend for the model. Otherwise, use a model the runner lists in `GET /models`.",
+ "see": [
+ {
+ "title": "Model References",
+ "href": "language/model-references.md"
+ }
+ ]
+ },
+ {
+ "code": "model.unspecified",
+ "title": "No model is named for this step",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The step names no {model_type} model, and the deployment names no default for that kind.",
+ "steps": {
+ "actor": {
+ "kind": "change_model",
+ "detail": "Name a {model_type} model on the step, then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to name a model on the step."
+ }
+ },
+ "params": {
+ "model_type": {
+ "type": "identifier",
+ "description": "The kind of model the step needs."
+ }
+ },
+ "meaning": "The step names no model, and the deployment names no default for its kind.",
+ "what_to_do": "Set the step's model, such as a PipeLLM's `model`, to one the runner lists in `GET /models`.",
+ "see": [
+ {
+ "title": "Model References",
+ "href": "language/model-references.md"
+ }
+ ]
+ },
+ {
+ "code": "model.capability_unsupported",
+ "title": "The model cannot do what the step asks",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The model '{model}' does not support {capability}, which the step needs.",
+ "steps": {
+ "actor": {
+ "kind": "change_model",
+ "detail": "Use a model that supports {capability}, or change what the step asks, then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to use a model that supports {capability}."
+ }
+ },
+ "params": {
+ "model": {
+ "type": "identifier",
+ "description": "The model the step names."
+ },
+ "capability": {
+ "type": "identifier",
+ "description": "What the step asks that the model cannot do."
+ }
+ },
+ "meaning": "The model is served, but cannot take this kind of input, produce this kind of output or honour this setting.",
+ "what_to_do": "Pick a model that has the capability, such as one that reads images for a step that sends them, or change the step.",
+ "see": [
+ {
+ "title": "Model References",
+ "href": "language/model-references.md"
+ }
+ ]
+ },
+ {
+ "code": "model.context_exceeded",
+ "title": "The inputs exceed what the model can read",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The prompt for the model '{model}' reaches {count} against a {limit} of {max}.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Send smaller inputs, or fewer images, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose inputs exceed what the model '{model}' can read."
+ }
+ },
+ "params": {
+ "model": {
+ "type": "identifier",
+ "description": "The model."
+ },
+ "limit": {
+ "type": "enum",
+ "values": [
+ "context_window",
+ "prompt_images"
+ ],
+ "description": "Which bound the prompt passes: the context window, or the number of images."
+ },
+ "count": {
+ "type": "integer",
+ "description": "What the prompt reached."
+ },
+ "max": {
+ "type": "integer",
+ "description": "The bound."
+ }
+ },
+ "meaning": "The prompt built from the inputs passes the model's context window or the number of images it takes.",
+ "what_to_do": "Shorten the inputs, split a long document into parts, or send fewer images. The method's author can instead pick a model with a larger window."
+ },
+ {
+ "code": "model.output_truncated",
+ "title": "The answer was cut at the method's token cap",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The model '{model}' stopped at the step's cap of {max_tokens} tokens, after {output_tokens} tokens.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Raise the step's max_tokens above {max_tokens}, or ask for a shorter answer, then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to raise the step's token cap."
+ }
+ },
+ "params": {
+ "model": {
+ "type": "identifier",
+ "description": "The model."
+ },
+ "max_tokens": {
+ "type": "integer",
+ "description": "The cap the step sets."
+ },
+ "output_tokens": {
+ "type": "integer",
+ "description": "The tokens the model produced."
+ }
+ },
+ "meaning": "The model stopped at the step's `max_tokens` before finishing its answer.",
+ "what_to_do": "Raise the step's `max_tokens`, or change its prompt so that it asks for a shorter answer.",
+ "see": [
+ {
+ "title": "Model References",
+ "href": "language/model-references.md"
+ }
+ ]
+ },
+ {
+ "code": "model.output_schema_mismatch",
+ "title": "The model's structured output did not match its schema",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 502,
+ "detail": "The model '{model}' gave an answer that does not fit the concept '{concept}', after the runtime asked again.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Run the method again, since another answer may fit."
+ },
+ "other": {
+ "kind": "retry",
+ "detail": "Run the method again, since another answer may fit."
+ }
+ },
+ "params": {
+ "model": {
+ "type": "identifier",
+ "description": "The model."
+ },
+ "concept": {
+ "type": "identifier",
+ "description": "The concept the answer must fit."
+ }
+ },
+ "meaning": "The model's structured answer failed the output schema, after the runtime's own re-asks. Models answer differently from one call to the next, so a new run may succeed.",
+ "what_to_do": "Run the method again. If it keeps failing, the method's author can simplify the concept's structure or use a model that follows schemas more closely."
+ },
+ {
+ "code": "model.content_refused",
+ "title": "The provider refused the content",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The model '{model}' or its provider refused the request's content on policy grounds.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Change the inputs so that they meet the provider's content policy, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose inputs the provider refused."
+ }
+ },
+ "params": {
+ "model": {
+ "type": "identifier",
+ "description": "The model."
+ }
+ },
+ "meaning": "The model or its provider refused the content of the request on policy grounds.",
+ "what_to_do": "Read the provider's content policy and change the inputs that break it."
+ },
+ {
+ "code": "model.no_result",
+ "title": "The model found nothing for this request",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The model '{model}' returned no result for the query built from the inputs.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Broaden the inputs the query is built from, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose query found nothing."
+ }
+ },
+ "params": {
+ "model": {
+ "type": "identifier",
+ "description": "The search or fetch model."
+ }
+ },
+ "meaning": "A search or fetch model returned no result for the query built from the inputs.",
+ "what_to_do": "Broaden or correct the inputs the query is built from, such as a search term or a URL.",
+ "see": [
+ {
+ "title": "Operator: PipeSearch",
+ "href": "spec/mthds-format.md#operator-pipesearch"
+ }
+ ]
+ },
+ {
+ "code": "provider.rate_limited",
+ "title": "The provider is rate limiting this deployment",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 429,
+ "detail": "The provider '{provider}' is rate limiting this deployment's calls to the model '{model}'.",
+ "steps": {
+ "actor": {
+ "kind": "wait",
+ "detail": "Wait, then run the method again."
+ },
+ "other": {
+ "kind": "wait",
+ "detail": "Wait, then run the method again."
+ }
+ },
+ "params": {
+ "provider": {
+ "type": "identifier",
+ "description": "The provider."
+ },
+ "model": {
+ "type": "identifier",
+ "description": "The model called."
+ }
+ },
+ "meaning": "The inference provider refused a call for its rate, which is not a quota: it passes.",
+ "what_to_do": "Run the method again after `retry_after` seconds when the problem gives it."
+ },
+ {
+ "code": "provider.unavailable",
+ "title": "The provider is unavailable",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 502,
+ "detail": "The provider '{provider}' is unavailable.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Run the method again, since the provider may be back."
+ },
+ "other": {
+ "kind": "retry",
+ "detail": "Run the method again, since the provider may be back."
+ }
+ },
+ "params": {
+ "provider": {
+ "type": "identifier",
+ "description": "The provider."
+ }
+ },
+ "meaning": "The provider answered that it is overloaded or down, or the connection to it never opened.",
+ "what_to_do": "Run the method again after a while, and check the provider's status page if it keeps failing."
+ },
+ {
+ "code": "provider.timeout",
+ "title": "The provider did not answer in time",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 504,
+ "detail": "The provider '{provider}' did not answer in time.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Run the method again."
+ },
+ "other": {
+ "kind": "retry",
+ "detail": "Run the method again."
+ }
+ },
+ "params": {
+ "provider": {
+ "type": "identifier",
+ "description": "The provider."
+ }
+ },
+ "meaning": "The provider timed out, or the runtime stopped waiting for it, on a call that is safe to repeat.",
+ "what_to_do": "Run the method again. If calls keep timing out, the inputs may be too large for the model to answer in time."
+ },
+ {
+ "code": "provider.failed",
+ "title": "The provider failed",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 502,
+ "detail": "The provider '{provider}' failed with the HTTP status {status}.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Run the method again."
+ },
+ "other": {
+ "kind": "retry",
+ "detail": "Run the method again."
+ }
+ },
+ "params": {
+ "provider": {
+ "type": "identifier",
+ "description": "The provider."
+ },
+ "status": {
+ "type": "integer",
+ "description": "The HTTP status the provider answered with."
+ }
+ },
+ "meaning": "The provider answered with a server error that no other `provider.` code describes.",
+ "what_to_do": "Run the method again after a while."
+ },
+ {
+ "code": "provider.response_invalid",
+ "title": "The provider's answer could not be used",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 502,
+ "detail": "The provider '{provider}' gave an answer the runtime cannot use ({defect}).",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Run the method again."
+ },
+ "other": {
+ "kind": "retry",
+ "detail": "Run the method again."
+ }
+ },
+ "params": {
+ "provider": {
+ "type": "identifier",
+ "description": "The provider."
+ },
+ "defect": {
+ "type": "enum",
+ "values": [
+ "empty",
+ "malformed"
+ ],
+ "description": "Whether the answer was empty or unreadable."
+ }
+ },
+ "meaning": "The provider stopped normally but gave an empty or unreadable answer.",
+ "what_to_do": "Run the method again, since the next answer may be sound."
+ },
+ {
+ "code": "provider.credential_refused",
+ "title": "The provider refused this deployment's credential",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 502,
+ "detail": "The provider '{provider}' refused this deployment's credential.",
+ "steps": {
+ "actor": {
+ "kind": "check_credentials",
+ "detail": "Check the credential this deployment holds for the provider '{provider}'."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "provider": {
+ "type": "identifier",
+ "description": "The provider."
+ }
+ },
+ "meaning": "The provider refused the credential the deployment itself holds, which the caller can do nothing about.",
+ "what_to_do": "If you run the runtime, renew or correct its credential for the provider. Otherwise, report the problem to whoever runs it."
+ },
+ {
+ "code": "provider.quota_exhausted",
+ "title": "This deployment's provider account is out of quota",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 502,
+ "detail": "This deployment's account with the provider '{provider}' is out of quota.",
+ "steps": {
+ "actor": {
+ "kind": "check_account",
+ "detail": "Check this deployment's account with the provider '{provider}', and raise its quota or its credit."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "provider": {
+ "type": "identifier",
+ "description": "The provider."
+ }
+ },
+ "meaning": "The provider refused a call because the deployment's own account with it is out of quota or of credit.",
+ "what_to_do": "If you run the runtime, top up or raise its account with the provider. Otherwise, report the problem to whoever runs it."
+ },
+ {
+ "code": "provider.outcome_unknown",
+ "title": "The provider call may have taken effect",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 502,
+ "detail": "A call to the model '{model}' of the provider '{provider}' failed after it was sent, so its work may exist and be billed.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Run the method again if a repeat of the work is acceptable, since a new run may bill that work again."
+ },
+ "other": {
+ "kind": "check_account",
+ "detail": "Check the account's usage before running the method again, since the work may have been billed."
+ }
+ },
+ "params": {
+ "provider": {
+ "type": "identifier",
+ "description": "The provider."
+ },
+ "model": {
+ "type": "identifier",
+ "description": "The model called."
+ }
+ },
+ "meaning": "The connection dropped, timed out or met a server error after a billed call that is not safe to repeat had been sent, so the work may exist and be billed. The runtime never repeats such a call within the run; read as the run's problem, a new run may succeed, and may bill that work again.",
+ "what_to_do": "Decide whether a repeat is acceptable. If it is, run the method again; if not, check the account's usage first."
+ },
+ {
+ "code": "run.not_found",
+ "title": "No such run",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 404,
+ "detail": "No run '{pipeline_run_id}' is visible to this caller.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Check the run id, then read the run again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose run id names no run it can read."
+ }
+ },
+ "params": {
+ "pipeline_run_id": {
+ "type": "identifier",
+ "description": "The run id the request gives."
+ }
+ },
+ "meaning": "The run id names no run this caller can read: it never existed, it belongs to someone else, or its record is no longer kept.",
+ "what_to_do": "Check the run id against the one `/start` or `/execute` answered with, and the credential against the one that started the run.",
+ "see": [
+ {
+ "title": "HTTP Runner Protocol",
+ "href": "spec/protocol.md"
+ }
+ ]
+ },
+ {
+ "code": "run.failed",
+ "title": "The run did not succeed",
+ "domain": "runtime",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The run '{pipeline_run_id}' ended as '{run_status}', without success.",
+ "steps": {
+ "actor": {
+ "kind": "read_run",
+ "detail": "Read the run's own problem in run_error to see why it did not succeed."
+ },
+ "other": {
+ "kind": "read_run",
+ "detail": "Read the run's own problem in run_error to see why it did not succeed."
+ }
+ },
+ "params": {
+ "pipeline_run_id": {
+ "type": "identifier",
+ "description": "The run."
+ },
+ "run_status": {
+ "type": "identifier",
+ "description": "The status the run ended with."
+ }
+ },
+ "meaning": "A read of a run that ended without success. This problem only says that the run failed; the run's own problem, with its own code and next step, rides `run_error`.",
+ "what_to_do": "Read `run_error` and act on its code: that problem says who must act and what to do.",
+ "see": [
+ {
+ "title": "HTTP Runner Protocol",
+ "href": "spec/protocol.md"
+ }
+ ]
+ },
+ {
+ "code": "run.not_finished",
+ "title": "The run has not finished",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The run '{pipeline_run_id}' has not finished yet.",
+ "steps": {
+ "actor": {
+ "kind": "wait",
+ "detail": "Wait, then read the run's results again."
+ },
+ "other": {
+ "kind": "wait",
+ "detail": "Wait, then read the run's results again."
+ }
+ },
+ "params": {
+ "pipeline_run_id": {
+ "type": "identifier",
+ "description": "The run."
+ }
+ },
+ "meaning": "A read of a run's results before the run ended.",
+ "what_to_do": "Read the results again after `retry_after` seconds when the problem gives it, or follow the run's status until it ends.",
+ "see": [
+ {
+ "title": "HTTP Runner Protocol",
+ "href": "spec/protocol.md"
+ }
+ ]
+ },
+ {
+ "code": "run.cancelled",
+ "title": "The run was cancelled by its caller",
+ "domain": "input",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The run was cancelled by its caller before it ended.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Start the run again if its result is still wanted."
+ },
+ "other": {
+ "kind": "read_run",
+ "detail": "Read the run to see when it was cancelled."
+ }
+ },
+ "params": {},
+ "meaning": "The run's own caller cancelled it before it ended. Nothing was wrong with the run, so a new one may succeed.",
+ "what_to_do": "Start a new run if the result is still wanted.",
+ "see": [
+ {
+ "title": "HTTP Runner Protocol",
+ "href": "spec/protocol.md"
+ }
+ ]
+ },
+ {
+ "code": "run.timed_out",
+ "title": "The run passed its time limit",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The run did not end within the deployment's run limit of {timeout} seconds.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Make the method do less work per run, so that it ends within {timeout} seconds."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to make the method end within the deployment's run limit."
+ }
+ },
+ "params": {
+ "timeout": {
+ "type": "seconds",
+ "description": "The deployment's run limit."
+ }
+ },
+ "meaning": "The run did not end within the deployment's run time limit, so the method's work must shrink to fit it.",
+ "what_to_do": "Split the method's work into smaller runs, or have it process fewer items per run.",
+ "see": [
+ {
+ "title": "HTTP Runner Protocol",
+ "href": "spec/protocol.md"
+ }
+ ]
+ },
+ {
+ "code": "run.lost",
+ "title": "The run's outcome is lost",
+ "domain": "runtime",
+ "retry": "outcome_unknown",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "The runtime lost track of the run '{pipeline_run_id}', and its outcome is unknown.",
+ "steps": {
+ "actor": {
+ "kind": "read_run",
+ "detail": "Read the run '{pipeline_run_id}' again later in case it reports how it ended, and start a new run only if repeating its work is acceptable."
+ },
+ "other": {
+ "kind": "read_run",
+ "detail": "Read the run '{pipeline_run_id}' again later in case it reports how it ended, and start a new run only if repeating its work is acceptable."
+ }
+ },
+ "params": {
+ "pipeline_run_id": {
+ "type": "identifier",
+ "description": "The run."
+ }
+ },
+ "meaning": "The run's execution can no longer be found, or never reported back, so the runtime holds no outcome for it. The run may have done its work, billed calls included, or may still be running, so a new run may repeat that work and is never started automatically.",
+ "what_to_do": "Read the run again later, since an execution that has not reported may still end, and check what the run would have produced and the account's usage. Start a new run only once a repeat of the run's work is acceptable. If runs keep being lost, report it to whoever runs the runtime.",
+ "see": [
+ {
+ "title": "HTTP Runner Protocol",
+ "href": "spec/protocol.md"
+ }
+ ]
+ },
+ {
+ "code": "run.outcome_unknown",
+ "title": "The runtime cannot tell whether the run started or finished",
+ "domain": "runtime",
+ "retry": "outcome_unknown",
+ "raised_as": "problem",
+ "status": 502,
+ "detail": "The run '{pipeline_run_id}' was sent on, and its answer was lost.",
+ "steps": {
+ "actor": {
+ "kind": "read_run",
+ "detail": "Read the run '{pipeline_run_id}' to learn its outcome, and never send the request again automatically."
+ },
+ "other": {
+ "kind": "read_run",
+ "detail": "Read the run '{pipeline_run_id}' to learn its outcome, and never send the request again automatically."
+ }
+ },
+ "params": {
+ "pipeline_run_id": {
+ "type": "identifier",
+ "description": "The run."
+ }
+ },
+ "meaning": "The runtime sent the run on to be executed and lost the answer, so the run may have started, may have finished, or may never have begun.",
+ "what_to_do": "Read the run by its id to learn its outcome. A repeat of the request may start a second run, so it is never made automatically.",
+ "see": [
+ {
+ "title": "HTTP Runner Protocol",
+ "href": "spec/protocol.md"
+ }
+ ]
+ },
+ {
+ "code": "run.already_ended",
+ "title": "The run has already ended",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The run '{pipeline_run_id}' has already ended as '{run_status}', so it cannot be changed.",
+ "steps": {
+ "actor": {
+ "kind": "read_run",
+ "detail": "Read the run's final outcome rather than change it."
+ },
+ "other": {
+ "kind": "read_run",
+ "detail": "Read the run's final outcome rather than change it."
+ }
+ },
+ "params": {
+ "pipeline_run_id": {
+ "type": "identifier",
+ "description": "The run."
+ },
+ "run_status": {
+ "type": "identifier",
+ "description": "The status it ended with."
+ }
+ },
+ "meaning": "A change, such as a cancellation, was asked of a run whose outcome is final.",
+ "what_to_do": "Read the run's outcome. To get a different one, start a new run.",
+ "see": [
+ {
+ "title": "HTTP Runner Protocol",
+ "href": "spec/protocol.md"
+ }
+ ]
+ },
+ {
+ "code": "run.answer_not_kept",
+ "title": "The run's answer was not kept",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The run '{pipeline_run_id}' under this idempotency key ended as '{run_status}', and its answer was not kept.",
+ "steps": {
+ "actor": {
+ "kind": "read_run",
+ "detail": "Read the run '{pipeline_run_id}' rather than repeat the request."
+ },
+ "other": {
+ "kind": "read_run",
+ "detail": "Read the run '{pipeline_run_id}' rather than repeat the request."
+ }
+ },
+ "params": {
+ "pipeline_run_id": {
+ "type": "identifier",
+ "description": "The first run."
+ },
+ "run_status": {
+ "type": "identifier",
+ "description": "The status it ended with."
+ }
+ },
+ "meaning": "A repeat, under the same idempotency key, of a synchronous run whose first run ended without an answer the runtime kept.",
+ "what_to_do": "Read the first run by its id. Sending the request again with a new key would start another run.",
+ "see": [
+ {
+ "title": "HTTP Runner Protocol",
+ "href": "spec/protocol.md"
+ }
+ ]
+ },
+ {
+ "code": "run.results_not_stored",
+ "title": "The run's results were not stored",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 404,
+ "detail": "The run '{pipeline_run_id}' completed, and its results were delivered with its answer rather than stored.",
+ "steps": {
+ "actor": {
+ "kind": "read_run",
+ "detail": "Read the results from the answer the run was started with."
+ },
+ "other": {
+ "kind": "read_run",
+ "detail": "Read the results from the answer the run was started with."
+ }
+ },
+ "params": {
+ "pipeline_run_id": {
+ "type": "identifier",
+ "description": "The run."
+ }
+ },
+ "meaning": "The run completed and its results were delivered inline in its answer, never stored, so there is nothing to read back.",
+ "what_to_do": "Keep the results from the answer that delivered them. A run whose results must be read back later is started the way the runtime stores them, such as with `/start`.",
+ "see": [
+ {
+ "title": "HTTP Runner Protocol",
+ "href": "spec/protocol.md"
+ }
+ ]
+ },
+ {
+ "code": "run.terminated",
+ "title": "The run was stopped by an operator or an erasure",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The run was stopped before it ended (ended by: {ended_by}).",
+ "steps": {
+ "actor": {
+ "kind": "read_run",
+ "detail": "Read the run's record to see when and why it was stopped."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime if the run was still wanted."
+ }
+ },
+ "params": {
+ "ended_by": {
+ "type": "enum",
+ "values": [
+ "operator",
+ "erasure"
+ ],
+ "description": "Whether whoever runs the runtime stopped the run, or an erasure purged it."
+ }
+ },
+ "meaning": "Whoever runs the runtime stopped the run, or an erasure purged it, before it ended. Such a run is never repeated automatically.",
+ "what_to_do": "Ask whoever runs the runtime why the run was stopped before starting it again.",
+ "see": [
+ {
+ "title": "HTTP Runner Protocol",
+ "href": "spec/protocol.md"
+ }
+ ]
+ },
+ {
+ "code": "security.input_url_refused",
+ "title": "A URL in the request was refused",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The URL of the input '{input}' points at a {target_class} target, which a security rule forbids (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Give the input '{input}' a URL on the public internet, or send the file itself, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose input '{input}' names a URL a security rule forbids."
+ }
+ },
+ "params": {
+ "input": {
+ "type": "identifier",
+ "description": "The input whose URL was refused."
+ },
+ "target_class": {
+ "type": "enum",
+ "values": [
+ "loopback",
+ "private",
+ "link_local",
+ "metadata",
+ "scheme"
+ ],
+ "description": "Where the URL points: a loopback, private or link-local address, a cloud metadata service, or a scheme the runtime does not fetch."
+ },
+ "reason": {
+ "type": "identifier",
+ "description": "The rule that refused it."
+ }
+ },
+ "meaning": "A URL the caller supplied points somewhere a security rule forbids the runtime to fetch, such as a private address.",
+ "what_to_do": "Send a URL that resolves to the public internet over https, or send the file's content itself."
+ },
+ {
+ "code": "security.method_url_refused",
+ "title": "A URL the method names was refused",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' names a URL that points at a {target_class} target, which a security rule forbids (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Make pipe '{pipe}' name a URL on the public internet, then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to change the URL pipe '{pipe}' names."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe naming the URL."
+ },
+ "target_class": {
+ "type": "enum",
+ "values": [
+ "loopback",
+ "private",
+ "link_local",
+ "metadata",
+ "scheme"
+ ],
+ "description": "Where the URL points."
+ },
+ "reason": {
+ "type": "identifier",
+ "description": "The rule that refused it."
+ }
+ },
+ "meaning": "A URL or a storage key that the method, or a template of it, names points somewhere a security rule forbids.",
+ "what_to_do": "Change the method so that every URL it fetches resolves to the public internet over https."
+ },
+ {
+ "code": "security.provider_url_refused",
+ "title": "A URL a provider returned was refused",
+ "domain": "runtime",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 502,
+ "detail": "The provider '{provider}' returned a URL that points at a private address, and the runtime did not fetch it.",
+ "steps": {
+ "actor": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "provider": {
+ "type": "identifier",
+ "description": "The provider whose answer held the URL."
+ }
+ },
+ "meaning": "A URL in a provider's answer points at a private address, so the runtime refused to fetch it.",
+ "what_to_do": "Report the problem to whoever runs the runtime, who can take it up with the provider."
+ },
+ {
+ "code": "security.input_path_refused",
+ "title": "A path the caller supplied was refused",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "A path in the request could escape its root (rule: {rule}).",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Write every path of the request relative to its root, with forward slashes, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose request holds a path that could escape its root."
+ }
+ },
+ "params": {
+ "rule": {
+ "type": "enum",
+ "values": [
+ "absolute",
+ "parent_segment",
+ "outside_root",
+ "backslash",
+ "colon",
+ "empty"
+ ],
+ "description": "The rule the path breaks: it is absolute, climbs with a parent segment, lands outside the root, holds a backslash or a colon, or is empty."
+ }
+ },
+ "meaning": "A path the caller supplied, such as a key of a request's `files`, could escape the root it belongs to.",
+ "what_to_do": "Write each path relative to its root, with forward slashes, no `..` segment, no colon and no leading slash.",
+ "see": [
+ {
+ "title": "Tree paths",
+ "href": "spec/method-tree.md#tree-paths"
+ }
+ ]
+ },
+ {
+ "code": "security.method_path_refused",
+ "title": "A path the method names was refused",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "Pipe '{pipe}' names the path '{file}', which would open a file outside the method on the runtime's disk.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Make pipe '{pipe}' name a file inside the method's tree, then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to change the path pipe '{pipe}' names."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe naming the path."
+ },
+ "file": {
+ "type": "identifier",
+ "description": "The path."
+ }
+ },
+ "meaning": "A runtime that opens files by path would open one outside the method on its own disk. A reference that only names no file of the tree is `method.resource_missing` instead.",
+ "what_to_do": "Point the reference at a file inside the method's tree, written relative to the referring file.",
+ "see": [
+ {
+ "title": "File references",
+ "href": "spec/method-tree.md#file-references"
+ }
+ ]
+ },
+ {
+ "code": "security.template_refused",
+ "title": "A template was refused by the template sandbox",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "A template of pipe '{pipe}' reached for '{name}', which the template sandbox forbids.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Remove '{name}' from the templates of pipe '{pipe}', then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to remove '{name}' from the templates of pipe '{pipe}'."
+ }
+ },
+ "params": {
+ "pipe": {
+ "type": "identifier",
+ "description": "The pipe whose template was refused."
+ },
+ "name": {
+ "type": "identifier",
+ "description": "The name or the call the template reached for."
+ }
+ },
+ "meaning": "A method's template reached for a private name or a call that the template sandbox forbids.",
+ "what_to_do": "Use only the pipe's inputs and the filters the template language offers in its templates."
+ },
+ {
+ "code": "security.schema_refused",
+ "title": "An output schema was refused",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The schema of the concept '{concept}' carries extensions or imports the runtime refuses to execute.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Remove the code-generation extensions and imports from the concept '{concept}', then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to remove the extensions from the concept '{concept}'."
+ }
+ },
+ "params": {
+ "concept": {
+ "type": "identifier",
+ "description": "The concept whose schema was refused."
+ }
+ },
+ "meaning": "An output concept's schema carries code-generation extensions or imports that the runtime refuses to execute.",
+ "what_to_do": "Describe the concept with the concept structure language alone, without extensions that run code.",
+ "see": [
+ {
+ "title": "Concepts",
+ "href": "language/concepts.md"
+ }
+ ]
+ },
+ {
+ "code": "security.integrity_mismatch",
+ "title": "A dependency's content differs from its lock",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The content of the dependency '{dependency}' differs from the hash its lock pins.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Check where the dependency '{dependency}' changed, then update its lock only if the change is trusted."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to check the dependency '{dependency}'."
+ }
+ },
+ "params": {
+ "dependency": {
+ "type": "identifier",
+ "description": "The dependency whose content differs."
+ }
+ },
+ "meaning": "A fetched dependency's content hashes to something other than the lock pins, so it changed since it was locked.",
+ "what_to_do": "Find out why the dependency's content changed, such as a moved tag. Update the lock only once the new content is trusted.",
+ "see": [
+ {
+ "title": "methods.lock Format",
+ "href": "spec/lock-format.md#verification"
+ }
+ ]
+ },
+ {
+ "code": "runtime.unexpected",
+ "title": "An unexpected error occurred",
+ "domain": "runtime",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "The runtime met an unexpected error.",
+ "steps": {
+ "actor": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {},
+ "meaning": "The catch-all: a fault of the runtime that no other code describes. It says nothing about the request, so repeating it is not advised.",
+ "what_to_do": "Report the problem to whoever runs the runtime, with its `pipeline_run_id` when it has one."
+ },
+ {
+ "code": "runtime.misconfigured",
+ "title": "The runtime is misconfigured",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "The runtime is misconfigured, so it cannot serve this request.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Set or correct the configuration of '{component}', then restart the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "component": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The part of the configuration that is unset or contradicts another."
+ }
+ },
+ "meaning": "A setting the runtime needs is unset, or contradicts another. Nobody can wait it out: whoever runs the runtime must fix it.",
+ "what_to_do": "If you run the runtime, read its logs for the component, and correct its configuration. Otherwise, report the problem to whoever runs it."
+ },
+ {
+ "code": "runtime.unavailable",
+ "title": "The runtime or a service it depends on is unavailable",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 503,
+ "detail": "The runtime, or a service it depends on, is unavailable.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Send the request again after a while."
+ },
+ "other": {
+ "kind": "wait",
+ "detail": "Wait, then send the request again."
+ }
+ },
+ "params": {
+ "dependency": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The service that is down."
+ }
+ },
+ "meaning": "The runtime is overloaded or shutting down, or a service it depends on is down.",
+ "what_to_do": "Send the request again after `retry_after` seconds when the problem gives it."
+ },
+ {
+ "code": "runtime.unsupported",
+ "title": "This runtime cannot do what was asked",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 501,
+ "detail": "This runtime lacks {capability}, which the request needs.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Enable {capability} on this runtime."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Send a request that does not need {capability}, or use a runtime that offers it."
+ }
+ },
+ "params": {
+ "capability": {
+ "type": "identifier",
+ "description": "The capability the request needs."
+ }
+ },
+ "meaning": "The deployment lacks a capability the request needs, such as the asynchronous execution `/start` relies on.",
+ "what_to_do": "Use a route or a form of the request that this runtime offers, such as `/execute` in place of `/start`, or a runtime that offers the capability."
+ },
+ {
+ "code": "client.unreachable",
+ "title": "The runtime could not be reached",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "client",
+ "detail": "The client could not connect to the runtime at {base_url}.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Check that the runtime at {base_url} is up and reachable, then try again."
+ },
+ "other": {
+ "kind": "retry",
+ "detail": "Try again once the runtime at {base_url} is reachable."
+ }
+ },
+ "params": {
+ "base_url": {
+ "type": "identifier",
+ "description": "The base URL the client is configured with."
+ }
+ },
+ "meaning": "The client could not open a connection to the runtime.",
+ "what_to_do": "Check the configured base URL, the network and whether the runtime is up, then try again."
+ },
+ {
+ "code": "client.timeout",
+ "title": "The runtime did not answer in time",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "client",
+ "detail": "The runtime did not answer within {seconds} seconds.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Try the call again, or raise the client's time limit."
+ },
+ "other": {
+ "kind": "retry",
+ "detail": "Try the call again."
+ }
+ },
+ "params": {
+ "seconds": {
+ "type": "seconds",
+ "description": "The client's time limit."
+ }
+ },
+ "meaning": "A call that creates nothing, such as a read, timed out. A call that may have created a run is `client.outcome_unknown` instead.",
+ "what_to_do": "Try the call again, or raise the client's time limit."
+ },
+ {
+ "code": "client.response_unreadable",
+ "title": "The runtime's answer could not be read",
+ "domain": "runtime",
+ "retry": "no",
+ "raised_as": "client",
+ "detail": "The runtime answered with the HTTP status {status} and a body that is not a problem document the client can read.",
+ "steps": {
+ "actor": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime, with the status and the body."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "status": {
+ "type": "integer",
+ "description": "The HTTP status of the answer."
+ }
+ },
+ "meaning": "The answer is not a problem document, and no reading rule the client has reads it, such as an error page from a proxy in front of the runtime.",
+ "what_to_do": "Check what sits between the client and the runtime, such as a proxy, and report the answer to whoever runs the runtime."
+ },
+ {
+ "code": "client.outcome_unknown",
+ "title": "The call may have created a run",
+ "domain": "runtime",
+ "retry": "outcome_unknown",
+ "raised_as": "client",
+ "detail": "The connection was lost after a request that creates a run had left, so the run may exist.",
+ "steps": {
+ "actor": {
+ "kind": "read_run",
+ "detail": "Read the run if its id is known, and otherwise leave the outcome unknown rather than send the request again automatically."
+ },
+ "other": {
+ "kind": "read_run",
+ "detail": "Read the run if its id is known, and otherwise leave the outcome unknown rather than send the request again automatically."
+ }
+ },
+ "params": {
+ "pipeline_run_id": {
+ "type": "identifier",
+ "optional": true,
+ "description": "The run, when the client learned its id before the connection was lost."
+ }
+ },
+ "meaning": "The connection dropped, the call timed out, or the caller stopped it, after a request that creates a run had left, so the run may exist.",
+ "what_to_do": "Read the run by its id when the client knows it. A client that knows no run to read leaves the outcome unknown and never repeats the request automatically, since a repeat may start a second run."
+ },
+ {
+ "code": "client.follow_failed",
+ "title": "Following a started run stopped",
+ "domain": "runtime",
+ "retry": "outcome_unknown",
+ "raised_as": "client",
+ "detail": "The client stopped following the run '{pipeline_run_id}', which may still be going.",
+ "steps": {
+ "actor": {
+ "kind": "read_run",
+ "detail": "Read the run '{pipeline_run_id}' by its id rather than start it again."
+ },
+ "other": {
+ "kind": "read_run",
+ "detail": "Read the run '{pipeline_run_id}' by its id rather than start it again."
+ }
+ },
+ "params": {
+ "pipeline_run_id": {
+ "type": "identifier",
+ "description": "The run."
+ }
+ },
+ "meaning": "The runtime acknowledged the run, and following it then failed, so the run has started and may still be going or may have ended. The call that started it has taken effect, so it is never repeated automatically.",
+ "what_to_do": "Read the run by its id until it ends. Starting it again would run it twice."
+ },
+ {
+ "code": "client.not_configured",
+ "title": "The client has no usable configuration",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "client",
+ "detail": "The client's setting '{setting}' is missing or unusable.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Set '{setting}' in the client's configuration."
+ },
+ "other": {
+ "kind": "fix_configuration",
+ "detail": "Set '{setting}' in the client's configuration."
+ }
+ },
+ "params": {
+ "setting": {
+ "type": "identifier",
+ "description": "The setting that is missing or unusable, such as the base URL or the key."
+ }
+ },
+ "meaning": "No base URL or credential is set, or the one set is unusable.",
+ "what_to_do": "Set the setting `params.setting` names, through the client's configuration or its environment."
+ },
+ {
+ "code": "client.argument_invalid",
+ "title": "An argument was refused before sending",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "client",
+ "detail": "The argument '{argument}' was refused before any request left (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Correct the argument '{argument}', then try again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Correct the argument '{argument}', then try again."
+ }
+ },
+ "params": {
+ "argument": {
+ "type": "identifier",
+ "description": "The argument refused."
+ },
+ "reason": {
+ "type": "identifier",
+ "description": "Why it was refused."
+ }
+ },
+ "meaning": "The client refused the arguments of a call, a command or a tool before any request left.",
+ "what_to_do": "Read the call's documentation for the argument and correct it."
+ },
+ {
+ "code": "client.file_unreadable",
+ "title": "A local file cannot be read",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "client",
+ "detail": "The local file '{path}' cannot be read (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Check that '{path}' exists and is readable, then try again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Check that '{path}' exists and is readable, then try again."
+ }
+ },
+ "params": {
+ "path": {
+ "type": "caller_text",
+ "description": "The file's path."
+ },
+ "reason": {
+ "type": "identifier",
+ "description": "Why it cannot be read."
+ }
+ },
+ "meaning": "A local file the client was told to read cannot be read or decoded.",
+ "what_to_do": "Check the path, the file's permissions and its encoding, then try again."
+ },
+ {
+ "code": "client.write_failed",
+ "title": "A local file could not be written",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "client",
+ "detail": "The client could not write '{path}' (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Make '{path}' writable, or choose another place to write, then try again."
+ },
+ "other": {
+ "kind": "fix_configuration",
+ "detail": "Make '{path}' writable, or choose another place to write, then try again."
+ }
+ },
+ "params": {
+ "path": {
+ "type": "caller_text",
+ "description": "The file or the directory."
+ },
+ "reason": {
+ "type": "identifier",
+ "description": "Why it could not be written."
+ }
+ },
+ "meaning": "The client could not write a file or a directory it was asked to produce.",
+ "what_to_do": "Check the directory's permissions and the free space, or write somewhere else."
+ },
+ {
+ "code": "client.target_exists",
+ "title": "The target already exists",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "client",
+ "detail": "'{path}' already holds something the client will not overwrite.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Choose another target, or remove what '{path}' holds, then try again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Choose another target, or remove what '{path}' holds, then try again."
+ }
+ },
+ "params": {
+ "path": {
+ "type": "caller_text",
+ "description": "The target path."
+ }
+ },
+ "meaning": "The target path holds something the client will not overwrite.",
+ "what_to_do": "Choose another target, or remove what it holds if it is no longer needed."
+ },
+ {
+ "code": "client.workspace_busy",
+ "title": "Local files changed underneath the client",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "client",
+ "detail": "Another process holds or changed '{path}', which this call read.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Try again once the other process is done with '{path}'."
+ },
+ "other": {
+ "kind": "retry",
+ "detail": "Try again once the other process is done with '{path}'."
+ }
+ },
+ "params": {
+ "path": {
+ "type": "caller_text",
+ "description": "The file or the directory."
+ }
+ },
+ "meaning": "Another process holds the lock on, or wrote, the files the call read.",
+ "what_to_do": "Wait for the other process to finish, then try again."
+ },
+ {
+ "code": "client.output_mismatch",
+ "title": "An output does not match the generated types",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "client",
+ "detail": "The output field '{field}' does not match the generated type of the concept '{concept}'.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Generate the types again from the method as it is now."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Generate the types again from the method as it is now."
+ }
+ },
+ "params": {
+ "field": {
+ "type": "identifier",
+ "description": "The output field."
+ },
+ "concept": {
+ "type": "identifier",
+ "description": "The concept whose generated type refuses it."
+ }
+ },
+ "meaning": "The caller's generated types refuse an output that the method declares, usually because the method changed after they were generated.",
+ "what_to_do": "Generate the types again from the current method."
+ },
+ {
+ "code": "client.link_refused",
+ "title": "A download link was refused",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "client",
+ "detail": "The client refused a download link the runtime's storage handed out (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Make the runtime's storage hand out https links that need no redirect."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "reason": {
+ "type": "enum",
+ "values": [
+ "plain_http",
+ "unsupported_scheme",
+ "redirect"
+ ],
+ "description": "Why the link was refused: it is plain http, it uses another scheme, or it redirects."
+ }
+ },
+ "meaning": "The client's fetch policy refused a link that the runtime's storage handed out.",
+ "what_to_do": "If you run the runtime, configure its storage to hand out https links. Otherwise, report the problem to whoever runs it."
+ },
+ {
+ "code": "client.download_limit_exceeded",
+ "title": "A download passed the client's limit",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "client",
+ "detail": "A download passed the client's limit of {limit} bytes.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Raise the client's download limit, or download fewer files at once."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Raise the client's download limit, or download fewer files at once."
+ }
+ },
+ "params": {
+ "limit": {
+ "type": "bytes",
+ "description": "The client's limit."
+ }
+ },
+ "meaning": "A file, or the call's total, passed the client's own download cap.",
+ "what_to_do": "Raise the limit in the client's configuration, or download the files one at a time."
+ },
+ {
+ "code": "client.aborted",
+ "title": "The call was stopped by the caller",
+ "domain": "input",
+ "retry": "yes",
+ "raised_as": "client",
+ "detail": "The caller stopped the call before it finished, and the call created nothing.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Make the call again if its result is still wanted."
+ },
+ "other": {
+ "kind": "retry",
+ "detail": "Make the call again if its result is still wanted."
+ }
+ },
+ "params": {},
+ "meaning": "The caller's abort signal stopped a call before it finished, where the call creates nothing, such as a read, or its request had not left yet. A call that creates a run and was stopped after its request left may have created the run, so it is `client.outcome_unknown` instead.",
+ "what_to_do": "Make the call again if its result is still wanted."
+ },
+ {
+ "code": "client.tool_missing",
+ "title": "A local tool the client needs is missing",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "client",
+ "detail": "The program '{tool}', which the client needs, is missing or cannot be started.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Install '{tool}' and put it on the PATH, then try again."
+ },
+ "other": {
+ "kind": "fix_configuration",
+ "detail": "Install '{tool}' and put it on the PATH, then try again."
+ }
+ },
+ "params": {
+ "tool": {
+ "type": "identifier",
+ "description": "The program."
+ }
+ },
+ "meaning": "A program the client needs, such as a runtime's command-line tool, git or uv, is missing, cannot be started, or failed to install.",
+ "what_to_do": "Install the program, check that it is on the PATH, and try again."
+ },
+ {
+ "code": "client.tool_outdated",
+ "title": "A local tool is too old",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "client",
+ "detail": "The program '{tool}' is at version {version}, older than the client requires.",
+ "steps": {
+ "actor": {
+ "kind": "upgrade",
+ "detail": "Upgrade '{tool}', then try again."
+ },
+ "other": {
+ "kind": "upgrade",
+ "detail": "Upgrade '{tool}', then try again."
+ }
+ },
+ "params": {
+ "tool": {
+ "type": "identifier",
+ "description": "The program or the engine."
+ },
+ "version": {
+ "type": "identifier",
+ "description": "The version found."
+ }
+ },
+ "meaning": "A program or an engine the client needs is older than it requires.",
+ "what_to_do": "Upgrade the program to the version the client documents, and try again."
+ }
+ ]
+}
diff --git a/pipelex/cli/dev_cli/commands/error_registry/standard/mthds-error-registry.schema.json b/pipelex/cli/dev_cli/commands/error_registry/standard/mthds-error-registry.schema.json
new file mode 100644
index 000000000..e762f1482
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/error_registry/standard/mthds-error-registry.schema.json
@@ -0,0 +1,298 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "MTHDS error registry",
+ "description": "The format of an MTHDS error registry: the core registry, which the MTHDS standard publishes, and the registry an owner of an extension prefix publishes for its own codes. Every entry declares every member a code needs, so no code is undomained, no verdict unknown and no step absent. The closed lists of domains, retry verdicts and step kinds are those of the Problem schema in mthds-protocol.openapi.yaml. See spec/error-registry.md on mthds.ai.",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["version", "base_url", "families", "codes"],
+ "properties": {
+ "version": {
+ "description": "The version of the release this registry is published with. For the core registry it is the MTHDS standard version; for an extension registry, the version of its owner's release.",
+ "type": "string",
+ "pattern": "^\\d+\\.\\d+\\.\\d+(?:[-+][0-9A-Za-z.\\-]+)?$"
+ },
+ "prefix": {
+ "description": "The registered extension prefix every code of this registry starts with. The core registry has none, since core codes are bare.",
+ "$ref": "#/$defs/segment"
+ },
+ "base_url": {
+ "description": "The base URL the pages of this registry's codes are published under. A code's type URI is this base URL, a slash, then the whole code.",
+ "$ref": "#/$defs/baseUrl"
+ },
+ "extension_prefixes": {
+ "description": "The core registry's list of registered extension prefixes, each with its owner and the base URL its codes' pages are published under. An extension registry has no such list.",
+ "type": "array",
+ "items": { "$ref": "#/$defs/extensionPrefix" }
+ },
+ "families": {
+ "description": "The families this registry's codes belong to, in the order its pages present them. A code's family is the code without its last segment.",
+ "type": "array",
+ "minItems": 1,
+ "items": { "$ref": "#/$defs/family" }
+ },
+ "codes": {
+ "description": "One entry per code.",
+ "type": "array",
+ "minItems": 1,
+ "items": { "$ref": "#/$defs/entry" }
+ }
+ },
+ "if": { "required": ["prefix"] },
+ "then": {
+ "properties": {
+ "extension_prefixes": false,
+ "families": { "items": { "properties": { "family": { "$ref": "#/$defs/extensionFamily" } } } },
+ "codes": { "items": { "properties": { "code": { "$ref": "#/$defs/extensionCode" } } } }
+ }
+ },
+ "else": {
+ "required": ["extension_prefixes"],
+ "properties": {
+ "families": { "items": { "properties": { "family": { "$ref": "#/$defs/segment" } } } },
+ "codes": { "items": { "properties": { "code": { "$ref": "#/$defs/coreCode" } } } }
+ }
+ },
+ "$defs": {
+ "segment": {
+ "description": "One segment of a code: a lowercase letter, then lowercase letters, digits and underscores.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_]*$"
+ },
+ "coreCode": {
+ "description": "A core code: exactly a family and a name.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$"
+ },
+ "extensionFamily": {
+ "description": "An extension family: the prefix and a family.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$"
+ },
+ "extensionCode": {
+ "description": "An extension code: the prefix, a family and a name.",
+ "type": "string",
+ "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$"
+ },
+ "baseUrl": {
+ "description": "An https URL: a lowercase host name, an optional port and a path of non-empty segments, with no trailing slash, query or fragment.",
+ "type": "string",
+ "format": "uri",
+ "pattern": "^https://[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?::[0-9]{1,5})?(?:/[A-Za-z0-9._~%!$&'()*+,;=:@-]+)*$"
+ },
+ "text": {
+ "description": "Prose for a person: a word, a phrase or sentences, never empty.",
+ "type": "string",
+ "minLength": 1,
+ "pattern": "\\S"
+ },
+ "template": {
+ "description": "A sentence or two with {name} placeholders, each naming a parameter the code declares. A literal brace is written twice.",
+ "type": "string",
+ "minLength": 1,
+ "pattern": "\\S"
+ },
+ "domain": {
+ "description": "Who must act. The closed list of ProblemDomain in mthds-protocol.openapi.yaml.",
+ "enum": ["input", "method", "account", "operator", "runtime"]
+ },
+ "retry": {
+ "description": "Whether repeating the operation that produced the problem can succeed. The closed list of RetryVerdict in mthds-protocol.openapi.yaml.",
+ "enum": ["no", "yes", "outcome_unknown"]
+ },
+ "stepKind": {
+ "description": "What the reader does next. The closed list of StepKind in mthds-protocol.openapi.yaml.",
+ "enum": [
+ "retry",
+ "wait",
+ "read_run",
+ "refresh",
+ "change_input",
+ "change_method",
+ "change_model",
+ "check_credentials",
+ "request_access",
+ "check_account",
+ "fix_configuration",
+ "upgrade",
+ "contact_owner",
+ "report"
+ ]
+ },
+ "step": {
+ "description": "One next step: its closed kind and the template of its detail sentence.",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["kind", "detail"],
+ "properties": {
+ "kind": { "$ref": "#/$defs/stepKind" },
+ "detail": { "$ref": "#/$defs/template" }
+ }
+ },
+ "scalarType": {
+ "description": "The type of a parameter that holds one value. identifier: a name, a code or an id. integer: a whole number. seconds: a number of seconds, never negative. bytes: a size in bytes, never negative. sha256: a SHA-256 hash in lowercase hexadecimal. enum: one of the listed values. caller_text: the caller's own text, capped, such as a parser's finding about the caller's method.",
+ "enum": ["identifier", "integer", "seconds", "bytes", "sha256", "enum", "caller_text"]
+ },
+ "enumValues": {
+ "description": "The values an enum parameter may hold.",
+ "type": "array",
+ "minItems": 1,
+ "uniqueItems": true,
+ "items": { "$ref": "#/$defs/segment" }
+ },
+ "itemType": {
+ "description": "The type of each item of a list parameter.",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["type"],
+ "properties": {
+ "type": { "$ref": "#/$defs/scalarType" },
+ "values": { "$ref": "#/$defs/enumValues" }
+ },
+ "if": { "properties": { "type": { "const": "enum" } } },
+ "then": { "required": ["values"] },
+ "else": { "properties": { "values": false } }
+ },
+ "param": {
+ "description": "One parameter of a code: a typed fact its sentences are written from.",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["type", "description"],
+ "properties": {
+ "type": {
+ "description": "A scalar type, or list for a list of items of the type items names.",
+ "anyOf": [{ "$ref": "#/$defs/scalarType" }, { "const": "list" }]
+ },
+ "values": { "$ref": "#/$defs/enumValues" },
+ "items": { "$ref": "#/$defs/itemType" },
+ "description": { "$ref": "#/$defs/text" },
+ "optional": {
+ "description": "True when an occurrence of the code may lack this fact. A parameter not declared optional is present on every occurrence that the reader's view includes it in.",
+ "type": "boolean"
+ },
+ "operator_only": {
+ "description": "True for a fact of the runtime's own configuration that only whoever runs the runtime may read. An implementation leaves it out of every problem it answers to a caller.",
+ "type": "boolean"
+ }
+ },
+ "allOf": [
+ {
+ "if": { "properties": { "type": { "const": "enum" } } },
+ "then": { "required": ["values"] },
+ "else": { "properties": { "values": false } }
+ },
+ {
+ "if": { "properties": { "type": { "const": "list" } } },
+ "then": { "required": ["items"] },
+ "else": { "properties": { "items": false } }
+ }
+ ]
+ },
+ "reference": {
+ "description": "A page of the specification that defines the situation a code names: a path from the documentation root to a Markdown page, with an optional anchor, and the text to link it with.",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["title", "href"],
+ "properties": {
+ "title": { "$ref": "#/$defs/text" },
+ "href": {
+ "type": "string",
+ "pattern": "^[a-z0-9_\\-]+(/[a-z0-9_\\-.]+)*\\.md(#[a-z0-9_\\-]+)?$"
+ }
+ }
+ },
+ "family": {
+ "description": "A family of codes and what its codes are about.",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["family", "description"],
+ "properties": {
+ "family": { "type": "string" },
+ "description": { "$ref": "#/$defs/text" }
+ }
+ },
+ "extensionPrefix": {
+ "description": "A registered extension prefix. A registered prefix is never reassigned to another owner.",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["prefix", "owner", "base_url"],
+ "properties": {
+ "prefix": { "$ref": "#/$defs/segment" },
+ "owner": { "$ref": "#/$defs/text" },
+ "base_url": { "$ref": "#/$defs/baseUrl" }
+ }
+ },
+ "entry": {
+ "description": "One code and everything a reader needs from it. The code decides: its title, domain, retry verdict, steps, parameters and HTTP status are properties of the code, never set independently by an emitter.",
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "code",
+ "title",
+ "domain",
+ "retry",
+ "raised_as",
+ "detail",
+ "steps",
+ "params",
+ "meaning",
+ "what_to_do"
+ ],
+ "properties": {
+ "code": { "type": "string" },
+ "title": {
+ "description": "The code's short title, the same for every occurrence of the code.",
+ "$ref": "#/$defs/text"
+ },
+ "domain": { "$ref": "#/$defs/domain" },
+ "retry": { "$ref": "#/$defs/retry" },
+ "raised_as": {
+ "description": "How the code reaches a reader. problem: as a problem document, the body of an HTTP response or kept in a run's record, so it has a status. warning: only as an item of a validate verdict's warnings, so it has none. client: detected by a client itself and never received as a body, so it has none.",
+ "enum": ["problem", "warning", "client"]
+ },
+ "status": {
+ "description": "The HTTP status of a response the code is the body of. A code kept only in a run's record carries the status the run's synchronous execution would answer with.",
+ "type": "integer",
+ "minimum": 400,
+ "maximum": 599
+ },
+ "detail": {
+ "description": "The template of the problem's detail: this occurrence, in one or two sentences.",
+ "$ref": "#/$defs/template"
+ },
+ "steps": {
+ "description": "The step for the domain's actor and the step for any other reader.",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["actor", "other"],
+ "properties": {
+ "actor": { "$ref": "#/$defs/step" },
+ "other": { "$ref": "#/$defs/step" }
+ }
+ },
+ "params": {
+ "description": "The code's parameters by name, in the order its page lists them. Empty for a code that declares none.",
+ "type": "object",
+ "propertyNames": { "$ref": "#/$defs/segment" },
+ "additionalProperties": { "$ref": "#/$defs/param" }
+ },
+ "meaning": {
+ "description": "What the code means, as its page says it.",
+ "$ref": "#/$defs/text"
+ },
+ "what_to_do": {
+ "description": "What to do about it, as its page says it.",
+ "$ref": "#/$defs/text"
+ },
+ "see": {
+ "description": "The pages of the specification that define the situation the code names.",
+ "type": "array",
+ "minItems": 1,
+ "items": { "$ref": "#/$defs/reference" }
+ }
+ },
+ "if": { "properties": { "raised_as": { "const": "problem" } } },
+ "then": { "required": ["status"] },
+ "else": { "properties": { "status": false } }
+ }
+ }
+}
diff --git a/pipelex/cli/dev_cli/commands/error_registry/standard/vendored.toml b/pipelex/cli/dev_cli/commands/error_registry/standard/vendored.toml
new file mode 100644
index 000000000..8d5949399
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/error_registry/standard/vendored.toml
@@ -0,0 +1,28 @@
+# The MTHDS standard's files that Pipelex's error registry is checked against, copied verbatim from the
+# standard's repository and never edited here.
+#
+# - `mthds-error-registry.schema.json` is the JSON Schema of the registry format, which an extension
+# owner's registry follows as the core registry does.
+# - `mthds-error-registry.json` is the snapshot of the core registry. The checks read it to confirm that
+# the `pipelex` prefix is registered with the base URL Pipelex's pages are served under, and that every
+# core code an entry's documentation names exists. Nothing at run time reads this copy: it is an
+# input of the checks alone.
+#
+# To refresh them, copy both files from the standard release they belong to, at the tag `v<version>` or
+# from its release assets, then update the commit, the version and each file's digest below. A test
+# fails when a file no longer has the digest recorded here.
+
+[source]
+repository = "https://github.com/mthds-ai/mthds"
+# The standard's branch that introduces the error registry, before its release.
+ref = "feature/Core-error-registry"
+commit = "d5dadecf63eac58734d0021d36974a4462def15a"
+standard_version = "7.1.0"
+
+[files."mthds-error-registry.schema.json"]
+path = "docs/spec/openapi/mthds-error-registry.schema.json"
+sha256 = "2923af37db081788fdfaf43d8d0e24a39e68be3ebd43f75ef64a04f87480e723"
+
+[files."mthds-error-registry.json"]
+path = "docs/spec/openapi/mthds-error-registry.json"
+sha256 = "4992e6bd8a30eb97016bb68620487b589f639ec08a860bfb8ce6b5b952169eb8"
diff --git a/pipelex/cli/dev_cli/commands/error_registry/type_redirects.py b/pipelex/cli/dev_cli/commands/error_registry/type_redirects.py
new file mode 100644
index 000000000..8dd9d88ff
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/error_registry/type_redirects.py
@@ -0,0 +1,145 @@
+"""The redirect stubs that make a Pipelex code's type URI reach its page on docs.pipelex.com.
+
+A code's type URI is the registry's base URL, a slash, then the whole code:
+``https://docs.pipelex.com/errors/pipelex.billing.plan_limit``. The documentation itself is versioned,
+and serves the code's page at ``/<version>/errors/pipelex/billing/plan_limit/``, with ``/latest/`` the
+released version. The site is served by GitHub Pages from its ``gh-pages`` branch, with no server-side
+redirect of our own, so the documentation's deployment writes, at the root of the published site, one
+directory per code named after the whole code, holding an ``index.html`` that redirects to the code's
+``/latest/`` page. GitHub Pages answers a URL naming a directory without its trailing slash, as the type
+URI does, with a 301 to the same URL with the slash, whatever its last segment holds (``/0.87.0`` is
+answered so too), and serves the directory's ``index.html`` there. The stubs are written from the pages the
+released version holds, so a code resolves once a release that documents it is the latest, and a stub whose
+code the latest version no longer documents is removed. The base URL itself gets a root stub, redirecting to
+the codes' index under ``/latest/``, only while the latest version documents at least one code; otherwise a
+root stub written earlier is removed, and only a file carrying the stubs' marker is ever removed.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+from typing import TYPE_CHECKING
+from urllib.parse import urlsplit
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from pipelex.cli.dev_cli.commands.error_registry.exceptions import ErrorRegistryError
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+# The version directory of the published site that the type URIs resolve to.
+LATEST_DIR_NAME = "latest"
+# The comment every stub carries, so that only a stub this module wrote is ever removed.
+STUB_MARKER = "<!-- pipelex-dev write-error-type-redirects: the type URI of an error code -->"
+# How a report names the root stub, the base URL's own, which serves no code.
+ROOT_STUB_NAME = "(index)"
+
+_SEGMENT = r"[a-z][a-z0-9_]*"
+_CODE_DIR_REGEX = re.compile(rf"^{_SEGMENT}(\.{_SEGMENT})+$")
+
+
+class TypeRedirectsReport(BaseModel):
+ """What a run of :func:`write_type_redirects` did, by the code each stub serves."""
+
+ model_config = ConfigDict(frozen=True)
+
+ written: list[str] = Field(default_factory=list)
+ unchanged: list[str] = Field(default_factory=list)
+ removed: list[str] = Field(default_factory=list)
+
+
+def render_stub(*, target_path: str, site_origin: str) -> str:
+ """A page that sends its reader to ``target_path``, keeping the URL's fragment, as the documentation's other redirects do."""
+ return (
+ "<!doctype html>\n"
+ '<html lang="en">\n'
+ "<head>\n"
+ f"{STUB_MARKER}\n"
+ '<meta charset="utf-8">\n'
+ "<title>Redirecting...</title>\n"
+ f'<link rel="canonical" href="{site_origin}{target_path}">\n'
+ '<meta name="robots" content="noindex">\n'
+ f'<script>var anchor=window.location.hash.substr(1);location.href="{target_path}"+(anchor?"#"+anchor:"")</script>\n'
+ f'<meta http-equiv="refresh" content="0; url={target_path}">\n'
+ "</head>\n"
+ "<body>\n"
+ f'Redirecting to <a href="{target_path}">{target_path}</a>...\n'
+ "</body>\n"
+ "</html>\n"
+ )
+
+
+def _documented_codes(*, pages_dir: Path) -> list[str]:
+ """Every code whose page the published version holds: ``<prefix>/<family>/<name>/index.html`` is ``<prefix>.<family>.<name>``."""
+ codes: list[str] = []
+ for index_file in sorted(pages_dir.glob("*/*/*/index.html")):
+ segments = index_file.parent.relative_to(pages_dir).parts
+ code = ".".join(segments)
+ if _CODE_DIR_REGEX.match(code):
+ codes.append(code)
+ return codes
+
+
+def write_type_redirects(*, site_root: Path, base_url: str) -> TypeRedirectsReport:
+ """Write, under the published site's root, the stub of every code the latest version documents, and remove stale stubs.
+
+ Args:
+ site_root: The root of the published site, a checkout of its ``gh-pages`` branch.
+ base_url: The registry's base URL, whose path is where the stubs go and whose origin their canonical links name.
+
+ Raises:
+ ErrorRegistryError: When the site has no latest version, or the base URL lies elsewhere than the site's root.
+ """
+ url = urlsplit(base_url)
+ stubs_path = url.path.strip("/")
+ if not stubs_path:
+ msg = f"the base URL {base_url} has no path, so the type URIs would overwrite the site's root"
+ raise ErrorRegistryError(msg)
+ site_origin = f"{url.scheme}://{url.netloc}"
+ pages_dir = site_root / LATEST_DIR_NAME / stubs_path
+ if not (site_root / LATEST_DIR_NAME).is_dir():
+ msg = f"{site_root} holds no '{LATEST_DIR_NAME}' version, so no type URI can resolve"
+ raise ErrorRegistryError(msg)
+ stubs_dir = site_root / stubs_path
+ codes = _documented_codes(pages_dir=pages_dir) if pages_dir.is_dir() else []
+
+ written: list[str] = []
+ unchanged: list[str] = []
+ removed: list[str] = []
+ targets = {code: f"/{LATEST_DIR_NAME}/{stubs_path}/{code.replace('.', '/')}/" for code in codes}
+ # The root stub sends the base URL to the codes' index under /latest/, which only a version that documents
+ # the codes holds: before such a release is the latest, /latest/errors/ is not that index, and may be no
+ # page at all, so no root stub is written, and the site's 404 page sends the base URL to /latest/ as it
+ # sends any path without a version.
+ if codes:
+ targets[""] = f"/{LATEST_DIR_NAME}/{stubs_path}/"
+ for code, target_path in targets.items():
+ stub_file = stubs_dir / code / "index.html" if code else stubs_dir / "index.html"
+ content = render_stub(target_path=target_path, site_origin=site_origin)
+ if stub_file.is_file() and stub_file.read_text(encoding="utf-8") == content:
+ unchanged.append(code or ROOT_STUB_NAME)
+ continue
+ stub_file.parent.mkdir(parents=True, exist_ok=True)
+ stub_file.write_text(content, encoding="utf-8", newline="\n")
+ written.append(code or ROOT_STUB_NAME)
+
+ if stubs_dir.is_dir():
+ for stub_dir in sorted(stubs_dir.iterdir()):
+ if not stub_dir.is_dir() or stub_dir.name in targets or not _CODE_DIR_REGEX.match(stub_dir.name):
+ continue
+ stub_file = stub_dir / "index.html"
+ if _is_stub(stub_file=stub_file):
+ shutil.rmtree(stub_dir)
+ removed.append(stub_dir.name)
+ root_stub_file = stubs_dir / "index.html"
+ if "" not in targets and _is_stub(stub_file=root_stub_file):
+ root_stub_file.unlink()
+ removed.append(ROOT_STUB_NAME)
+ return TypeRedirectsReport(written=written, unchanged=unchanged, removed=removed)
+
+
+def _is_stub(*, stub_file: Path) -> bool:
+ """Whether a file is a stub this module wrote, which alone it may remove: a file carrying the stub's marker."""
+ return stub_file.is_file() and STUB_MARKER in stub_file.read_text(encoding="utf-8")
diff --git a/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py b/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py
deleted file mode 100644
index 6181b600a..000000000
--- a/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py
+++ /dev/null
@@ -1,71 +0,0 @@
-"""Command to generate one docs page per ``PipelexError`` subclass."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from rich.panel import Panel
-
-from pipelex.errors.error_pages_generator import generate_error_pages
-from pipelex.pipelex import Pipelex
-from pipelex.runtime_hub import get_console
-
-ERROR_PAGES_DIR = Path("docs/errors")
-
-
-def generate_error_pages_cmd(*, output: Path | None = None, quiet: bool = False) -> None:
- """Generate per-class error documentation pages.
-
- Bootstraps Pipelex with ``needs_inference=False`` (kept for parity with other
- dev CLI commands and to surface config / setup errors loudly), then calls
- :func:`generate_error_pages`. Inference is never invoked here — the command only
- introspects ``PipelexError`` subclasses and writes markdown — so the bootstrap
- skips the inference setup, which a CI environment with no configured backend
- (e.g. the docs deploy job) could not complete. The underlying discovery rglobs every
- ``exceptions.py`` / ``*_exceptions.py`` via :func:`iter_pipelex_error_subclasses`
- — no manual import or class-list update is needed when a new error class lands.
- Pages already carrying ``<!-- pipelex:authored -->`` are preserved so hand-edited
- reference content is never clobbered.
-
- Args:
- output: Custom output directory. Defaults to ``docs/errors/``.
- quiet: If ``True``, emit only a single status line.
- """
- console = get_console()
- output_path = output or ERROR_PAGES_DIR
-
- if not quiet:
- console.print()
- console.print("[bold]Generating per-class error documentation pages...[/bold]")
- console.print()
-
- Pipelex.make(needs_inference=False)
- try:
- report = generate_error_pages(output_dir=output_path)
- finally:
- Pipelex.teardown_if_needed()
-
- written = len(report.written)
- unchanged = len(report.unchanged)
- preserved = len(report.preserved)
- removed = len(report.removed)
-
- if quiet:
- console.print(
- f"[green]✓ Error pages generation: PASSED[/green] ({written} written, {unchanged} unchanged, {preserved} preserved, {removed} removed)"
- )
- return
-
- success_panel = Panel(
- (
- f"[green]✓[/green] Error pages generated.\n\n"
- f"[dim]Output: {output_path}[/dim]\n"
- f"[dim]Total pages: {report.total}[/dim]\n"
- f"[dim]Written: {written} · Unchanged: {unchanged} · Preserved (authored): {preserved} · Removed: {removed}[/dim]"
- ),
- title="[bold green]Error Pages Generation: PASSED[/bold green]",
- border_style="green",
- padding=(1, 2),
- )
- console.print(success_panel)
- console.print()
diff --git a/pipelex/errors/error_class_discovery.py b/pipelex/errors/error_class_discovery.py
new file mode 100644
index 000000000..385aad261
--- /dev/null
+++ b/pipelex/errors/error_class_discovery.py
@@ -0,0 +1,133 @@
+"""Discovery of every ``PipelexError`` subclass the package defines.
+
+The committed wire-identity snapshot (:mod:`pipelex.errors.error_identity_snapshot`), the
+``type_uri`` uniqueness check and the error-class location convention all need the complete set of
+error classes, including the ones whose module only a deferred plugin or factory import would reach.
+:func:`iter_pipelex_error_subclasses` gives them that set, without bootstrapping Pipelex.
+"""
+
+from __future__ import annotations
+
+import functools
+import importlib
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pipelex
+from pipelex.base_exceptions import PipelexError
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
+
+
+_PIPELEX_ROOT = Path(pipelex.__file__).resolve().parent
+_FIXTURE_DIR_NAMES = frozenset({"test_extras", "test_helpers"})
+
+
+def _force_load_all_error_modules() -> None:
+ """Force-import every ``exceptions.py`` / ``*_exceptions.py`` module under ``pipelex/``.
+
+ Cached via :func:`functools.cache` so the first call walks the package and
+ ``importlib.import_module``-s every properly-named error module while
+ subsequent calls are no-ops. Two preconditions keep this safe and complete,
+ both enforced by
+ ``tests/unit/pipelex/errors/test_error_class_location_convention.py``:
+
+ 1. Every :class:`PipelexError` subclass lives in a module named
+ ``exceptions.py`` or ``<topic>_exceptions.py``. A name-filtered ``rglob``
+ therefore captures the complete error-class set, with no allowlist.
+ 2. Every properly-named error module imports only base error classes
+ (``PipelexError`` / ``CogtError`` / ``CredentialsError`` /
+ ``ClickException``) and no third-party SDK. Force-loading adds no
+ optional-plugin weight to pytest collection or dev CLI invocations.
+
+ Production code (notably ``Pipelex.make()``) does NOT touch this: discovery
+ has no runtime side effect outside the dev and test consumers.
+
+ Per-module import failures are accumulated and raised once at the end so a
+ single broken ``*_exceptions.py`` surfaces with its dotted module name
+ rather than aborting the walk under an opaque exception whose traceback
+ frames all live inside this helper. ``functools.cache`` only memoizes the
+ success path (no caching on exception), so a fix-then-retry cycle inside
+ a long-lived dev session works without ``cache_clear()``.
+
+ The catch is intentionally broad: ``importlib.import_module`` runs the
+ target module's top-level code, so a typo or bad reference inside a new
+ ``*_exceptions.py`` can surface as ``NameError``, ``SyntaxError``,
+ ``AttributeError``, … — all of which must be aggregated like ``ImportError``
+ so the dev sees the full list of broken modules at once.
+ """
+ failures: list[tuple[str, BaseException]] = []
+ for path in sorted(_PIPELEX_ROOT.rglob("*.py")):
+ name = path.name
+ if name != "exceptions.py" and not name.endswith("_exceptions.py"):
+ continue
+ rel = path.relative_to(_PIPELEX_ROOT.parent).with_suffix("")
+ dotted = ".".join(rel.parts)
+ try:
+ importlib.import_module(dotted)
+ except Exception as exc: # ruff: ignore[blind-except]
+ # importlib runs the target module's top-level code — an open-ended exception surface
+ # (NameError, SyntaxError, …) that must be aggregated like ImportError so the dev
+ # sees the full list of broken modules at once instead of aborting on the first one.
+ failures.append((dotted, exc))
+ if failures:
+ lines = ["One or more error modules failed to import during discovery:"]
+ lines.extend(f" - {name}: {exc}" for name, exc in failures)
+ msg = "\n".join(lines)
+ # Chain from the first failure so the dev sees a full traceback (file:line
+ # of the broken module) in addition to the aggregated list of names —
+ # str(exc) alone elides where the failure happened.
+ raise RuntimeError(msg) from failures[0][1]
+
+
+def _is_production_subclass(cls: type[PipelexError]) -> bool:
+ """True when ``cls`` should appear in the production discovery set.
+
+ Excludes synthetic subclasses created inside test modules (``tests.*``) and
+ classes defined inside shipped fixture packages (``pipelex/.../test_extras/``,
+ ``pipelex/.../test_helpers/``) — those are test infrastructure that happens
+ to be packaged alongside production code so it can be reused across
+ downstream test suites.
+ """
+ if cls.__module__.startswith("tests."):
+ return False
+ module = sys.modules.get(cls.__module__)
+ if module is None:
+ return True
+ module_file = getattr(module, "__file__", None)
+ if module_file is None:
+ return True
+ try:
+ rel = Path(module_file).resolve().relative_to(_PIPELEX_ROOT)
+ except ValueError:
+ return True
+ return _FIXTURE_DIR_NAMES.isdisjoint(rel.parts)
+
+
+def iter_pipelex_error_subclasses() -> Iterator[type[PipelexError]]:
+ """Yield :class:`PipelexError` and every loaded subclass, breadth-first.
+
+ Calls :func:`_force_load_all_error_modules` first so deferred-import
+ plugin / factory error modules are reachable via ``__subclasses__()``. The
+ call is idempotent — first invocation walks the filesystem, subsequent
+ invocations are no-ops.
+
+ Skips classes that fail :func:`_is_production_subclass` so synthetic
+ subclasses created by other tests in the same pytest session and classes
+ defined under shipped fixture packages (``pipelex/.../test_extras/`` /
+ ``test_helpers/``) never leak into the snapshot or the checks.
+ """
+ _force_load_all_error_modules()
+ seen: set[type[PipelexError]] = set()
+ stack: list[type[PipelexError]] = [PipelexError]
+ while stack:
+ cls = stack.pop()
+ if cls in seen:
+ continue
+ seen.add(cls)
+ if _is_production_subclass(cls):
+ yield cls
+ stack.extend(cls.__subclasses__())
diff --git a/pipelex/errors/error_identity_snapshot.py b/pipelex/errors/error_identity_snapshot.py
index b353d830e..ee0bcf578 100644
--- a/pipelex/errors/error_identity_snapshot.py
+++ b/pipelex/errors/error_identity_snapshot.py
@@ -25,7 +25,7 @@ from __future__ import annotations
from typing import NamedTuple
-from pipelex.errors.error_pages_generator import iter_pipelex_error_subclasses
+from pipelex.errors.error_class_discovery import iter_pipelex_error_subclasses
# Column separator. Space-padded so the fields stay legible in a raw diff, and
# absent from every class name / type URI so a naive split round-trips.
diff --git a/pipelex/errors/error_pages_generator.py b/pipelex/errors/error_pages_generator.py
deleted file mode 100644
index a63a4b852..000000000
--- a/pipelex/errors/error_pages_generator.py
+++ /dev/null
@@ -1,607 +0,0 @@
-"""Generator for the per-class error documentation pages.
-
-Each non-test :class:`pipelex.base_exceptions.PipelexError` subclass gets a
-markdown page at ``docs/errors/<kebab-class-name>.md``, named so the path
-aligns with :meth:`PipelexError.type_uri`'s final segment. The docs site can
-then host those pages at ``<base_uri>/<kebab-class-name>`` and a clickable
-RFC 7807 ``type`` URI lands the user on a populated reference page.
-
-Pages a maintainer has hand-edited are protected by an ``<!-- pipelex:authored -->``
-HTML comment anywhere in the file: when the generator detects it on an
-existing page, the page is left untouched. Generated pages carry a different
-marker (``<!-- pipelex:generated -->``) so a quick ``grep`` distinguishes the
-two populations.
-"""
-
-from __future__ import annotations
-
-import functools
-import importlib
-import sys
-from dataclasses import field
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-from pydantic.dataclasses import dataclass
-
-import pipelex
-from pipelex.base_exceptions import ErrorDomain, PipelexError
-from pipelex.cogt.inference.error_classification import UserAction
-from pipelex.tools.misc.string_utils import pascal_case_to_kebab
-
-if TYPE_CHECKING:
- from collections.abc import Iterable, Iterator
-
-
-_PIPELEX_ROOT = Path(pipelex.__file__).resolve().parent
-_FIXTURE_DIR_NAMES = frozenset({"test_extras", "test_helpers"})
-
-
-def _force_load_all_error_modules() -> None:
- """Force-import every ``exceptions.py`` / ``*_exceptions.py`` module under ``pipelex/``.
-
- Cached via :func:`functools.cache` so the first call walks the package and
- ``importlib.import_module``-s every properly-named error module while
- subsequent calls are no-ops. Two preconditions keep this safe and complete,
- both enforced by
- ``tests/unit/pipelex/errors/test_error_class_location_convention.py``:
-
- 1. Every :class:`PipelexError` subclass lives in a module named
- ``exceptions.py`` or ``<topic>_exceptions.py`` (the Phase 6 file-naming
- convention). A name-filtered ``rglob`` therefore captures the complete
- error-class set — no allowlist needed.
- 2. Every properly-named error module imports only base error classes
- (``PipelexError`` / ``CogtError`` / ``CredentialsError`` /
- ``ClickException``) — no third-party SDK pulls. Force-loading adds no
- optional-plugin weight to pytest collection or dev CLI invocations.
-
- Called by :func:`iter_pipelex_error_subclasses` so the docs generator and
- the type-URI uniqueness test see every subclass — including those whose
- home module is otherwise reached only by a deferred plugin / factory
- import path. Production code (notably ``Pipelex.make()``) does NOT touch
- this — discovery has no runtime side effect outside the dev/test-time
- consumers.
-
- Per-module import failures are accumulated and raised once at the end so a
- single broken ``*_exceptions.py`` surfaces with its dotted module name
- rather than aborting the walk under an opaque exception whose traceback
- frames all live inside this helper. ``functools.cache`` only memoizes the
- success path (no caching on exception), so a fix-then-retry cycle inside
- a long-lived dev session works without ``cache_clear()``.
-
- The catch is intentionally broad: ``importlib.import_module`` runs the
- target module's top-level code, so a typo or bad reference inside a new
- ``*_exceptions.py`` can surface as ``NameError``, ``SyntaxError``,
- ``AttributeError``, … — all of which must be aggregated like ``ImportError``
- so the dev sees the full list of broken modules at once.
-
- To clear the cache (e.g. inside a long-lived dev session after adding a
- new ``*_exceptions.py``), call ``_force_load_all_error_modules.cache_clear()``.
- """
- failures: list[tuple[str, BaseException]] = []
- for path in sorted(_PIPELEX_ROOT.rglob("*.py")):
- name = path.name
- if name != "exceptions.py" and not name.endswith("_exceptions.py"):
- continue
- rel = path.relative_to(_PIPELEX_ROOT.parent).with_suffix("")
- dotted = ".".join(rel.parts)
- try:
- importlib.import_module(dotted)
- except Exception as exc: # ruff: ignore[blind-except]
- # importlib runs the target module's top-level code — an open-ended exception surface
- # (NameError, SyntaxError, …) that must be aggregated like ImportError so the dev
- # sees the full list of broken modules at once instead of aborting on the first one.
- failures.append((dotted, exc))
- if failures:
- lines = ["One or more error modules failed to import during discovery:"]
- lines.extend(f" - {name}: {exc}" for name, exc in failures)
- msg = "\n".join(lines)
- # Chain from the first failure so the dev sees a full traceback (file:line
- # of the broken module) in addition to the aggregated list of names —
- # str(exc) alone elides where the failure happened.
- raise RuntimeError(msg) from failures[0][1]
-
-
-def _is_production_subclass(cls: type[PipelexError]) -> bool:
- """True when ``cls`` should appear in the production discovery set.
-
- Excludes synthetic subclasses created inside test modules (``tests.*``) and
- classes defined inside shipped fixture packages (``pipelex/.../test_extras/``,
- ``pipelex/.../test_helpers/``) — those are test infrastructure that happens
- to be packaged alongside production code so it can be reused across
- downstream test suites.
- """
- if cls.__module__.startswith("tests."):
- return False
- module = sys.modules.get(cls.__module__)
- if module is None:
- return True
- module_file = getattr(module, "__file__", None)
- if module_file is None:
- return True
- try:
- rel = Path(module_file).resolve().relative_to(_PIPELEX_ROOT)
- except ValueError:
- return True
- return _FIXTURE_DIR_NAMES.isdisjoint(rel.parts)
-
-
-def iter_pipelex_error_subclasses() -> Iterator[type[PipelexError]]:
- """Yield :class:`PipelexError` and every loaded subclass, breadth-first.
-
- Calls :func:`_force_load_all_error_modules` first so deferred-import
- plugin / factory error modules are reachable via ``__subclasses__()``. The
- call is idempotent — first invocation walks the filesystem, subsequent
- invocations are no-ops.
-
- Skips classes that fail :func:`_is_production_subclass` so synthetic
- subclasses created by other tests in the same pytest session and classes
- defined under shipped fixture packages (``pipelex/.../test_extras/`` /
- ``test_helpers/``) never leak into the generated docs or the smoke-test
- assertions.
- """
- _force_load_all_error_modules()
- seen: set[type[PipelexError]] = set()
- stack: list[type[PipelexError]] = [PipelexError]
- while stack:
- cls = stack.pop()
- if cls in seen:
- continue
- seen.add(cls)
- if _is_production_subclass(cls):
- yield cls
- stack.extend(cls.__subclasses__())
-
-
-# Marker a maintainer adds to a generated page to claim it for hand-editing.
-# When present, :func:`generate_error_pages` skips the page on regeneration.
-AUTHORED_MARKER = "<!-- pipelex:authored -->"
-# Marker stamped on every generated page so the two populations are
-# distinguishable at a glance (``grep -L pipelex:authored docs/errors``).
-GENERATED_MARKER = "<!-- pipelex:generated -->"
-# Stem of the landing page emitted alongside the per-class pages. Kept in nav;
-# the per-class pages are declared ``not_in_nav`` in ``mkdocs.yml`` so the
-# sidebar does not balloon with one entry per error class.
-INDEX_STEM = "index"
-
-
-@dataclass(frozen=True)
-class ErrorPagesReport:
- """Outcome summary returned by :func:`generate_error_pages`.
-
- Carries the four populations the CLI command reports back:
- ``written`` (a page was newly created or refreshed),
- ``unchanged`` (a generated page already on disk was byte-identical),
- ``preserved`` (the file carried :data:`AUTHORED_MARKER` and was left as-is),
- ``removed`` (a previously-generated page no longer maps to a target class
- and was deleted; pages bearing :data:`AUTHORED_MARKER` are never removed
- and surface as ``preserved`` instead).
-
- ``frozen`` only blocks rebinding the fields — the lists are still populated
- in place via ``.append`` by ``_commit_page`` / ``_remove_orphans``.
- """
-
- written: list[Path] = field(default_factory=list[Path])
- unchanged: list[Path] = field(default_factory=list[Path])
- preserved: list[Path] = field(default_factory=list[Path])
- removed: list[Path] = field(default_factory=list[Path])
-
- @property
- def total(self) -> int:
- return len(self.written) + len(self.unchanged) + len(self.preserved) + len(self.removed)
-
-
-def page_slug(cls: type[PipelexError]) -> str:
- """Return the kebab-case slug used both as the file stem and as the URI tail."""
- return pascal_case_to_kebab(cls.__name__)
-
-
-def render_error_page(cls: type[PipelexError]) -> str:
- """Render the default markdown body for ``cls``.
-
- Includes the class identity (title, type URI, defining module), the
- declared error domain (or ``(inherited from parent)`` for subclasses that
- don't override it), a link to the parent class's page when the parent is
- itself a ``PipelexError``, the ``retryable`` and ``user_action`` the class
- declares in its own body, if any, and a back-link to the Error Reference index.
- """
- title = cls.title()
- type_uri = cls.type_uri()
- domain_value = _resolve_class_level_domain(cls)
- parent_link = _parent_link(cls)
- description = f"Reference for the `{cls.__name__}` Pipelex error class."
-
- rows: list[tuple[str, str]] = [
- ("`error_type`", f"`{cls.__name__}`"),
- ("`title`", title),
- ("`type_uri`", f"`{type_uri}`"),
- ("`error_domain`", domain_value),
- ("Defined in", f"`{cls.__module__}`"),
- ("Parent class", parent_link),
- ]
- declared_retryable = cls.__dict__.get("retryable")
- if isinstance(declared_retryable, bool):
- rows.append(("`retryable`", f"`{str(declared_retryable).lower()}`"))
- declared_action = _resolve_class_level_user_action(cls)
- if declared_action is not None:
- rows.append(("`user_action`", declared_action))
- docstring = _short_docstring(cls)
-
- lines: list[str] = [
- "---",
- f'title: "{title}"',
- f'description: "{description}"',
- "---",
- "",
- f"{GENERATED_MARKER}",
- "",
- f"# {title}",
- "",
- ]
- if docstring is not None:
- lines.extend([docstring, ""])
- lines.extend(
- [
- "| Field | Value |",
- "|---|---|",
- *(f"| {key} | {value} |" for key, value in rows),
- "",
- "[Back to Error Reference](index.md)",
- "",
- ]
- )
- return "\n".join(lines)
-
-
-def generate_error_pages(
- *,
- output_dir: Path,
- classes: Iterable[type[PipelexError]] | None = None,
-) -> ErrorPagesReport:
- """Write one markdown page per :class:`PipelexError` subclass into ``output_dir``.
-
- ``classes`` defaults to every loaded production subclass via
- :func:`iter_pipelex_error_subclasses`. Alongside the per-class pages it
- emits an ``index.md`` overview and one macro listing page per non-empty
- :data:`_MACRO_SECTIONS` area (the entries nested under "Error Reference" in
- the nav). Pages bearing :data:`AUTHORED_MARKER` are left untouched and
- reported under ``preserved``; pages whose generated content matches what's
- already on disk are reported as ``unchanged`` (no write, no mtime churn).
- Pre-existing generated pages whose slug no longer appears in
- ``target_classes`` (or a macro page that lost all its classes) are deleted
- and reported under ``removed`` — pages with :data:`AUTHORED_MARKER` are never
- removed, the index page is never removed.
-
- Raises a loud ``RuntimeError`` if two target classes resolve to the same
- kebab slug (e.g. ``LLMError`` and ``LlmError`` both kebab to ``llm-error``),
- or if a class slug collides with a generated listing-page stem (the index or
- a macro-area page), so either collision is caught at generation time instead
- of silently overwriting a page.
- """
- output_dir.mkdir(parents=True, exist_ok=True)
- target_classes = list(classes) if classes is not None else list(iter_pipelex_error_subclasses())
-
- # Stems owned by the generated listing pages (the index + one per macro area). A
- # per-class page is committed first, then the listing pages to the same dir, so a
- # class whose slug lands here would have its reference page silently overwritten —
- # catch it loudly at generation time instead.
- reserved_stems = {INDEX_STEM, *(slug for slug, _ in _MACRO_SECTIONS)}
- slug_owners: dict[str, type[PipelexError]] = {}
- for cls in target_classes:
- slug = page_slug(cls)
- if slug in reserved_stems:
- msg = (
- f"Reserved-slug collision on {slug!r}: {cls.__module__}.{cls.__name__} kebabs to "
- "the stem of a generated listing page (the index or a macro-area page), whose "
- "content would overwrite the per-class page. Rename the class."
- )
- raise RuntimeError(msg)
- previous = slug_owners.get(slug)
- if previous is not None and previous is not cls:
- msg = (
- f"Kebab-slug collision on {slug!r}: {previous.__module__}.{previous.__name__} "
- f"and {cls.__module__}.{cls.__name__} both resolve to the same docs page. "
- "Rename one class — acronym-casing variants (e.g. LLMError / LlmError) kebab "
- "to the same slug."
- )
- raise RuntimeError(msg)
- slug_owners[slug] = cls
-
- report = ErrorPagesReport()
- expected_stems: set[str] = {page_slug(cls) for cls in target_classes} | {INDEX_STEM}
- for cls in target_classes:
- target = output_dir / f"{page_slug(cls)}.md"
- _commit_page(target=target, new_content=render_error_page(cls), report=report)
-
- # Macro listing pages — one per non-empty macro area. Their stems join
- # ``expected_stems`` so a macro that still has classes is never treated as an
- # orphan, while a macro that loses all its classes (none written this run)
- # falls through to ``_remove_orphans`` and is deleted like any stale page.
- by_subsystem = _group_by_subsystem(target_classes)
- for macro_slug, macro_heading in _MACRO_SECTIONS:
- sections = _subsystems_for_macro(macro_slug=macro_slug, by_subsystem=by_subsystem)
- if not sections:
- continue
- _commit_page(
- target=output_dir / f"{macro_slug}.md", new_content=render_macro_page(macro_heading=macro_heading, sections=sections), report=report
- )
- expected_stems.add(macro_slug)
-
- index_target = output_dir / f"{INDEX_STEM}.md"
- _commit_page(target=index_target, new_content=render_index_page(by_subsystem), report=report)
-
- _remove_orphans(output_dir=output_dir, expected_stems=expected_stems, report=report)
-
- return report
-
-
-def _remove_orphans(output_dir: Path, *, expected_stems: set[str], report: ErrorPagesReport) -> None:
- """Delete generated ``.md`` files whose stem is not in ``expected_stems``.
-
- Files carrying :data:`AUTHORED_MARKER` are preserved verbatim — those
- pages have been hand-claimed and the maintainer is responsible for their
- lifecycle. Files with no marker at all (neither generated nor authored)
- are left alone too, since this function only takes responsibility for
- pages this generator previously wrote.
- """
- for path in output_dir.glob("*.md"):
- if path.stem in expected_stems:
- continue
- content = path.read_text(encoding="utf-8")
- if has_authored_marker(content):
- report.preserved.append(path)
- continue
- if GENERATED_MARKER not in content:
- continue
- path.unlink()
- report.removed.append(path)
-
-
-def _commit_page(*, target: Path, new_content: str, report: ErrorPagesReport) -> None:
- """Apply the write / unchanged / preserved classification to one target path."""
- if target.exists():
- existing = target.read_text(encoding="utf-8")
- if has_authored_marker(existing):
- report.preserved.append(target)
- return
- if existing == new_content:
- report.unchanged.append(target)
- return
- target.write_text(new_content, encoding="utf-8")
- report.written.append(target)
-
-
-# Macro sections — the top-level left-sidebar groups nested under "Error
-# Reference" in ``mkdocs.yml``, in display order. ``(slug, heading)``. Each
-# bundles several subsystems (see :data:`_SUBSYSTEM_SECTIONS`) onto one listing
-# page so the nav shows a handful of macro areas instead of one flat entry.
-# The slugs are the page stems (``errors/<slug>.md``) and MUST stay in sync with
-# the nav block + ``not_in_nav`` re-includes in ``mkdocs.yml``.
-_MACRO_SECTIONS: tuple[tuple[str, str], ...] = (
- ("authoring-and-language", "Authoring & language"),
- ("execution-and-runtime", "Execution & runtime"),
- ("inference-and-providers", "Inference & providers"),
- ("platform-and-tooling", "Platform & tooling"),
-)
-
-# The macro that adopts any subsystem not explicitly assigned in
-# :data:`_SUBSYSTEM_SECTIONS` — keeps a newly-added ``pipelex.<area>`` reachable
-# in the nav (under a humanized heading) without a manifest edit. Must be one of
-# the :data:`_MACRO_SECTIONS` slugs.
-_FALLBACK_MACRO_SLUG = "platform-and-tooling"
-
-# Curated subsystem sections, in display order *within* their macro. Each entry
-# is ``(subsystem_key, macro_slug, heading)``. ``subsystem_key`` is the second
-# segment of a class's defining module (``pipelex.<subsystem>.…``) — the layer
-# that groups errors by the area of the codebase they originate from. A subsystem
-# missing from this tuple still renders: it lands in the fallback macro under a
-# humanized heading (see :func:`_subsystems_for_macro`), so adding a new
-# ``pipelex/<area>/…_exceptions.py`` needs no edit here — the curation only pins
-# label wording, macro placement, and ordering, never completeness.
-_SUBSYSTEM_SECTIONS: tuple[tuple[str, str, str], ...] = (
- # Authoring & language
- ("mthds_parsing", "authoring-and-language", "MTHDS parsing"),
- ("core", "authoring-and-language", "Core language"),
- ("pipe_operators", "authoring-and-language", "Pipe operators"),
- ("pipe_controllers", "authoring-and-language", "Pipe controllers"),
- ("pipe_signature", "authoring-and-language", "Pipe signatures"),
- ("libraries", "authoring-and-language", "Libraries"),
- # Execution & runtime
- ("pipe_run", "execution-and-runtime", "Pipe execution"),
- ("pipeline", "execution-and-runtime", "Pipeline execution"),
- ("runtime_bridge", "execution-and-runtime", "Runtime bridge"),
- ("graph", "execution-and-runtime", "Graph"),
- ("tracing", "execution-and-runtime", "Tracing"),
- # Inference & providers
- ("cogt", "inference-and-providers", "Inference (Cogt)"),
- # Two rows, because the vendor adapters and the plugin mechanism they register through are
- # two packages. `providers` is the one a method author hits (a vendor SDK rejected the call);
- # `plugins` is the one an integrator hits (a plugin failed to load or claimed a taken slot).
- ("providers", "inference-and-providers", "Provider adapters"),
- ("plugins", "inference-and-providers", "Plugin system"),
- # Platform & tooling
- ("base_exceptions", "platform-and-tooling", "Base & root errors"),
- ("tools", "platform-and-tooling", "Tools"),
- ("kit", "platform-and-tooling", "Kit"),
- ("system", "platform-and-tooling", "System & configuration"),
- ("cli", "platform-and-tooling", "CLI"),
-)
-
-
-def _subsystem_key(cls: type[PipelexError]) -> str:
- """Return the subsystem grouping key for ``cls`` — the second segment of its module path.
-
- Every ``PipelexError`` subclass lives at ``pipelex.<subsystem>.…exceptions``
- (root errors live directly in ``pipelex.base_exceptions``), so the second
- dotted segment names the area of the codebase the error belongs to. That is
- the axis the listing pages group on.
- """
- parts = cls.__module__.split(".")
- return parts[1] if len(parts) > 1 else parts[0]
-
-
-def _humanize_subsystem(key: str) -> str:
- """Fallback heading for an uncurated subsystem ``key`` (snake_case → Sentence case)."""
- return key.replace("_", " ").capitalize()
-
-
-def _group_by_subsystem(classes: Iterable[type[PipelexError]]) -> dict[str, list[type[PipelexError]]]:
- """Bucket ``classes`` by :func:`_subsystem_key`, each bucket alphabetized by class name."""
- by_subsystem: dict[str, list[type[PipelexError]]] = {}
- for cls in sorted(classes, key=lambda c: c.__name__):
- by_subsystem.setdefault(_subsystem_key(cls), []).append(cls)
- return by_subsystem
-
-
-def _subsystems_for_macro(
- *,
- macro_slug: str,
- by_subsystem: dict[str, list[type[PipelexError]]],
-) -> list[tuple[str, list[type[PipelexError]]]]:
- """Return the ``(heading, classes)`` subsystem sections that belong on a macro page.
-
- Curated subsystems assigned to ``macro_slug`` come first, in
- :data:`_SUBSYSTEM_SECTIONS` order. The fallback macro additionally adopts any
- uncurated subsystem present, appended alphabetically under a humanized
- heading. Subsystems with no loaded classes are skipped, so a macro with
- nothing to show yields an empty list and no page is written.
- """
- sections: list[tuple[str, list[type[PipelexError]]]] = []
- for key, assigned_macro, heading in _SUBSYSTEM_SECTIONS:
- if assigned_macro == macro_slug and key in by_subsystem:
- sections.append((heading, by_subsystem[key]))
- if macro_slug == _FALLBACK_MACRO_SLUG:
- curated = {key for key, _, _ in _SUBSYSTEM_SECTIONS}
- for key in sorted(by_subsystem):
- if key not in curated:
- sections.append((_humanize_subsystem(key), by_subsystem[key]))
- return sections
-
-
-def render_macro_page(*, macro_heading: str, sections: list[tuple[str, list[type[PipelexError]]]]) -> str:
- """Render one macro listing page: a ``## subsystem`` block per section, class links beneath.
-
- ``sections`` is the output of :func:`_subsystems_for_macro` — already ordered
- and non-empty.
- """
- description = f"Pipelex error classes in the {macro_heading} area, grouped by subsystem."
- lines: list[str] = [
- "---",
- f'title: "{macro_heading}"',
- f'description: "{description}"',
- "---",
- "",
- f"{GENERATED_MARKER}",
- "",
- f"# {macro_heading}",
- "",
- "Each error class below has a stable RFC 7807 `type` URI that dereferences to its",
- "own page. Classes are grouped by subsystem.",
- "",
- ]
- for heading, classes in sections:
- lines.append(f"## {heading}")
- lines.append("")
- for cls in classes:
- lines.append(f"- [`{cls.__name__}`]({page_slug(cls)}.md) — {cls.title()}")
- lines.append("")
- lines.append("[Back to Error Reference](index.md)")
- lines.append("")
- return "\n".join(lines)
-
-
-def render_index_page(by_subsystem: dict[str, list[type[PipelexError]]]) -> str:
- """Render the Error Reference overview that links to each macro listing page.
-
- The overview stays light: it explains the ``type`` URI contract and lists the
- macro sections (in :data:`_MACRO_SECTIONS` order), each annotated with the
- subsystems it covers — derived live from ``by_subsystem`` so the annotation
- never drifts from what the macro pages actually contain. A macro with no
- loaded classes is omitted.
- """
- lines: list[str] = [
- "---",
- 'title: "Error Reference"',
- 'description: "Auto-generated overview of the Pipelex error reference, grouped into macro areas of error classes."',
- "---",
- "",
- f"{GENERATED_MARKER}",
- "<!-- This index is generated by `pipelex-dev generate-error-pages`. To claim this",
- " page for hand-editing, add a standalone `pipelex:authored` HTML comment line;",
- " the generator will then preserve it on every run. -->",
- "",
- "# Error Reference",
- "",
- "Every Pipelex error class has a stable RFC 7807 `type` URI on the form",
- "`<base_uri>/<kebab-class-name>/`, and that URI dereferences to a per-class page.",
- "The classes are grouped into a few macro areas — pick the one that matches where",
- "the error came from:",
- "",
- ]
- for macro_slug, macro_heading in _MACRO_SECTIONS:
- sections = _subsystems_for_macro(macro_slug=macro_slug, by_subsystem=by_subsystem)
- if not sections:
- continue
- covered = ", ".join(heading for heading, _ in sections)
- lines.append(f"- [{macro_heading}]({macro_slug}.md) — {covered}.")
- lines.extend(
- [
- "",
- "See [Error Model](../under-the-hood/error-model.md) for the underlying contract",
- "and classification rules.",
- "",
- ]
- )
- return "\n".join(lines)
-
-
-def has_authored_marker(content: str) -> bool:
- """Return True when :data:`AUTHORED_MARKER` appears as its own (stripped) line.
-
- A standalone-line check ensures the generator's own instructional text —
- which mentions the marker inside a longer HTML comment — does not falsely
- flag every generated page as hand-authored on the next run.
- """
- return any(line.strip() == AUTHORED_MARKER for line in content.splitlines())
-
-
-def _resolve_class_level_domain(cls: type[PipelexError]) -> str:
- """Return the formatted ``error_domain`` value, or an inherited marker."""
- declared = cls.__dict__.get("error_domain")
- if isinstance(declared, ErrorDomain):
- return f"`{declared}`"
- if cls is PipelexError:
- return "_(unset)_"
- return "_(inherited from parent)_"
-
-
-def _resolve_class_level_user_action(cls: type[PipelexError]) -> str | None:
- """Return a markdown rendering of the class-level :class:`UserAction`, or ``None``."""
- declared = cls.__dict__.get("user_action")
- if not isinstance(declared, UserAction):
- return None
- kind_repr = f"`{declared.kind}`"
- if declared.detail:
- return f"{kind_repr} — {declared.detail}"
- return kind_repr
-
-
-def _parent_link(cls: type[PipelexError]) -> str:
- """Return a markdown link to the first ``PipelexError`` parent, or a plain ``Exception`` label."""
- parents = [base for base in cls.__bases__ if issubclass(base, PipelexError) and base is not cls]
- if not parents:
- return "`Exception` (Python builtin)"
- return f"[`{parents[0].__name__}`]({page_slug(parents[0])}.md)"
-
-
-def _short_docstring(cls: type[PipelexError]) -> str | None:
- """Return the first non-empty paragraph of ``cls.__doc__``, if any."""
- raw = cls.__dict__.get("__doc__")
- if not isinstance(raw, str):
- return None
- stripped = raw.strip()
- if not stripped:
- return None
- first_paragraph = stripped.split("\n\n", 1)[0]
- return " ".join(line.strip() for line in first_paragraph.splitlines() if line.strip())
diff --git a/pipelex/errors/registry/__init__.py b/pipelex/errors/registry/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/pipelex/errors/registry/pipelex-error-registry.json b/pipelex/errors/registry/pipelex-error-registry.json
new file mode 100644
index 000000000..2576fbbbd
--- /dev/null
+++ b/pipelex/errors/registry/pipelex-error-registry.json
@@ -0,0 +1,2037 @@
+{
+ "version": "0.89.0",
+ "prefix": "pipelex",
+ "base_url": "https://docs.pipelex.com/errors",
+ "families": [
+ {
+ "family": "pipelex.billing",
+ "description": "Credit and subscriptions: what an organization's plan and balance allow."
+ },
+ {
+ "family": "pipelex.org",
+ "description": "Organizations, their members, their API keys and their promo codes."
+ },
+ {
+ "family": "pipelex.catalog",
+ "description": "Saved methods in an organization's catalog."
+ },
+ {
+ "family": "pipelex.run",
+ "description": "Pipelex's extensions to runs."
+ },
+ {
+ "family": "pipelex.storage",
+ "description": "Pipelex's storage addresses and uploads."
+ },
+ {
+ "family": "pipelex.security",
+ "description": "Pipelex's own refusals made for safety, each recorded as a security event."
+ },
+ {
+ "family": "pipelex.config",
+ "description": "The runtime's own configuration."
+ },
+ {
+ "family": "pipelex.plugin",
+ "description": "The plugins installed in the runtime."
+ },
+ {
+ "family": "pipelex.deployment",
+ "description": "The policies of a runner deployment."
+ },
+ {
+ "family": "pipelex.docgen",
+ "description": "The document engines that print a PipeDocGen step's documents."
+ },
+ {
+ "family": "pipelex.sandbox",
+ "description": "The Daytona sandbox that runs a method's own code."
+ },
+ {
+ "family": "pipelex.codegen",
+ "description": "Code generated from a method."
+ },
+ {
+ "family": "pipelex.connector",
+ "description": "The toolsets a method's connectors offer a model."
+ },
+ {
+ "family": "pipelex.erasure",
+ "description": "The erasure of runs and methods."
+ },
+ {
+ "family": "pipelex.webhook",
+ "description": "The webhooks a caller registers to hear about its runs."
+ }
+ ],
+ "codes": [
+ {
+ "code": "pipelex.billing.plan_limit",
+ "title": "The account's plan does not allow this",
+ "domain": "account",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The account's plan allows at most {value} for '{limit}', and the account already holds that many.",
+ "steps": {
+ "actor": {
+ "kind": "check_account",
+ "detail": "Check the account's plan, then free some of '{limit}' or move to a plan that allows more."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the account's owner to move to a plan that allows more than {value} for '{limit}'."
+ }
+ },
+ "params": {
+ "limit": {
+ "type": "identifier",
+ "description": "What the plan caps, such as the account's API keys."
+ },
+ "value": {
+ "type": "integer",
+ "description": "The most the account's plan allows."
+ }
+ },
+ "meaning": "The account's plan caps a resource, such as its API keys, and the account already holds as many as the plan allows.",
+ "what_to_do": "Remove something the limit counts, such as an API key no longer in use, or move the account to a plan with a higher limit."
+ },
+ {
+ "code": "pipelex.billing.credit_exhausted",
+ "title": "The organization is out of credit",
+ "domain": "account",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 402,
+ "detail": "The organization has no credit left, so the operation was refused.",
+ "steps": {
+ "actor": {
+ "kind": "check_account",
+ "detail": "Add credit to the organization, or move it to a plan that includes more, then try again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the account's owner to add credit to the organization."
+ }
+ },
+ "params": {},
+ "meaning": "The organization's credit is spent. The platform refuses a run before queueing it, and a model call made once the credit has run out is refused as well.",
+ "what_to_do": "Add credit to the organization, or move it to a plan that includes more, then start the run again."
+ },
+ {
+ "code": "pipelex.billing.subscription_conflict",
+ "title": "The subscription's state does not allow this",
+ "domain": "account",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "This billing action is not possible while the organization's subscription is '{subscription}'.",
+ "steps": {
+ "actor": {
+ "kind": "check_account",
+ "detail": "Check the organization's subscription, then take the billing action its state allows."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the account's owner to check the organization's subscription."
+ }
+ },
+ "params": {
+ "subscription": {
+ "type": "enum",
+ "values": [
+ "none",
+ "active"
+ ],
+ "description": "The organization's subscription: it has none, or it has an active one."
+ }
+ },
+ "meaning": "A billing action needs an active subscription and the organization has none, or forbids one and the organization already has one.",
+ "what_to_do": "Read the organization's subscription in its billing settings, then subscribe first, or manage the subscription it already has."
+ },
+ {
+ "code": "pipelex.billing.plan_refused",
+ "title": "The plan's rules refuse this change",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The rules of the organization's plan refuse this change (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Request a change the organization's plan allows, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose plan change the plan's rules refuse."
+ }
+ },
+ "params": {
+ "reason": {
+ "type": "enum",
+ "values": [
+ "enterprise_is_paid_only",
+ "plan_not_editable",
+ "plan_not_enterprise"
+ ],
+ "description": "Why the change is refused: an enterprise plan is only ever paid, the plan cannot be edited, or the change applies only to an enterprise plan and this one is not."
+ }
+ },
+ "meaning": "An administrator's change to an organization's plan that the plan's kind does not allow.",
+ "what_to_do": "Read `params.reason`, then choose another plan, or make the change on a plan that allows it."
+ },
+ {
+ "code": "pipelex.org.required",
+ "title": "An organization is required",
+ "domain": "account",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 403,
+ "detail": "This operation acts on an organization, and the request acts for none.",
+ "steps": {
+ "actor": {
+ "kind": "check_account",
+ "detail": "Act for an organization, by joining or creating one, then send the request again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the account's owner to add you to an organization."
+ }
+ },
+ "params": {},
+ "meaning": "The caller acts for no organization, and the route acts on an organization's resources.",
+ "what_to_do": "Sign in to an organization, or use an API key that belongs to one, then send the request again."
+ },
+ {
+ "code": "pipelex.org.mismatch",
+ "title": "The reference belongs to another organization",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 403,
+ "detail": "The request's {reference} belongs to an organization other than the caller's.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Use a {reference} of the organization the request acts for, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose {reference} belongs to another organization."
+ }
+ },
+ "params": {
+ "reference": {
+ "type": "enum",
+ "values": [
+ "organization_id",
+ "storage_uri"
+ ],
+ "description": "The kind of reference that names another organization: an organization's id or a storage address."
+ }
+ },
+ "meaning": "A well-formed reference names an organization other than the one the caller acts for.",
+ "what_to_do": "Check which organization the request acts for, and use a reference that belongs to it."
+ },
+ {
+ "code": "pipelex.org.not_found",
+ "title": "The organization's resource does not exist",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 404,
+ "detail": "The {resource} the request names does not exist.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Name a {resource} that exists, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose request names a {resource} that does not exist."
+ }
+ },
+ "params": {
+ "resource": {
+ "type": "enum",
+ "values": [
+ "organization",
+ "member",
+ "invitation",
+ "api_key",
+ "user",
+ "promo_code",
+ "promo_redemption",
+ "flag_target"
+ ],
+ "description": "The kind of resource the request names."
+ }
+ },
+ "meaning": "The organization, member, invitation, API key, user or promo record the request names does not exist.",
+ "what_to_do": "Check the identifier the request gives, and list what the organization holds to find the right one."
+ },
+ {
+ "code": "pipelex.org.not_manageable",
+ "title": "The resource cannot be changed this way in its state",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The resource cannot be changed this way in its current state (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Change the resource another way, or bring it into a state that allows this change first."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose change the resource's state does not allow."
+ }
+ },
+ "params": {
+ "reason": {
+ "type": "identifier",
+ "description": "What about the resource's state refuses the change."
+ }
+ },
+ "meaning": "The resource's state refuses the change: a personal or an internal organization, the last administrator of an organization, a subject with no directory identity, or a promo code's cap set below the redemptions it already has.",
+ "what_to_do": "Read `params.reason`, then change the request, for instance by naming another administrator before removing the last one."
+ },
+ {
+ "code": "pipelex.org.already_exists",
+ "title": "The organization's resource already exists",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The {resource} the request would create already exists.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Use the {resource} that exists, or choose another, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose {resource} already exists."
+ }
+ },
+ "params": {
+ "resource": {
+ "type": "enum",
+ "values": [
+ "member",
+ "invitation",
+ "promo_code",
+ "api_key_label"
+ ],
+ "description": "The kind of resource that already exists."
+ }
+ },
+ "meaning": "A member, an invitation, a promo code and an API key's name are each unique, and the one the request gives is taken.",
+ "what_to_do": "Use the one that exists, or choose another name, code or address."
+ },
+ {
+ "code": "pipelex.org.promo_invalid",
+ "title": "The promo code cannot be redeemed",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The promo code cannot be redeemed.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Check the promo code, then redeem one that is valid."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose promo code cannot be redeemed."
+ }
+ },
+ "params": {},
+ "meaning": "The promo code is not one this organization can redeem. The reason is withheld on purpose, so that a code cannot be guessed by trying.",
+ "what_to_do": "Check the promo code as it was given to you, and ask whoever gave it for one that is valid."
+ },
+ {
+ "code": "pipelex.org.promo_credit_pending",
+ "title": "The promo credit is pending",
+ "domain": "runtime",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 502,
+ "detail": "The promo code was redeemed, and its credit has not been applied yet.",
+ "steps": {
+ "actor": {
+ "kind": "wait",
+ "detail": "Wait for the credit to reach the organization, without redeeming the code again."
+ },
+ "other": {
+ "kind": "wait",
+ "detail": "Wait for the credit to reach the organization, without redeeming the code again."
+ }
+ },
+ "params": {},
+ "meaning": "The redemption is recorded, but applying its credit failed. A repair sweep applies it later, so redeeming the code again is neither needed nor possible.",
+ "what_to_do": "Wait, then check the organization's credit. If the credit has not arrived after a day, report it to whoever runs the runtime."
+ },
+ {
+ "code": "pipelex.catalog.not_found",
+ "title": "The saved method does not exist",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 404,
+ "detail": "The organization's catalog holds no {resource} matching the request for the method '{method_id}'.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "List the organization's catalog to find the {resource}, then send the request again with one that exists."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose request names a {resource} the catalog does not hold."
+ }
+ },
+ "params": {
+ "resource": {
+ "type": "enum",
+ "values": [
+ "method",
+ "version",
+ "example"
+ ],
+ "description": "What the request names: a saved method, one of its versions, or one of its examples."
+ },
+ "method_id": {
+ "type": "identifier",
+ "description": "The catalog id of the method the request names."
+ },
+ "version": {
+ "type": "integer",
+ "optional": true,
+ "description": "The version the request names, when what it names is a version."
+ }
+ },
+ "meaning": "No saved method, version or example matches the request in the catalog of the organization the request acts for.",
+ "what_to_do": "List the catalog's methods and their versions, and use an identifier that exists. A catalog id is read in the organization the request acts for, so check that it is the right one."
+ },
+ {
+ "code": "pipelex.catalog.not_published",
+ "title": "The saved method has no published version",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The method '{method_id}' has no published version.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Publish a version of the method '{method_id}', or name its draft as '{method_id}@draft', then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who names the latest published version of the method '{method_id}', which has none."
+ }
+ },
+ "params": {
+ "method_id": {
+ "type": "identifier",
+ "description": "The catalog id of the method."
+ }
+ },
+ "meaning": "A bare catalog id names the method's latest published version, and the method has only a draft.",
+ "what_to_do": "Publish the method, or name its draft with the `@draft` suffix."
+ },
+ {
+ "code": "pipelex.catalog.being_deleted",
+ "title": "The saved method is being deleted",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The method '{method_id}' is being deleted.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Use another method, since the method '{method_id}' is being deleted."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose request names the method '{method_id}', which is being deleted."
+ }
+ },
+ "params": {
+ "method_id": {
+ "type": "identifier",
+ "description": "The catalog id of the method."
+ }
+ },
+ "meaning": "The method's deletion is in flight, so it can no longer be run, changed or published.",
+ "what_to_do": "Use another method, or save the method again under a new id if it is still wanted."
+ },
+ {
+ "code": "pipelex.catalog.deletion_failed",
+ "title": "The saved method's deletion failed",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 503,
+ "detail": "The deletion of the method '{method_id}' did not complete.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Delete the method '{method_id}' again."
+ },
+ "other": {
+ "kind": "retry",
+ "detail": "Delete the method '{method_id}' again."
+ }
+ },
+ "params": {
+ "method_id": {
+ "type": "identifier",
+ "description": "The catalog id of the method."
+ }
+ },
+ "meaning": "A step of the method's deletion failed. Deleting the method again resumes its deletion.",
+ "what_to_do": "Send the delete again. If it keeps failing, report it to whoever runs the runtime."
+ },
+ {
+ "code": "pipelex.catalog.update_conflict",
+ "title": "The saved method changed since it was read",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The method '{method_id}' changed after it was read, so the update was not applied.",
+ "steps": {
+ "actor": {
+ "kind": "refresh",
+ "detail": "Read the method '{method_id}' again, then apply the change to its current content."
+ },
+ "other": {
+ "kind": "refresh",
+ "detail": "Read the method '{method_id}' again, then apply the change to its current content."
+ }
+ },
+ "params": {
+ "method_id": {
+ "type": "identifier",
+ "description": "The catalog id of the method."
+ }
+ },
+ "meaning": "Another write changed the method or its draft between the read the update started from and the update itself, so the update stopped rather than overwrite that change.",
+ "what_to_do": "Read the method again, apply the change to what it holds now, and send the update again."
+ },
+ {
+ "code": "pipelex.catalog.selector_invalid",
+ "title": "The catalog selector is malformed",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The catalog selector cannot be parsed (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Write the selector as a catalog id, alone or followed by '@' and a version number or 'draft', then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose catalog selector cannot be parsed."
+ }
+ },
+ "params": {
+ "reason": {
+ "type": "enum",
+ "values": [
+ "malformed_method_id",
+ "malformed_version_suffix",
+ "suffix_on_linkage"
+ ],
+ "description": "What is wrong: the catalog id itself, the suffix after its '@', or a suffix where the request runs the source it sends and names no version."
+ }
+ },
+ "meaning": "A method selector names a saved method by its catalog id, `mt_` and its characters, and may add `@3` for one version or `@draft` for the draft. This one breaks that grammar.",
+ "what_to_do": "Read `params.reason`, then correct the selector: a catalog id as the catalog returned it, with a version number that has no leading zero or the word `draft` after the `@`."
+ },
+ {
+ "code": "pipelex.catalog.link_conflict",
+ "title": "The directory is linked to another method",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "client",
+ "detail": "The method link of the directory '{path}' stops this save to the method '{method_id}'.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Save the directory to the method its link names, or save these files from a directory of their own."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose directory '{path}' is linked in a way that stops this save."
+ }
+ },
+ "params": {
+ "method_id": {
+ "type": "identifier",
+ "description": "The catalog id of the method the save targets."
+ },
+ "path": {
+ "type": "caller_text",
+ "description": "The local directory whose link stops the save."
+ }
+ },
+ "meaning": "A local directory records, in its method link, which saved method its files belong to. The link names another method than the one the save targets, cannot be read, or records a sync that did not finish, so the client refuses to save over a draft that is not this directory's.",
+ "what_to_do": "Check which method the directory is linked to, then save to that method or move the files to a directory of their own. Repair or remove a link that cannot be read."
+ },
+ {
+ "code": "pipelex.run.already_exists",
+ "title": "A run with this id already exists",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "A run with the id '{pipeline_run_id}' already exists.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Start the run with another id, or with none so that the runner assigns one."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who chose the run id '{pipeline_run_id}', which is already taken."
+ }
+ },
+ "params": {
+ "pipeline_run_id": {
+ "type": "identifier",
+ "description": "The run id the caller chose."
+ }
+ },
+ "meaning": "The caller chose the run's id, which Pipelex allows as an extension of the protocol, whose run id is always the runner's, and a run already holds that id.",
+ "what_to_do": "Start the run with a new id, or with none so that the runner assigns it. To see the run that holds the id, read it by that id."
+ },
+ {
+ "code": "pipelex.storage.uri_invalid",
+ "title": "The storage address is malformed",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "A storage address in the request cannot be parsed.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Send the storage address exactly as storage returned it, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose request holds a storage address that cannot be parsed."
+ }
+ },
+ "params": {},
+ "meaning": "A `pipelex-storage://` address does not parse, or the storage provider refuses it as a key.",
+ "what_to_do": "Use the storage address exactly as an upload or a run's results returned it, without editing it.",
+ "see": [
+ {
+ "title": "Cloud Storage",
+ "href": "features/cloud-storage.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.storage.not_found",
+ "title": "A stored file is gone",
+ "domain": "runtime",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "A file the runtime stored is no longer in its {scheme} storage.",
+ "steps": {
+ "actor": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "scheme": {
+ "type": "enum",
+ "values": [
+ "local",
+ "s3",
+ "gcs",
+ "memory"
+ ],
+ "description": "The kind of storage that no longer holds the file."
+ }
+ },
+ "meaning": "A file the run wrote, or that the runtime handed out, is no longer in storage. A caller's own reference to something that does not exist is `input.reference_not_found` instead.",
+ "what_to_do": "Report the problem to whoever runs the runtime, with the run's `pipeline_run_id` when it has one."
+ },
+ {
+ "code": "pipelex.storage.unavailable",
+ "title": "Storage is unavailable",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 503,
+ "detail": "The {scheme} storage failed a read or a write.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Send the request again after a while."
+ },
+ "other": {
+ "kind": "wait",
+ "detail": "Wait, then send the request again."
+ }
+ },
+ "params": {
+ "scheme": {
+ "type": "enum",
+ "values": [
+ "local",
+ "s3",
+ "gcs",
+ "memory"
+ ],
+ "description": "The kind of storage that failed."
+ }
+ },
+ "meaning": "The storage backend failed a read or a write, which may succeed later.",
+ "what_to_do": "Send the request again after `retry_after` seconds when the problem gives it. If storage keeps failing, report it to whoever runs the runtime."
+ },
+ {
+ "code": "pipelex.storage.not_configured",
+ "title": "This deployment serves no storage for that address",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "This deployment serves no storage for the scheme '{scheme}'.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Configure a storage for the scheme '{scheme}' on this deployment, then restart the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "scheme": {
+ "type": "identifier",
+ "description": "The scheme of the storage address."
+ }
+ },
+ "meaning": "A storage address names a scheme for which this deployment configures no bucket.",
+ "what_to_do": "If you run the runtime, configure the storage for the scheme. Otherwise, report the problem to whoever runs it.",
+ "see": [
+ {
+ "title": "Storage Provider Plugins",
+ "href": "under-the-hood/storage-provider-plugins.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.storage.grant_unusable",
+ "title": "The upload grant is spent or expired",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 403,
+ "detail": "The upload grant has expired, or has already written its file.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Ask for a new upload grant, then upload the file with it."
+ },
+ "other": {
+ "kind": "retry",
+ "detail": "Ask for a new upload grant, then upload the file with it."
+ }
+ },
+ "params": {},
+ "meaning": "An upload grant writes one file, once, before it expires. This one has expired or has already written its file, and a new grant succeeds.",
+ "what_to_do": "Request a new upload grant, and upload the file with it."
+ },
+ {
+ "code": "pipelex.storage.grant_mismatch",
+ "title": "The upload differs from its grant",
+ "domain": "runtime",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 403,
+ "detail": "The upload differs from what its grant signed, so storage refused it.",
+ "steps": {
+ "actor": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {},
+ "meaning": "The upload's size, type, metadata or headers differ from what the grant signed. A client that uploads with the grant exactly as it was handed out never meets this.",
+ "what_to_do": "Report the problem to whoever runs the runtime. If you wrote the client that uploads, send the headers the grant lists, unchanged."
+ },
+ {
+ "code": "pipelex.storage.upload_refused",
+ "title": "Storage refused the upload",
+ "domain": "runtime",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 403,
+ "detail": "Storage refused the upload with the status {status}.",
+ "steps": {
+ "actor": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "status": {
+ "type": "integer",
+ "description": "The HTTP status storage answered the upload with."
+ }
+ },
+ "meaning": "Storage refused an upload for a reason it does not name.",
+ "what_to_do": "Report the problem to whoever runs the runtime, with the status storage answered."
+ },
+ {
+ "code": "pipelex.security.reserved_key",
+ "title": "The request carries a reserved key",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The request carries object keys that Pipelex's decoder reserves for its own markers.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Rename or remove the reserved keys in the request, then send it again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose request carries reserved keys."
+ }
+ },
+ "params": {
+ "keys": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The reserved keys the request carries."
+ }
+ },
+ "meaning": "An object in the request holds a key that Pipelex's decoder would read as a class marker, such as `__class__`, `__module__` or a key starting with `__kajson`. The request is refused, and the refusal is recorded as a security event.",
+ "what_to_do": "Rename or remove each key `params.keys` lists. No input of a method needs one."
+ },
+ {
+ "code": "pipelex.security.result_outside_scope",
+ "title": "A result location lies outside the run",
+ "domain": "runtime",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "A result location lies outside the run's storage scope, so the runtime refused it.",
+ "steps": {
+ "actor": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {},
+ "meaning": "A result location that a step reported, or that storage holds, lies outside the run's own storage scope. The runtime refuses it, and records the refusal as a security event.",
+ "what_to_do": "Report the problem to whoever runs the runtime, with the run's `pipeline_run_id`."
+ },
+ {
+ "code": "pipelex.config.invalid",
+ "title": "The runtime's configuration is invalid",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "The runtime's configuration is invalid, so it cannot serve this request.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Correct the setting '{setting}' in the file '{file}' of the {surface} configuration, then restart the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "surface": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The part of the configuration at fault, such as the backends, the model deck, the routing, the plugins, the storage, the telemetry, the log sinks, the libraries or the API server's settings."
+ },
+ "file": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The configuration file that holds the setting."
+ },
+ "setting": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The setting that does not validate."
+ }
+ },
+ "meaning": "A configuration file or setting parsed, but does not validate.",
+ "what_to_do": "If you run the runtime, read its logs for the file and the setting, and correct them; `pipelex doctor` checks the configuration. Otherwise, report the problem to whoever runs it.",
+ "see": [
+ {
+ "title": "Configuration",
+ "href": "configuration/index.md"
+ },
+ {
+ "title": "Doctor Command",
+ "href": "tools/cli/doctor.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.config.syntax",
+ "title": "A configuration file does not parse",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "A configuration file of the runtime does not parse.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Fix the TOML of the file '{file}' of the {surface} configuration at line {line}, column {column}, then restart the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "surface": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The part of the configuration the file belongs to."
+ },
+ "file": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The file that does not parse."
+ },
+ "line": {
+ "type": "integer",
+ "operator_only": true,
+ "description": "The line of the first fault."
+ },
+ "column": {
+ "type": "integer",
+ "operator_only": true,
+ "description": "The column of the first fault."
+ }
+ },
+ "meaning": "A configuration file is not valid TOML.",
+ "what_to_do": "If you run the runtime, open the file its logs name at the line and column given, and fix the syntax. Otherwise, report the problem to whoever runs it.",
+ "see": [
+ {
+ "title": "Configuration",
+ "href": "configuration/index.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.config.file_missing",
+ "title": "A configuration file is missing",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "A configuration file the runtime needs is missing.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Create or restore the file '{file}' of the {surface} configuration, then restart the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "surface": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The part of the configuration the file belongs to."
+ },
+ "file": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The file that is missing."
+ }
+ },
+ "meaning": "A configuration file, or a key file, that the runtime needs is absent or cannot be loaded.",
+ "what_to_do": "If you run the runtime, restore the file its logs name, or write the default configuration with `pipelex init`. Otherwise, report the problem to whoever runs it.",
+ "see": [
+ {
+ "title": "Init Commands",
+ "href": "tools/cli/init.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.config.variable_missing",
+ "title": "A configuration variable is not set",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "A variable the runtime's configuration refers to is not set.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Set the {source} variable '{variable}', then restart the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "variable": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The variable that is not set."
+ },
+ "source": {
+ "type": "enum",
+ "values": [
+ "env",
+ "secret"
+ ],
+ "operator_only": true,
+ "description": "Where the configuration reads the variable from: the environment or a secret."
+ }
+ },
+ "meaning": "An environment variable or a secret that the configuration refers to did not resolve.",
+ "what_to_do": "If you run the runtime, set the variable in its environment or in its secrets provider. Otherwise, report the problem to whoever runs it.",
+ "see": [
+ {
+ "title": "Secrets Provider Plugins",
+ "href": "under-the-hood/secrets-provider-plugins.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.config.credential_missing",
+ "title": "An inference backend has no credential",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "An inference backend of the runtime has no credential.",
+ "steps": {
+ "actor": {
+ "kind": "check_credentials",
+ "detail": "Set the credential '{variable}' of the backend '{backend}', then restart the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "backend": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The inference backend that lacks its credential."
+ },
+ "variable": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The variable or the file that should hold the credential."
+ }
+ },
+ "meaning": "A key or a credential file that an inference backend needs is absent.",
+ "what_to_do": "If you run the runtime, set the backend's key in its environment or its secrets, or disable the backend. Otherwise, report the problem to whoever runs it.",
+ "see": [
+ {
+ "title": "Inference Backend Plugins",
+ "href": "under-the-hood/inference-backend-plugins.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.config.credential_refused",
+ "title": "A service refused the configured credential",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "A service the runtime depends on refused the credential it is configured with.",
+ "steps": {
+ "actor": {
+ "kind": "check_credentials",
+ "detail": "Check the credential the {surface} configuration holds for the service '{service}'."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "surface": {
+ "type": "enum",
+ "values": [
+ "log_sink",
+ "storage"
+ ],
+ "operator_only": true,
+ "description": "The part of the configuration that holds the credential."
+ },
+ "service": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The service that refused it."
+ }
+ },
+ "meaning": "A service that is not an inference provider, such as a log sink or a storage, refused the deployment's credential. An inference provider refusing its key is `provider.credential_refused` instead.",
+ "what_to_do": "If you run the runtime, renew or correct the credential. Otherwise, report the problem to whoever runs it."
+ },
+ {
+ "code": "pipelex.config.dependency_missing",
+ "title": "An optional dependency is not installed",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "An optional dependency that the runtime's configuration needs is not installed.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Install '{dependency}', which the extra '{extra}' provides, then restart the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "dependency": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The package, the SDK or the program that is missing."
+ },
+ "extra": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The Pipelex extra that provides it."
+ }
+ },
+ "meaning": "A Python extra, an SDK or a program such as `plxt` that the configuration needs is not installed.",
+ "what_to_do": "If you run the runtime, install Pipelex with the extra its logs name. Otherwise, report the problem to whoever runs it."
+ },
+ {
+ "code": "pipelex.plugin.not_found",
+ "title": "No plugin provides the configured choice",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "No installed plugin provides a choice the runtime's configuration makes.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Install a plugin that provides '{value}' for the setting '{setting}', or choose a value an installed plugin provides."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "setting": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The setting that makes the choice."
+ },
+ "value": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The choice no installed plugin provides."
+ },
+ "available": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "operator_only": true,
+ "description": "The choices the installed plugins provide."
+ }
+ },
+ "meaning": "A setting names a storage, a secrets provider, a log sink, an execution mode, an orchestrator or a validator that no installed plugin registers.",
+ "what_to_do": "If you run the runtime, install the plugin that provides the choice, or choose one of those its logs list as available. Otherwise, report the problem to whoever runs it.",
+ "see": [
+ {
+ "title": "Inference Backend Plugins",
+ "href": "under-the-hood/inference-backend-plugins.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.plugin.broken",
+ "title": "A plugin failed to load",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "An installed plugin failed to load.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Fix or uninstall the plugin '{plugin}' ({reason}), then restart the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "plugin": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The plugin that failed."
+ },
+ "reason": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "What failed: its loading, its registration, or a rule its package breaks."
+ }
+ },
+ "meaning": "An installed plugin raised while it was loading or registering, or breaks the rules a plugin's package follows.",
+ "what_to_do": "If you run the runtime, read its logs for the plugin, then upgrade, fix or uninstall it. Otherwise, report the problem to whoever runs it.",
+ "see": [
+ {
+ "title": "Inference Backend Plugins",
+ "href": "under-the-hood/inference-backend-plugins.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.plugin.conflict",
+ "title": "Two plugins claim the same slot",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "Two installed plugins claim the same slot.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Uninstall '{plugin}' or '{other_plugin}', which both claim '{slot}', then restart the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "plugin": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "One of the two plugins."
+ },
+ "other_plugin": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The other plugin."
+ },
+ "slot": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The name or the process-wide slot both claim."
+ }
+ },
+ "meaning": "Two installed plugins register the same name, or claim the same process-wide slot.",
+ "what_to_do": "If you run the runtime, keep only one of the two plugins. Otherwise, report the problem to whoever runs it.",
+ "see": [
+ {
+ "title": "Inference Backend Plugins",
+ "href": "under-the-hood/inference-backend-plugins.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.plugin.api_mismatch",
+ "title": "A plugin targets another plugin API",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "An installed plugin targets a plugin API this runtime does not support.",
+ "steps": {
+ "actor": {
+ "kind": "upgrade",
+ "detail": "Upgrade the plugin '{plugin}', built for the plugin API {targets_api}, or Pipelex, which supports the plugin API {supported_api}."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "plugin": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The plugin."
+ },
+ "targets_api": {
+ "type": "integer",
+ "operator_only": true,
+ "description": "The plugin API version the plugin was built for."
+ },
+ "supported_api": {
+ "type": "integer",
+ "operator_only": true,
+ "description": "The plugin API version this runtime supports."
+ }
+ },
+ "meaning": "An installed plugin was built for another version of the plugin contract than the one this runtime implements.",
+ "what_to_do": "If you run the runtime, upgrade the plugin or Pipelex so that both target the same plugin API. Otherwise, report the problem to whoever runs it.",
+ "see": [
+ {
+ "title": "Inference Backend Plugins",
+ "href": "under-the-hood/inference-backend-plugins.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.deployment.orchestration_override_forbidden",
+ "title": "This deployment does not allow choosing the orchestration mode",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "This deployment does not let a request choose its orchestration mode, and this one asks for '{requested_mode}'.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Send the request without choosing an orchestration mode."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose request chooses an orchestration mode this deployment fixes."
+ }
+ },
+ "params": {
+ "requested_mode": {
+ "type": "identifier",
+ "description": "The orchestration mode the request asks for."
+ }
+ },
+ "meaning": "The deployment's policy fixes the orchestration mode, so a request may not choose one.",
+ "what_to_do": "Leave the orchestration mode out of the request, and let the deployment run it in its own mode.",
+ "see": [
+ {
+ "title": "Orchestrator Plugins",
+ "href": "under-the-hood/orchestrator-plugins.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.deployment.custom_code_requires_sandbox",
+ "title": "Custom code needs a sandbox-hosted deployment",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 501,
+ "detail": "The method ships Python code in its {origin}, and this deployment runs none outside the Daytona sandbox.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Configure the Daytona sandbox on this deployment, so that it can run the method's own code."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "origin": {
+ "type": "enum",
+ "values": [
+ "bundle",
+ "package"
+ ],
+ "description": "Where the method ships its code: in its bundle or in its package."
+ }
+ },
+ "meaning": "The method ships Python code of its own, and this deployment runs a method's own code only inside the Daytona sandbox, which it does not have.",
+ "what_to_do": "If you run the runtime, configure the Daytona sandbox for custom code. Otherwise, run the method on a runtime that allows its code, or ask its owner for a version without Python.",
+ "see": [
+ {
+ "title": "PipeFunc Requirements",
+ "href": "under-the-hood/pipe-func-requirements.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.deployment.python_structures_refused",
+ "title": "Python structure classes are not allowed here",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The method declares structures as Python classes, which this runner does not import.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Declare the structures as concepts in the method in place of Python classes, then run it again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to declare its structures as concepts in the method."
+ }
+ },
+ "params": {
+ "files": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The method's files that declare structures as Python classes."
+ }
+ },
+ "meaning": "The method declares its structures as Python classes, which no hosted runner imports. Concepts declared in the method itself replace them.",
+ "what_to_do": "Rewrite each structure the files in `params.files` declare as a concept with its fields in the method, then run it again.",
+ "see": [
+ {
+ "title": "Python StructuredContent Classes",
+ "href": "building-methods/concepts/python-classes.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.deployment.token_claims_invalid",
+ "title": "The token's claims cannot be used",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "The request's verified token carries claims this runner cannot use.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Correct the claim '{claim}' ({reason}) that the token issuer writes, then send the request again."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "claim": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The claim at fault."
+ },
+ "reason": {
+ "type": "enum",
+ "values": [
+ "missing",
+ "unsafe",
+ "reserved"
+ ],
+ "operator_only": true,
+ "description": "What is wrong with the claim: it is missing, unsafe as an identifier, or reserved."
+ }
+ },
+ "meaning": "A verified token carries a user id the runner cannot use, so the token's issuer is misconfigured.",
+ "what_to_do": "If you run the runtime, correct the claims its token issuer writes. Otherwise, report the problem to whoever runs it.",
+ "see": [
+ {
+ "title": "API Server Configuration",
+ "href": "api-server/configuration.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.docgen.engine_unavailable",
+ "title": "No document engine prints this here",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 501,
+ "detail": "No document engine prints the format '{format}' in this runtime.",
+ "steps": {
+ "actor": {
+ "kind": "fix_configuration",
+ "detail": "Install or enable the engine '{engine}' ({gap}), then restart the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "engine": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "The document engine the step needs."
+ },
+ "format": {
+ "type": "enum",
+ "values": [
+ "pdf",
+ "xlsx",
+ "docx",
+ "pptx"
+ ],
+ "description": "The format the step prints."
+ },
+ "gap": {
+ "type": "identifier",
+ "operator_only": true,
+ "description": "What is missing: the engine, a system library it needs, its declaration or its enablement."
+ }
+ },
+ "meaning": "The engine that prints a PipeDocGen step's format, or a system library it needs, is not installed, declared or enabled in this runtime.",
+ "what_to_do": "If you run the runtime, install and enable the engine. Otherwise, report the problem to whoever runs it.",
+ "see": [
+ {
+ "title": "Document Engine Plugins",
+ "href": "under-the-hood/document-engine-plugins.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.docgen.template_invalid",
+ "title": "The document template cannot be used",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The document template '{template}' cannot be used (reason: {reason}): {finding}",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Fix the template '{template}', then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to fix the template '{template}'."
+ }
+ },
+ "params": {
+ "template": {
+ "type": "identifier",
+ "description": "The template."
+ },
+ "reason": {
+ "type": "enum",
+ "values": [
+ "unreadable",
+ "does_not_fit",
+ "check_failed",
+ "value_unsupported"
+ ],
+ "description": "Why it cannot be used: it is not a readable file of its format, it does not fit the step's inputs, it fails the engine's check, or it maps a value no cell can take."
+ },
+ "finding": {
+ "type": "caller_text",
+ "description": "What the engine found, about the method's own template."
+ }
+ },
+ "meaning": "A PipeDocGen step's template cannot be used to print its document.",
+ "what_to_do": "Read `params.finding`, then fix the template, or the inputs the step maps into it.",
+ "see": [
+ {
+ "title": "Document Engine Plugins",
+ "href": "under-the-hood/document-engine-plugins.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.docgen.resource_refused",
+ "title": "The document names a file it may not read",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The document names a file the print engine may not read (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Name the file by an absolute https URL or embed it, then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to fix the file its document names."
+ }
+ },
+ "params": {
+ "reason": {
+ "type": "enum",
+ "values": [
+ "relative_url",
+ "plain_http_url",
+ "undecodable_data_url",
+ "unknown_font"
+ ],
+ "description": "Why the file was refused: a relative URL, a plain http URL, a data URL that does not decode, or a font the engine does not know."
+ }
+ },
+ "meaning": "The print engine's fetcher refused a resource the document names, by policy. A plain `http://` URL breaks a transport rule rather than a security one, so its refusal records no security event.",
+ "what_to_do": "Use an absolute `https://` URL, embed the file as a data URL that decodes, or use a font the engine provides.",
+ "see": [
+ {
+ "title": "Document Engine Plugins",
+ "href": "under-the-hood/document-engine-plugins.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.docgen.content_unprintable",
+ "title": "The document's content cannot be printed",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The run's data holds something the print engine cannot lay out (reason: {reason}, in '{element}').",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Change the input that fills '{element}', then run the method again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose inputs hold something the document cannot print."
+ }
+ },
+ "params": {
+ "reason": {
+ "type": "enum",
+ "values": [
+ "too_tall_for_page",
+ "image_unreadable",
+ "image_too_large",
+ "image_empty",
+ "html_too_large"
+ ],
+ "description": "What cannot be printed: an element taller than a page, an image that cannot be read, is too large or is empty, or HTML past its size limit."
+ },
+ "element": {
+ "type": "identifier",
+ "description": "The element of the document that holds it."
+ }
+ },
+ "meaning": "The run's data holds something the print engine cannot lay out or decode.",
+ "what_to_do": "Read `params.reason`, then shorten, resize or replace the content, and run the method again."
+ },
+ {
+ "code": "pipelex.docgen.print_timeout",
+ "title": "Printing the document took too long",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 504,
+ "detail": "Printing the document ran past its limit of {limit} seconds and was stopped.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Run the method again, since the print may finish within its limit."
+ },
+ "other": {
+ "kind": "retry",
+ "detail": "Run the method again, since the print may finish within its limit."
+ }
+ },
+ "params": {
+ "limit": {
+ "type": "seconds",
+ "description": "The time the print was allowed."
+ }
+ },
+ "meaning": "The print, or a resource it read, ran past its limit and was stopped.",
+ "what_to_do": "Run the method again. If the print keeps running past its limit, make the document lighter, or report it to whoever runs the runtime."
+ },
+ {
+ "code": "pipelex.docgen.template_warning",
+ "title": "The document template may be faulty",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "warning",
+ "detail": "The document template '{template}' may be faulty: {finding}",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Check the template '{template}', and fix it if the finding is right."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to check the template '{template}'."
+ }
+ },
+ "params": {
+ "template": {
+ "type": "identifier",
+ "description": "The template."
+ },
+ "finding": {
+ "type": "caller_text",
+ "description": "What the check found, about the method's own template."
+ }
+ },
+ "meaning": "An advisory: the check of a PipeDocGen step's template found a likely fault, which does not stop the method from validating.",
+ "what_to_do": "Read `params.finding`, check the template, and fix it if the finding is right.",
+ "see": [
+ {
+ "title": "Document Engine Plugins",
+ "href": "under-the-hood/document-engine-plugins.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.sandbox.unavailable",
+ "title": "The Daytona sandbox could not be started",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 503,
+ "detail": "The Daytona sandbox that runs the method's code could not be started (backend: {backend}), so the code never ran.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Run the method again after a while."
+ },
+ "other": {
+ "kind": "retry",
+ "detail": "Run the method again after a while."
+ }
+ },
+ "params": {
+ "backend": {
+ "type": "enum",
+ "values": [
+ "daytona",
+ "subprocess"
+ ],
+ "description": "What could not be started: a Daytona sandbox, or the local subprocess that stands in for it."
+ }
+ },
+ "meaning": "A Daytona sandbox, or the local subprocess that stands in for it, could not be provisioned or reached. The method's own code never ran, so running the method again is safe.",
+ "what_to_do": "Run the method again after a while. If the Daytona sandbox keeps failing, report it to whoever runs the runtime.",
+ "see": [
+ {
+ "title": "PipeFunc Requirements",
+ "href": "under-the-hood/pipe-func-requirements.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.codegen.output_conflict",
+ "title": "Codegen will not write there",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "Codegen will not write to '{path}' (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Generate into a directory codegen owns, or move what sits at '{path}' out of the way."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose codegen target '{path}' holds something codegen will not overwrite."
+ }
+ },
+ "params": {
+ "path": {
+ "type": "identifier",
+ "description": "The path codegen would write."
+ },
+ "reason": {
+ "type": "enum",
+ "values": [
+ "unowned_file",
+ "escapes_root",
+ "not_a_file",
+ "symlink"
+ ],
+ "description": "Why codegen will not write there: a file it does not own sits there, the path lies outside the output root, is not a file, or is a symbolic link."
+ }
+ },
+ "meaning": "A file codegen does not own sits at the target, or the target lies outside the output root, is not a file, or is a symbolic link.",
+ "what_to_do": "Point codegen at a directory of its own, or remove what sits at the path, then generate again.",
+ "see": [
+ {
+ "title": "Codegen Projections",
+ "href": "under-the-hood/codegen-projections.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.codegen.lock_invalid",
+ "title": "The codegen lock is unreadable",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The codegen lock '{file}' cannot be read.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Restore the lock '{file}' from version control, or generate the code again to rewrite it."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose codegen lock '{file}' cannot be read."
+ }
+ },
+ "params": {
+ "file": {
+ "type": "identifier",
+ "description": "The lock file."
+ }
+ },
+ "meaning": "The `codegen.lock` file is malformed, or records a tree that is not safe to write.",
+ "what_to_do": "Restore the lock from version control, or generate the code again, which rewrites it.",
+ "see": [
+ {
+ "title": "Codegen Projections",
+ "href": "under-the-hood/codegen-projections.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.codegen.lock_unsupported",
+ "title": "The codegen lock needs a newer Pipelex",
+ "domain": "operator",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "The codegen lock was written in the format version {lock_version}, which this Pipelex does not read.",
+ "steps": {
+ "actor": {
+ "kind": "upgrade",
+ "detail": "Upgrade Pipelex to a version that reads the codegen lock format {lock_version}."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "lock_version": {
+ "type": "integer",
+ "description": "The format version the lock was written in."
+ }
+ },
+ "meaning": "The lock was written by a newer Pipelex, in a format this runtime does not read.",
+ "what_to_do": "If you run the runtime, upgrade Pipelex. Otherwise, report the problem to whoever runs it.",
+ "see": [
+ {
+ "title": "Codegen Projections",
+ "href": "under-the-hood/codegen-projections.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.codegen.lock_not_found",
+ "title": "No codegen lock in this directory",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 404,
+ "detail": "The directory '{path}' holds no codegen lock.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Check the directory codegen wrote, or generate the code into '{path}' first."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose directory '{path}' holds no codegen lock."
+ }
+ },
+ "params": {
+ "path": {
+ "type": "identifier",
+ "description": "The directory checked."
+ }
+ },
+ "meaning": "The directory checked has no `codegen.lock`, so it holds no code generated from a method.",
+ "what_to_do": "Run the check on the directory codegen wrote, or generate the code first.",
+ "see": [
+ {
+ "title": "Codegen Projections",
+ "href": "under-the-hood/codegen-projections.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.codegen.drifted",
+ "title": "The generated code has drifted from its method",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 409,
+ "detail": "The generated code no longer matches its method.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Generate the code again from the method, then check it again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose generated code no longer matches its method."
+ }
+ },
+ "params": {
+ "artifacts": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The generated artifacts that no longer match."
+ }
+ },
+ "meaning": "The artifacts the check read no longer match the method they were generated from.",
+ "what_to_do": "Generate the code again from the current method, and commit what it writes.",
+ "see": [
+ {
+ "title": "Codegen Projections",
+ "href": "under-the-hood/codegen-projections.md"
+ }
+ ]
+ },
+ {
+ "code": "pipelex.connector.tool_not_in_toolset",
+ "title": "The tool is not in the connector's toolset",
+ "domain": "method",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "A model asked for the tool '{tool}', which the method's toolset does not hold.",
+ "steps": {
+ "actor": {
+ "kind": "change_method",
+ "detail": "Add the tool '{tool}' to the method's toolset, or steer the prompt away from it, then run the method again."
+ },
+ "other": {
+ "kind": "contact_owner",
+ "detail": "Ask the method's owner to add the tool '{tool}' to its toolset."
+ }
+ },
+ "params": {
+ "tool": {
+ "type": "identifier",
+ "description": "The tool the model asked for."
+ },
+ "available": {
+ "type": "list",
+ "items": {
+ "type": "identifier"
+ },
+ "description": "The tools the toolset holds."
+ }
+ },
+ "meaning": "A model called a tool that the method's connector toolset does not hold, so the runtime refused the call.",
+ "what_to_do": "Compare the tool with those `params.available` lists, then add it to the toolset or steer the prompt away from it."
+ },
+ {
+ "code": "pipelex.erasure.incomplete",
+ "title": "The erasure left data behind",
+ "domain": "runtime",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 503,
+ "detail": "The erasure of the {resource} '{id}' did not complete, and some of its data remains.",
+ "steps": {
+ "actor": {
+ "kind": "retry",
+ "detail": "Request the erasure of the {resource} '{id}' again."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "resource": {
+ "type": "enum",
+ "values": [
+ "run",
+ "method",
+ "method_version",
+ "workflow"
+ ],
+ "description": "What was being erased: a run, a method, a method's version or a workflow's history."
+ },
+ "id": {
+ "type": "identifier",
+ "description": "The id of what was being erased."
+ }
+ },
+ "meaning": "A purge of a run, a method, a method's version or a workflow's history did not complete, so part of its data remains. Requesting the erasure again resumes it.",
+ "what_to_do": "Request the erasure again. If it keeps failing, report it to whoever runs the runtime, since data that should be gone remains."
+ },
+ {
+ "code": "pipelex.webhook.delivery_failed",
+ "title": "A webhook was not delivered",
+ "domain": "input",
+ "retry": "yes",
+ "raised_as": "problem",
+ "status": 502,
+ "detail": "The webhook was not delivered to its receiver (reason: {reason}).",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Check that the webhook's receiver is reachable and answers with a success status."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, whose webhook receiver refused the delivery or could not be reached."
+ }
+ },
+ "params": {
+ "reason": {
+ "type": "enum",
+ "values": [
+ "http_status",
+ "unreachable"
+ ],
+ "description": "Why the delivery failed: the receiver answered with an error status, or could not be reached."
+ },
+ "receiver_status": {
+ "type": "integer",
+ "optional": true,
+ "description": "The HTTP status the receiver answered with, when it answered."
+ }
+ },
+ "meaning": "A caller's webhook receiver answered with an error status, or could not be reached. The failure is recorded on the delivery, never on the run, and the platform repeats the delivery on its own.",
+ "what_to_do": "Fix the receiver so that it answers with a `2xx` status. The platform repeats the delivery, so nothing needs to be sent again."
+ }
+ ]
+}
diff --git a/pipelex/errors/registry/pipelex-error-registry.yaml b/pipelex/errors/registry/pipelex-error-registry.yaml
new file mode 100644
index 000000000..95e26e10c
--- /dev/null
+++ b/pipelex/errors/registry/pipelex-error-registry.yaml
@@ -0,0 +1,1016 @@
+# The Pipelex error registry.
+#
+# One entry per Pipelex code: a code under the `pipelex` extension prefix, which the MTHDS core
+# registry registers to Pipelex. A Pipelex code names a situation the core codes leave to an
+# implementation: billing, organizations, the hosted catalog, Pipelex's storage, its own
+# configuration and plugins, and the components it ships, such as its document engines and the
+# Daytona sandbox. Each entry declares every member its code needs, in the MTHDS registry format,
+# and the format's JSON Schema refuses an entry with a member missing.
+#
+# This file is the single source. `make generate-error-registry` (`ger`, `pipelex-dev generate-error-registry`)
+# writes from it the JSON snapshot beside it, pipelex-error-registry.json, stamped with Pipelex's
+# version and never edited by hand; the typed Python of the codes and their parameters,
+# pipelex_codes.py; and one documentation page per code under docs/errors/pipelex/, served at the
+# URL the code's type names. The test suite checks all of it. docs/contribute/error-registry.md
+# describes the workflow.
+#
+# The registry carries no version of its own: its snapshot takes Pipelex's version, from
+# pyproject.toml, so a release publishes the registry under its own number.
+#
+# Strings are double-quoted, and "no" and "yes" must be, since YAML would otherwise read them as
+# booleans. A template names a parameter as {name}.
+
+prefix: pipelex
+base_url: "https://docs.pipelex.com/errors"
+
+families:
+ - {family: pipelex.billing, description: "Credit and subscriptions: what an organization's plan and balance allow."}
+ - {family: pipelex.org, description: "Organizations, their members, their API keys and their promo codes."}
+ - {family: pipelex.catalog, description: "Saved methods in an organization's catalog."}
+ - {family: pipelex.run, description: "Pipelex's extensions to runs."}
+ - {family: pipelex.storage, description: "Pipelex's storage addresses and uploads."}
+ - {family: pipelex.security, description: "Pipelex's own refusals made for safety, each recorded as a security event."}
+ - {family: pipelex.config, description: "The runtime's own configuration."}
+ - {family: pipelex.plugin, description: "The plugins installed in the runtime."}
+ - {family: pipelex.deployment, description: "The policies of a runner deployment."}
+ - {family: pipelex.docgen, description: "The document engines that print a PipeDocGen step's documents."}
+ - {family: pipelex.sandbox, description: "The Daytona sandbox that runs a method's own code."}
+ - {family: pipelex.codegen, description: "Code generated from a method."}
+ - {family: pipelex.connector, description: "The toolsets a method's connectors offer a model."}
+ - {family: pipelex.erasure, description: "The erasure of runs and methods."}
+ - {family: pipelex.webhook, description: "The webhooks a caller registers to hear about its runs."}
+
+codes:
+
+ # --- pipelex.billing. -------------------------------------------------------------------
+
+ - code: pipelex.billing.plan_limit
+ title: "The account's plan does not allow this"
+ domain: account
+ retry: "no"
+ raised_as: problem
+ status: 409
+ detail: "The account's plan allows at most {value} for '{limit}', and the account already holds that many."
+ steps:
+ actor: {kind: check_account, detail: "Check the account's plan, then free some of '{limit}' or move to a plan that allows more."}
+ other: {kind: contact_owner, detail: "Ask the account's owner to move to a plan that allows more than {value} for '{limit}'."}
+ params:
+ limit: {type: identifier, description: "What the plan caps, such as the account's API keys."}
+ value: {type: integer, description: "The most the account's plan allows."}
+ meaning: "The account's plan caps a resource, such as its API keys, and the account already holds as many as the plan allows."
+ what_to_do: "Remove something the limit counts, such as an API key no longer in use, or move the account to a plan with a higher limit."
+
+ - code: pipelex.billing.credit_exhausted
+ title: "The organization is out of credit"
+ domain: account
+ retry: "no"
+ raised_as: problem
+ status: 402
+ detail: "The organization has no credit left, so the operation was refused."
+ steps:
+ actor: {kind: check_account, detail: "Add credit to the organization, or move it to a plan that includes more, then try again."}
+ other: {kind: contact_owner, detail: "Ask the account's owner to add credit to the organization."}
+ params: {}
+ meaning: "The organization's credit is spent. The platform refuses a run before queueing it, and a model call made once the credit has run out is refused as well."
+ what_to_do: "Add credit to the organization, or move it to a plan that includes more, then start the run again."
+
+ - code: pipelex.billing.subscription_conflict
+ title: "The subscription's state does not allow this"
+ domain: account
+ retry: "no"
+ raised_as: problem
+ status: 409
+ detail: "This billing action is not possible while the organization's subscription is '{subscription}'."
+ steps:
+ actor: {kind: check_account, detail: "Check the organization's subscription, then take the billing action its state allows."}
+ other: {kind: contact_owner, detail: "Ask the account's owner to check the organization's subscription."}
+ params:
+ subscription: {type: enum, values: [none, active], description: "The organization's subscription: it has none, or it has an active one."}
+ meaning: "A billing action needs an active subscription and the organization has none, or forbids one and the organization already has one."
+ what_to_do: "Read the organization's subscription in its billing settings, then subscribe first, or manage the subscription it already has."
+
+ - code: pipelex.billing.plan_refused
+ title: "The plan's rules refuse this change"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 409
+ detail: "The rules of the organization's plan refuse this change (reason: {reason})."
+ steps:
+ actor: {kind: change_input, detail: "Request a change the organization's plan allows, then send the request again."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose plan change the plan's rules refuse."}
+ params:
+ reason: {type: enum, values: [enterprise_is_paid_only, plan_not_editable, plan_not_enterprise], description: "Why the change is refused: an enterprise plan is only ever paid, the plan cannot be edited, or the change applies only to an enterprise plan and this one is not."}
+ meaning: "An administrator's change to an organization's plan that the plan's kind does not allow."
+ what_to_do: "Read `params.reason`, then choose another plan, or make the change on a plan that allows it."
+
+ # --- pipelex.org. -----------------------------------------------------------------------
+
+ - code: pipelex.org.required
+ title: "An organization is required"
+ domain: account
+ retry: "no"
+ raised_as: problem
+ status: 403
+ detail: "This operation acts on an organization, and the request acts for none."
+ steps:
+ actor: {kind: check_account, detail: "Act for an organization, by joining or creating one, then send the request again."}
+ other: {kind: contact_owner, detail: "Ask the account's owner to add you to an organization."}
+ params: {}
+ meaning: "The caller acts for no organization, and the route acts on an organization's resources."
+ what_to_do: "Sign in to an organization, or use an API key that belongs to one, then send the request again."
+
+ - code: pipelex.org.mismatch
+ title: "The reference belongs to another organization"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 403
+ detail: "The request's {reference} belongs to an organization other than the caller's."
+ steps:
+ actor: {kind: change_input, detail: "Use a {reference} of the organization the request acts for, then send the request again."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose {reference} belongs to another organization."}
+ params:
+ reference: {type: enum, values: [organization_id, storage_uri], description: "The kind of reference that names another organization: an organization's id or a storage address."}
+ meaning: "A well-formed reference names an organization other than the one the caller acts for."
+ what_to_do: "Check which organization the request acts for, and use a reference that belongs to it."
+
+ - code: pipelex.org.not_found
+ title: "The organization's resource does not exist"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 404
+ detail: "The {resource} the request names does not exist."
+ steps:
+ actor: {kind: change_input, detail: "Name a {resource} that exists, then send the request again."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose request names a {resource} that does not exist."}
+ params:
+ resource: {type: enum, values: [organization, member, invitation, api_key, user, promo_code, promo_redemption, flag_target], description: "The kind of resource the request names."}
+ meaning: "The organization, member, invitation, API key, user or promo record the request names does not exist."
+ what_to_do: "Check the identifier the request gives, and list what the organization holds to find the right one."
+
+ - code: pipelex.org.not_manageable
+ title: "The resource cannot be changed this way in its state"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 409
+ detail: "The resource cannot be changed this way in its current state (reason: {reason})."
+ steps:
+ actor: {kind: change_input, detail: "Change the resource another way, or bring it into a state that allows this change first."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose change the resource's state does not allow."}
+ params:
+ reason: {type: identifier, description: "What about the resource's state refuses the change."}
+ meaning: "The resource's state refuses the change: a personal or an internal organization, the last administrator of an organization, a subject with no directory identity, or a promo code's cap set below the redemptions it already has."
+ what_to_do: "Read `params.reason`, then change the request, for instance by naming another administrator before removing the last one."
+
+ - code: pipelex.org.already_exists
+ title: "The organization's resource already exists"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 409
+ detail: "The {resource} the request would create already exists."
+ steps:
+ actor: {kind: change_input, detail: "Use the {resource} that exists, or choose another, then send the request again."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose {resource} already exists."}
+ params:
+ resource: {type: enum, values: [member, invitation, promo_code, api_key_label], description: "The kind of resource that already exists."}
+ meaning: "A member, an invitation, a promo code and an API key's name are each unique, and the one the request gives is taken."
+ what_to_do: "Use the one that exists, or choose another name, code or address."
+
+ - code: pipelex.org.promo_invalid
+ title: "The promo code cannot be redeemed"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 422
+ detail: "The promo code cannot be redeemed."
+ steps:
+ actor: {kind: change_input, detail: "Check the promo code, then redeem one that is valid."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose promo code cannot be redeemed."}
+ params: {}
+ meaning: "The promo code is not one this organization can redeem. The reason is withheld on purpose, so that a code cannot be guessed by trying."
+ what_to_do: "Check the promo code as it was given to you, and ask whoever gave it for one that is valid."
+
+ - code: pipelex.org.promo_credit_pending
+ title: "The promo credit is pending"
+ domain: runtime
+ retry: "no"
+ raised_as: problem
+ status: 502
+ detail: "The promo code was redeemed, and its credit has not been applied yet."
+ steps:
+ actor: {kind: wait, detail: "Wait for the credit to reach the organization, without redeeming the code again."}
+ other: {kind: wait, detail: "Wait for the credit to reach the organization, without redeeming the code again."}
+ params: {}
+ meaning: "The redemption is recorded, but applying its credit failed. A repair sweep applies it later, so redeeming the code again is neither needed nor possible."
+ what_to_do: "Wait, then check the organization's credit. If the credit has not arrived after a day, report it to whoever runs the runtime."
+
+ # --- pipelex.catalog. -------------------------------------------------------------------
+
+ - code: pipelex.catalog.not_found
+ title: "The saved method does not exist"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 404
+ detail: "The organization's catalog holds no {resource} matching the request for the method '{method_id}'."
+ steps:
+ actor: {kind: change_input, detail: "List the organization's catalog to find the {resource}, then send the request again with one that exists."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose request names a {resource} the catalog does not hold."}
+ params:
+ resource: {type: enum, values: [method, version, example], description: "What the request names: a saved method, one of its versions, or one of its examples."}
+ method_id: {type: identifier, description: "The catalog id of the method the request names."}
+ version: {type: integer, optional: true, description: "The version the request names, when what it names is a version."}
+ meaning: "No saved method, version or example matches the request in the catalog of the organization the request acts for."
+ what_to_do: "List the catalog's methods and their versions, and use an identifier that exists. A catalog id is read in the organization the request acts for, so check that it is the right one."
+
+ - code: pipelex.catalog.not_published
+ title: "The saved method has no published version"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 409
+ detail: "The method '{method_id}' has no published version."
+ steps:
+ actor: {kind: change_input, detail: "Publish a version of the method '{method_id}', or name its draft as '{method_id}@draft', then send the request again."}
+ other: {kind: change_input, detail: "Pass this to the caller, who names the latest published version of the method '{method_id}', which has none."}
+ params:
+ method_id: {type: identifier, description: "The catalog id of the method."}
+ meaning: "A bare catalog id names the method's latest published version, and the method has only a draft."
+ what_to_do: "Publish the method, or name its draft with the `@draft` suffix."
+
+ - code: pipelex.catalog.being_deleted
+ title: "The saved method is being deleted"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 409
+ detail: "The method '{method_id}' is being deleted."
+ steps:
+ actor: {kind: change_input, detail: "Use another method, since the method '{method_id}' is being deleted."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose request names the method '{method_id}', which is being deleted."}
+ params:
+ method_id: {type: identifier, description: "The catalog id of the method."}
+ meaning: "The method's deletion is in flight, so it can no longer be run, changed or published."
+ what_to_do: "Use another method, or save the method again under a new id if it is still wanted."
+
+ - code: pipelex.catalog.deletion_failed
+ title: "The saved method's deletion failed"
+ domain: runtime
+ retry: "yes"
+ raised_as: problem
+ status: 503
+ detail: "The deletion of the method '{method_id}' did not complete."
+ steps:
+ actor: {kind: retry, detail: "Delete the method '{method_id}' again."}
+ other: {kind: retry, detail: "Delete the method '{method_id}' again."}
+ params:
+ method_id: {type: identifier, description: "The catalog id of the method."}
+ meaning: "A step of the method's deletion failed. Deleting the method again resumes its deletion."
+ what_to_do: "Send the delete again. If it keeps failing, report it to whoever runs the runtime."
+
+ - code: pipelex.catalog.update_conflict
+ title: "The saved method changed since it was read"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 409
+ detail: "The method '{method_id}' changed after it was read, so the update was not applied."
+ steps:
+ actor: {kind: refresh, detail: "Read the method '{method_id}' again, then apply the change to its current content."}
+ other: {kind: refresh, detail: "Read the method '{method_id}' again, then apply the change to its current content."}
+ params:
+ method_id: {type: identifier, description: "The catalog id of the method."}
+ meaning: "Another write changed the method or its draft between the read the update started from and the update itself, so the update stopped rather than overwrite that change."
+ what_to_do: "Read the method again, apply the change to what it holds now, and send the update again."
+
+ - code: pipelex.catalog.selector_invalid
+ title: "The catalog selector is malformed"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 422
+ detail: "The catalog selector cannot be parsed (reason: {reason})."
+ steps:
+ actor: {kind: change_input, detail: "Write the selector as a catalog id, alone or followed by '@' and a version number or 'draft', then send the request again."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose catalog selector cannot be parsed."}
+ params:
+ reason: {type: enum, values: [malformed_method_id, malformed_version_suffix, suffix_on_linkage], description: "What is wrong: the catalog id itself, the suffix after its '@', or a suffix where the request runs the source it sends and names no version."}
+ meaning: "A method selector names a saved method by its catalog id, `mt_` and its characters, and may add `@3` for one version or `@draft` for the draft. This one breaks that grammar."
+ what_to_do: "Read `params.reason`, then correct the selector: a catalog id as the catalog returned it, with a version number that has no leading zero or the word `draft` after the `@`."
+
+ - code: pipelex.catalog.link_conflict
+ title: "The directory is linked to another method"
+ domain: input
+ retry: "no"
+ raised_as: client
+ detail: "The method link of the directory '{path}' stops this save to the method '{method_id}'."
+ steps:
+ actor: {kind: change_input, detail: "Save the directory to the method its link names, or save these files from a directory of their own."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose directory '{path}' is linked in a way that stops this save."}
+ params:
+ method_id: {type: identifier, description: "The catalog id of the method the save targets."}
+ path: {type: caller_text, description: "The local directory whose link stops the save."}
+ meaning: "A local directory records, in its method link, which saved method its files belong to. The link names another method than the one the save targets, cannot be read, or records a sync that did not finish, so the client refuses to save over a draft that is not this directory's."
+ what_to_do: "Check which method the directory is linked to, then save to that method or move the files to a directory of their own. Repair or remove a link that cannot be read."
+
+ # --- pipelex.run. -----------------------------------------------------------------------
+
+ - code: pipelex.run.already_exists
+ title: "A run with this id already exists"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 409
+ detail: "A run with the id '{pipeline_run_id}' already exists."
+ steps:
+ actor: {kind: change_input, detail: "Start the run with another id, or with none so that the runner assigns one."}
+ other: {kind: change_input, detail: "Pass this to the caller, who chose the run id '{pipeline_run_id}', which is already taken."}
+ params:
+ pipeline_run_id: {type: identifier, description: "The run id the caller chose."}
+ meaning: "The caller chose the run's id, which Pipelex allows as an extension of the protocol, whose run id is always the runner's, and a run already holds that id."
+ what_to_do: "Start the run with a new id, or with none so that the runner assigns it. To see the run that holds the id, read it by that id."
+
+ # --- pipelex.storage. -------------------------------------------------------------------
+
+ - code: pipelex.storage.uri_invalid
+ title: "The storage address is malformed"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 422
+ detail: "A storage address in the request cannot be parsed."
+ steps:
+ actor: {kind: change_input, detail: "Send the storage address exactly as storage returned it, then send the request again."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose request holds a storage address that cannot be parsed."}
+ params: {}
+ meaning: "A `pipelex-storage://` address does not parse, or the storage provider refuses it as a key."
+ what_to_do: "Use the storage address exactly as an upload or a run's results returned it, without editing it."
+ see:
+ - {title: "Cloud Storage", href: "features/cloud-storage.md"}
+
+ - code: pipelex.storage.not_found
+ title: "A stored file is gone"
+ domain: runtime
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "A file the runtime stored is no longer in its {scheme} storage."
+ steps:
+ actor: {kind: report, detail: "Report this to whoever runs the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ scheme: {type: enum, values: [local, s3, gcs, memory], description: "The kind of storage that no longer holds the file."}
+ meaning: "A file the run wrote, or that the runtime handed out, is no longer in storage. A caller's own reference to something that does not exist is `input.reference_not_found` instead."
+ what_to_do: "Report the problem to whoever runs the runtime, with the run's `pipeline_run_id` when it has one."
+
+ - code: pipelex.storage.unavailable
+ title: "Storage is unavailable"
+ domain: runtime
+ retry: "yes"
+ raised_as: problem
+ status: 503
+ detail: "The {scheme} storage failed a read or a write."
+ steps:
+ actor: {kind: retry, detail: "Send the request again after a while."}
+ other: {kind: wait, detail: "Wait, then send the request again."}
+ params:
+ scheme: {type: enum, values: [local, s3, gcs, memory], description: "The kind of storage that failed."}
+ meaning: "The storage backend failed a read or a write, which may succeed later."
+ what_to_do: "Send the request again after `retry_after` seconds when the problem gives it. If storage keeps failing, report it to whoever runs the runtime."
+
+ - code: pipelex.storage.not_configured
+ title: "This deployment serves no storage for that address"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "This deployment serves no storage for the scheme '{scheme}'."
+ steps:
+ actor: {kind: fix_configuration, detail: "Configure a storage for the scheme '{scheme}' on this deployment, then restart the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ scheme: {type: identifier, description: "The scheme of the storage address."}
+ meaning: "A storage address names a scheme for which this deployment configures no bucket."
+ what_to_do: "If you run the runtime, configure the storage for the scheme. Otherwise, report the problem to whoever runs it."
+ see:
+ - {title: "Storage Provider Plugins", href: "under-the-hood/storage-provider-plugins.md"}
+
+ - code: pipelex.storage.grant_unusable
+ title: "The upload grant is spent or expired"
+ domain: runtime
+ retry: "yes"
+ raised_as: problem
+ status: 403
+ detail: "The upload grant has expired, or has already written its file."
+ steps:
+ actor: {kind: retry, detail: "Ask for a new upload grant, then upload the file with it."}
+ other: {kind: retry, detail: "Ask for a new upload grant, then upload the file with it."}
+ params: {}
+ meaning: "An upload grant writes one file, once, before it expires. This one has expired or has already written its file, and a new grant succeeds."
+ what_to_do: "Request a new upload grant, and upload the file with it."
+
+ - code: pipelex.storage.grant_mismatch
+ title: "The upload differs from its grant"
+ domain: runtime
+ retry: "no"
+ raised_as: problem
+ status: 403
+ detail: "The upload differs from what its grant signed, so storage refused it."
+ steps:
+ actor: {kind: report, detail: "Report this to whoever runs the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params: {}
+ meaning: "The upload's size, type, metadata or headers differ from what the grant signed. A client that uploads with the grant exactly as it was handed out never meets this."
+ what_to_do: "Report the problem to whoever runs the runtime. If you wrote the client that uploads, send the headers the grant lists, unchanged."
+
+ - code: pipelex.storage.upload_refused
+ title: "Storage refused the upload"
+ domain: runtime
+ retry: "no"
+ raised_as: problem
+ status: 403
+ detail: "Storage refused the upload with the status {status}."
+ steps:
+ actor: {kind: report, detail: "Report this to whoever runs the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ status: {type: integer, description: "The HTTP status storage answered the upload with."}
+ meaning: "Storage refused an upload for a reason it does not name."
+ what_to_do: "Report the problem to whoever runs the runtime, with the status storage answered."
+
+ # --- pipelex.security. ------------------------------------------------------------------
+
+ - code: pipelex.security.reserved_key
+ title: "The request carries a reserved key"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 422
+ detail: "The request carries object keys that Pipelex's decoder reserves for its own markers."
+ steps:
+ actor: {kind: change_input, detail: "Rename or remove the reserved keys in the request, then send it again."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose request carries reserved keys."}
+ params:
+ keys: {type: list, items: {type: identifier}, description: "The reserved keys the request carries."}
+ meaning: "An object in the request holds a key that Pipelex's decoder would read as a class marker, such as `__class__`, `__module__` or a key starting with `__kajson`. The request is refused, and the refusal is recorded as a security event."
+ what_to_do: "Rename or remove each key `params.keys` lists. No input of a method needs one."
+
+ - code: pipelex.security.result_outside_scope
+ title: "A result location lies outside the run"
+ domain: runtime
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "A result location lies outside the run's storage scope, so the runtime refused it."
+ steps:
+ actor: {kind: report, detail: "Report this to whoever runs the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params: {}
+ meaning: "A result location that a step reported, or that storage holds, lies outside the run's own storage scope. The runtime refuses it, and records the refusal as a security event."
+ what_to_do: "Report the problem to whoever runs the runtime, with the run's `pipeline_run_id`."
+
+ # --- pipelex.config. --------------------------------------------------------------------
+
+ - code: pipelex.config.invalid
+ title: "The runtime's configuration is invalid"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "The runtime's configuration is invalid, so it cannot serve this request."
+ steps:
+ actor: {kind: fix_configuration, detail: "Correct the setting '{setting}' in the file '{file}' of the {surface} configuration, then restart the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ surface: {type: identifier, operator_only: true, description: "The part of the configuration at fault, such as the backends, the model deck, the routing, the plugins, the storage, the telemetry, the log sinks, the libraries or the API server's settings."}
+ file: {type: identifier, operator_only: true, description: "The configuration file that holds the setting."}
+ setting: {type: identifier, operator_only: true, description: "The setting that does not validate."}
+ meaning: "A configuration file or setting parsed, but does not validate."
+ what_to_do: "If you run the runtime, read its logs for the file and the setting, and correct them; `pipelex doctor` checks the configuration. Otherwise, report the problem to whoever runs it."
+ see:
+ - {title: "Configuration", href: "configuration/index.md"}
+ - {title: "Doctor Command", href: "tools/cli/doctor.md"}
+
+ - code: pipelex.config.syntax
+ title: "A configuration file does not parse"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "A configuration file of the runtime does not parse."
+ steps:
+ actor: {kind: fix_configuration, detail: "Fix the TOML of the file '{file}' of the {surface} configuration at line {line}, column {column}, then restart the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ surface: {type: identifier, operator_only: true, description: "The part of the configuration the file belongs to."}
+ file: {type: identifier, operator_only: true, description: "The file that does not parse."}
+ line: {type: integer, operator_only: true, description: "The line of the first fault."}
+ column: {type: integer, operator_only: true, description: "The column of the first fault."}
+ meaning: "A configuration file is not valid TOML."
+ what_to_do: "If you run the runtime, open the file its logs name at the line and column given, and fix the syntax. Otherwise, report the problem to whoever runs it."
+ see:
+ - {title: "Configuration", href: "configuration/index.md"}
+
+ - code: pipelex.config.file_missing
+ title: "A configuration file is missing"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "A configuration file the runtime needs is missing."
+ steps:
+ actor: {kind: fix_configuration, detail: "Create or restore the file '{file}' of the {surface} configuration, then restart the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ surface: {type: identifier, operator_only: true, description: "The part of the configuration the file belongs to."}
+ file: {type: identifier, operator_only: true, description: "The file that is missing."}
+ meaning: "A configuration file, or a key file, that the runtime needs is absent or cannot be loaded."
+ what_to_do: "If you run the runtime, restore the file its logs name, or write the default configuration with `pipelex init`. Otherwise, report the problem to whoever runs it."
+ see:
+ - {title: "Init Commands", href: "tools/cli/init.md"}
+
+ - code: pipelex.config.variable_missing
+ title: "A configuration variable is not set"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "A variable the runtime's configuration refers to is not set."
+ steps:
+ actor: {kind: fix_configuration, detail: "Set the {source} variable '{variable}', then restart the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ variable: {type: identifier, operator_only: true, description: "The variable that is not set."}
+ source: {type: enum, values: [env, secret], operator_only: true, description: "Where the configuration reads the variable from: the environment or a secret."}
+ meaning: "An environment variable or a secret that the configuration refers to did not resolve."
+ what_to_do: "If you run the runtime, set the variable in its environment or in its secrets provider. Otherwise, report the problem to whoever runs it."
+ see:
+ - {title: "Secrets Provider Plugins", href: "under-the-hood/secrets-provider-plugins.md"}
+
+ - code: pipelex.config.credential_missing
+ title: "An inference backend has no credential"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "An inference backend of the runtime has no credential."
+ steps:
+ actor: {kind: check_credentials, detail: "Set the credential '{variable}' of the backend '{backend}', then restart the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ backend: {type: identifier, operator_only: true, description: "The inference backend that lacks its credential."}
+ variable: {type: identifier, operator_only: true, description: "The variable or the file that should hold the credential."}
+ meaning: "A key or a credential file that an inference backend needs is absent."
+ what_to_do: "If you run the runtime, set the backend's key in its environment or its secrets, or disable the backend. Otherwise, report the problem to whoever runs it."
+ see:
+ - {title: "Inference Backend Plugins", href: "under-the-hood/inference-backend-plugins.md"}
+
+ - code: pipelex.config.credential_refused
+ title: "A service refused the configured credential"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "A service the runtime depends on refused the credential it is configured with."
+ steps:
+ actor: {kind: check_credentials, detail: "Check the credential the {surface} configuration holds for the service '{service}'."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ surface: {type: enum, values: [log_sink, storage], operator_only: true, description: "The part of the configuration that holds the credential."}
+ service: {type: identifier, operator_only: true, description: "The service that refused it."}
+ meaning: "A service that is not an inference provider, such as a log sink or a storage, refused the deployment's credential. An inference provider refusing its key is `provider.credential_refused` instead."
+ what_to_do: "If you run the runtime, renew or correct the credential. Otherwise, report the problem to whoever runs it."
+
+ - code: pipelex.config.dependency_missing
+ title: "An optional dependency is not installed"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "An optional dependency that the runtime's configuration needs is not installed."
+ steps:
+ actor: {kind: fix_configuration, detail: "Install '{dependency}', which the extra '{extra}' provides, then restart the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ dependency: {type: identifier, operator_only: true, description: "The package, the SDK or the program that is missing."}
+ extra: {type: identifier, operator_only: true, description: "The Pipelex extra that provides it."}
+ meaning: "A Python extra, an SDK or a program such as `plxt` that the configuration needs is not installed."
+ what_to_do: "If you run the runtime, install Pipelex with the extra its logs name. Otherwise, report the problem to whoever runs it."
+
+ # --- pipelex.plugin. --------------------------------------------------------------------
+
+ - code: pipelex.plugin.not_found
+ title: "No plugin provides the configured choice"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "No installed plugin provides a choice the runtime's configuration makes."
+ steps:
+ actor: {kind: fix_configuration, detail: "Install a plugin that provides '{value}' for the setting '{setting}', or choose a value an installed plugin provides."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ setting: {type: identifier, operator_only: true, description: "The setting that makes the choice."}
+ value: {type: identifier, operator_only: true, description: "The choice no installed plugin provides."}
+ available: {type: list, items: {type: identifier}, operator_only: true, description: "The choices the installed plugins provide."}
+ meaning: "A setting names a storage, a secrets provider, a log sink, an execution mode, an orchestrator or a validator that no installed plugin registers."
+ what_to_do: "If you run the runtime, install the plugin that provides the choice, or choose one of those its logs list as available. Otherwise, report the problem to whoever runs it."
+ see:
+ - {title: "Inference Backend Plugins", href: "under-the-hood/inference-backend-plugins.md"}
+
+ - code: pipelex.plugin.broken
+ title: "A plugin failed to load"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "An installed plugin failed to load."
+ steps:
+ actor: {kind: fix_configuration, detail: "Fix or uninstall the plugin '{plugin}' ({reason}), then restart the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ plugin: {type: identifier, operator_only: true, description: "The plugin that failed."}
+ reason: {type: identifier, operator_only: true, description: "What failed: its loading, its registration, or a rule its package breaks."}
+ meaning: "An installed plugin raised while it was loading or registering, or breaks the rules a plugin's package follows."
+ what_to_do: "If you run the runtime, read its logs for the plugin, then upgrade, fix or uninstall it. Otherwise, report the problem to whoever runs it."
+ see:
+ - {title: "Inference Backend Plugins", href: "under-the-hood/inference-backend-plugins.md"}
+
+ - code: pipelex.plugin.conflict
+ title: "Two plugins claim the same slot"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "Two installed plugins claim the same slot."
+ steps:
+ actor: {kind: fix_configuration, detail: "Uninstall '{plugin}' or '{other_plugin}', which both claim '{slot}', then restart the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ plugin: {type: identifier, operator_only: true, description: "One of the two plugins."}
+ other_plugin: {type: identifier, operator_only: true, description: "The other plugin."}
+ slot: {type: identifier, operator_only: true, description: "The name or the process-wide slot both claim."}
+ meaning: "Two installed plugins register the same name, or claim the same process-wide slot."
+ what_to_do: "If you run the runtime, keep only one of the two plugins. Otherwise, report the problem to whoever runs it."
+ see:
+ - {title: "Inference Backend Plugins", href: "under-the-hood/inference-backend-plugins.md"}
+
+ - code: pipelex.plugin.api_mismatch
+ title: "A plugin targets another plugin API"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "An installed plugin targets a plugin API this runtime does not support."
+ steps:
+ actor: {kind: upgrade, detail: "Upgrade the plugin '{plugin}', built for the plugin API {targets_api}, or Pipelex, which supports the plugin API {supported_api}."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ plugin: {type: identifier, operator_only: true, description: "The plugin."}
+ targets_api: {type: integer, operator_only: true, description: "The plugin API version the plugin was built for."}
+ supported_api: {type: integer, operator_only: true, description: "The plugin API version this runtime supports."}
+ meaning: "An installed plugin was built for another version of the plugin contract than the one this runtime implements."
+ what_to_do: "If you run the runtime, upgrade the plugin or Pipelex so that both target the same plugin API. Otherwise, report the problem to whoever runs it."
+ see:
+ - {title: "Inference Backend Plugins", href: "under-the-hood/inference-backend-plugins.md"}
+
+ # --- pipelex.deployment. ----------------------------------------------------------------
+
+ - code: pipelex.deployment.orchestration_override_forbidden
+ title: "This deployment does not allow choosing the orchestration mode"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 422
+ detail: "This deployment does not let a request choose its orchestration mode, and this one asks for '{requested_mode}'."
+ steps:
+ actor: {kind: change_input, detail: "Send the request without choosing an orchestration mode."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose request chooses an orchestration mode this deployment fixes."}
+ params:
+ requested_mode: {type: identifier, description: "The orchestration mode the request asks for."}
+ meaning: "The deployment's policy fixes the orchestration mode, so a request may not choose one."
+ what_to_do: "Leave the orchestration mode out of the request, and let the deployment run it in its own mode."
+ see:
+ - {title: "Orchestrator Plugins", href: "under-the-hood/orchestrator-plugins.md"}
+
+ - code: pipelex.deployment.custom_code_requires_sandbox
+ title: "Custom code needs a sandbox-hosted deployment"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 501
+ detail: "The method ships Python code in its {origin}, and this deployment runs none outside the Daytona sandbox."
+ steps:
+ actor: {kind: fix_configuration, detail: "Configure the Daytona sandbox on this deployment, so that it can run the method's own code."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ origin: {type: enum, values: [bundle, package], description: "Where the method ships its code: in its bundle or in its package."}
+ meaning: "The method ships Python code of its own, and this deployment runs a method's own code only inside the Daytona sandbox, which it does not have."
+ what_to_do: "If you run the runtime, configure the Daytona sandbox for custom code. Otherwise, run the method on a runtime that allows its code, or ask its owner for a version without Python."
+ see:
+ - {title: "PipeFunc Requirements", href: "under-the-hood/pipe-func-requirements.md"}
+
+ - code: pipelex.deployment.python_structures_refused
+ title: "Python structure classes are not allowed here"
+ domain: method
+ retry: "no"
+ raised_as: problem
+ status: 422
+ detail: "The method declares structures as Python classes, which this runner does not import."
+ steps:
+ actor: {kind: change_method, detail: "Declare the structures as concepts in the method in place of Python classes, then run it again."}
+ other: {kind: contact_owner, detail: "Ask the method's owner to declare its structures as concepts in the method."}
+ params:
+ files: {type: list, items: {type: identifier}, description: "The method's files that declare structures as Python classes."}
+ meaning: "The method declares its structures as Python classes, which no hosted runner imports. Concepts declared in the method itself replace them."
+ what_to_do: "Rewrite each structure the files in `params.files` declare as a concept with its fields in the method, then run it again."
+ see:
+ - {title: "Python StructuredContent Classes", href: "building-methods/concepts/python-classes.md"}
+
+ - code: pipelex.deployment.token_claims_invalid
+ title: "The token's claims cannot be used"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "The request's verified token carries claims this runner cannot use."
+ steps:
+ actor: {kind: fix_configuration, detail: "Correct the claim '{claim}' ({reason}) that the token issuer writes, then send the request again."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ claim: {type: identifier, operator_only: true, description: "The claim at fault."}
+ reason: {type: enum, values: [missing, unsafe, reserved], operator_only: true, description: "What is wrong with the claim: it is missing, unsafe as an identifier, or reserved."}
+ meaning: "A verified token carries a user id the runner cannot use, so the token's issuer is misconfigured."
+ what_to_do: "If you run the runtime, correct the claims its token issuer writes. Otherwise, report the problem to whoever runs it."
+ see:
+ - {title: "API Server Configuration", href: "api-server/configuration.md"}
+
+ # --- pipelex.docgen. --------------------------------------------------------------------
+
+ - code: pipelex.docgen.engine_unavailable
+ title: "No document engine prints this here"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 501
+ detail: "No document engine prints the format '{format}' in this runtime."
+ steps:
+ actor: {kind: fix_configuration, detail: "Install or enable the engine '{engine}' ({gap}), then restart the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ engine: {type: identifier, operator_only: true, description: "The document engine the step needs."}
+ format: {type: enum, values: [pdf, xlsx, docx, pptx], description: "The format the step prints."}
+ gap: {type: identifier, operator_only: true, description: "What is missing: the engine, a system library it needs, its declaration or its enablement."}
+ meaning: "The engine that prints a PipeDocGen step's format, or a system library it needs, is not installed, declared or enabled in this runtime."
+ what_to_do: "If you run the runtime, install and enable the engine. Otherwise, report the problem to whoever runs it."
+ see:
+ - {title: "Document Engine Plugins", href: "under-the-hood/document-engine-plugins.md"}
+
+ - code: pipelex.docgen.template_invalid
+ title: "The document template cannot be used"
+ domain: method
+ retry: "no"
+ raised_as: problem
+ status: 422
+ detail: "The document template '{template}' cannot be used (reason: {reason}): {finding}"
+ steps:
+ actor: {kind: change_method, detail: "Fix the template '{template}', then run the method again."}
+ other: {kind: contact_owner, detail: "Ask the method's owner to fix the template '{template}'."}
+ params:
+ template: {type: identifier, description: "The template."}
+ reason: {type: enum, values: [unreadable, does_not_fit, check_failed, value_unsupported], description: "Why it cannot be used: it is not a readable file of its format, it does not fit the step's inputs, it fails the engine's check, or it maps a value no cell can take."}
+ finding: {type: caller_text, description: "What the engine found, about the method's own template."}
+ meaning: "A PipeDocGen step's template cannot be used to print its document."
+ what_to_do: "Read `params.finding`, then fix the template, or the inputs the step maps into it."
+ see:
+ - {title: "Document Engine Plugins", href: "under-the-hood/document-engine-plugins.md"}
+
+ - code: pipelex.docgen.resource_refused
+ title: "The document names a file it may not read"
+ domain: method
+ retry: "no"
+ raised_as: problem
+ status: 422
+ detail: "The document names a file the print engine may not read (reason: {reason})."
+ steps:
+ actor: {kind: change_method, detail: "Name the file by an absolute https URL or embed it, then run the method again."}
+ other: {kind: contact_owner, detail: "Ask the method's owner to fix the file its document names."}
+ params:
+ reason: {type: enum, values: [relative_url, plain_http_url, undecodable_data_url, unknown_font], description: "Why the file was refused: a relative URL, a plain http URL, a data URL that does not decode, or a font the engine does not know."}
+ meaning: "The print engine's fetcher refused a resource the document names, by policy. A plain `http://` URL breaks a transport rule rather than a security one, so its refusal records no security event."
+ what_to_do: "Use an absolute `https://` URL, embed the file as a data URL that decodes, or use a font the engine provides."
+ see:
+ - {title: "Document Engine Plugins", href: "under-the-hood/document-engine-plugins.md"}
+
+ - code: pipelex.docgen.content_unprintable
+ title: "The document's content cannot be printed"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 422
+ detail: "The run's data holds something the print engine cannot lay out (reason: {reason}, in '{element}')."
+ steps:
+ actor: {kind: change_input, detail: "Change the input that fills '{element}', then run the method again."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose inputs hold something the document cannot print."}
+ params:
+ reason: {type: enum, values: [too_tall_for_page, image_unreadable, image_too_large, image_empty, html_too_large], description: "What cannot be printed: an element taller than a page, an image that cannot be read, is too large or is empty, or HTML past its size limit."}
+ element: {type: identifier, description: "The element of the document that holds it."}
+ meaning: "The run's data holds something the print engine cannot lay out or decode."
+ what_to_do: "Read `params.reason`, then shorten, resize or replace the content, and run the method again."
+
+ - code: pipelex.docgen.print_timeout
+ title: "Printing the document took too long"
+ domain: runtime
+ retry: "yes"
+ raised_as: problem
+ status: 504
+ detail: "Printing the document ran past its limit of {limit} seconds and was stopped."
+ steps:
+ actor: {kind: retry, detail: "Run the method again, since the print may finish within its limit."}
+ other: {kind: retry, detail: "Run the method again, since the print may finish within its limit."}
+ params:
+ limit: {type: seconds, description: "The time the print was allowed."}
+ meaning: "The print, or a resource it read, ran past its limit and was stopped."
+ what_to_do: "Run the method again. If the print keeps running past its limit, make the document lighter, or report it to whoever runs the runtime."
+
+ - code: pipelex.docgen.template_warning
+ title: "The document template may be faulty"
+ domain: method
+ retry: "no"
+ raised_as: warning
+ detail: "The document template '{template}' may be faulty: {finding}"
+ steps:
+ actor: {kind: change_method, detail: "Check the template '{template}', and fix it if the finding is right."}
+ other: {kind: contact_owner, detail: "Ask the method's owner to check the template '{template}'."}
+ params:
+ template: {type: identifier, description: "The template."}
+ finding: {type: caller_text, description: "What the check found, about the method's own template."}
+ meaning: "An advisory: the check of a PipeDocGen step's template found a likely fault, which does not stop the method from validating."
+ what_to_do: "Read `params.finding`, check the template, and fix it if the finding is right."
+ see:
+ - {title: "Document Engine Plugins", href: "under-the-hood/document-engine-plugins.md"}
+
+ # --- pipelex.sandbox. -------------------------------------------------------------------
+
+ - code: pipelex.sandbox.unavailable
+ title: "The Daytona sandbox could not be started"
+ domain: runtime
+ retry: "yes"
+ raised_as: problem
+ status: 503
+ detail: "The Daytona sandbox that runs the method's code could not be started (backend: {backend}), so the code never ran."
+ steps:
+ actor: {kind: retry, detail: "Run the method again after a while."}
+ other: {kind: retry, detail: "Run the method again after a while."}
+ params:
+ backend: {type: enum, values: [daytona, subprocess], description: "What could not be started: a Daytona sandbox, or the local subprocess that stands in for it."}
+ meaning: "A Daytona sandbox, or the local subprocess that stands in for it, could not be provisioned or reached. The method's own code never ran, so running the method again is safe."
+ what_to_do: "Run the method again after a while. If the Daytona sandbox keeps failing, report it to whoever runs the runtime."
+ see:
+ - {title: "PipeFunc Requirements", href: "under-the-hood/pipe-func-requirements.md"}
+
+ # --- pipelex.codegen. -------------------------------------------------------------------
+
+ - code: pipelex.codegen.output_conflict
+ title: "Codegen will not write there"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 409
+ detail: "Codegen will not write to '{path}' (reason: {reason})."
+ steps:
+ actor: {kind: change_input, detail: "Generate into a directory codegen owns, or move what sits at '{path}' out of the way."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose codegen target '{path}' holds something codegen will not overwrite."}
+ params:
+ path: {type: identifier, description: "The path codegen would write."}
+ reason: {type: enum, values: [unowned_file, escapes_root, not_a_file, symlink], description: "Why codegen will not write there: a file it does not own sits there, the path lies outside the output root, is not a file, or is a symbolic link."}
+ meaning: "A file codegen does not own sits at the target, or the target lies outside the output root, is not a file, or is a symbolic link."
+ what_to_do: "Point codegen at a directory of its own, or remove what sits at the path, then generate again."
+ see:
+ - {title: "Codegen Projections", href: "under-the-hood/codegen-projections.md"}
+
+ - code: pipelex.codegen.lock_invalid
+ title: "The codegen lock is unreadable"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 422
+ detail: "The codegen lock '{file}' cannot be read."
+ steps:
+ actor: {kind: change_input, detail: "Restore the lock '{file}' from version control, or generate the code again to rewrite it."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose codegen lock '{file}' cannot be read."}
+ params:
+ file: {type: identifier, description: "The lock file."}
+ meaning: "The `codegen.lock` file is malformed, or records a tree that is not safe to write."
+ what_to_do: "Restore the lock from version control, or generate the code again, which rewrites it."
+ see:
+ - {title: "Codegen Projections", href: "under-the-hood/codegen-projections.md"}
+
+ - code: pipelex.codegen.lock_unsupported
+ title: "The codegen lock needs a newer Pipelex"
+ domain: operator
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "The codegen lock was written in the format version {lock_version}, which this Pipelex does not read."
+ steps:
+ actor: {kind: upgrade, detail: "Upgrade Pipelex to a version that reads the codegen lock format {lock_version}."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ lock_version: {type: integer, description: "The format version the lock was written in."}
+ meaning: "The lock was written by a newer Pipelex, in a format this runtime does not read."
+ what_to_do: "If you run the runtime, upgrade Pipelex. Otherwise, report the problem to whoever runs it."
+ see:
+ - {title: "Codegen Projections", href: "under-the-hood/codegen-projections.md"}
+
+ - code: pipelex.codegen.lock_not_found
+ title: "No codegen lock in this directory"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 404
+ detail: "The directory '{path}' holds no codegen lock."
+ steps:
+ actor: {kind: change_input, detail: "Check the directory codegen wrote, or generate the code into '{path}' first."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose directory '{path}' holds no codegen lock."}
+ params:
+ path: {type: identifier, description: "The directory checked."}
+ meaning: "The directory checked has no `codegen.lock`, so it holds no code generated from a method."
+ what_to_do: "Run the check on the directory codegen wrote, or generate the code first."
+ see:
+ - {title: "Codegen Projections", href: "under-the-hood/codegen-projections.md"}
+
+ - code: pipelex.codegen.drifted
+ title: "The generated code has drifted from its method"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 409
+ detail: "The generated code no longer matches its method."
+ steps:
+ actor: {kind: change_input, detail: "Generate the code again from the method, then check it again."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose generated code no longer matches its method."}
+ params:
+ artifacts: {type: list, items: {type: identifier}, description: "The generated artifacts that no longer match."}
+ meaning: "The artifacts the check read no longer match the method they were generated from."
+ what_to_do: "Generate the code again from the current method, and commit what it writes."
+ see:
+ - {title: "Codegen Projections", href: "under-the-hood/codegen-projections.md"}
+
+ # --- pipelex.connector. -----------------------------------------------------------------
+
+ - code: pipelex.connector.tool_not_in_toolset
+ title: "The tool is not in the connector's toolset"
+ domain: method
+ retry: "no"
+ raised_as: problem
+ status: 422
+ detail: "A model asked for the tool '{tool}', which the method's toolset does not hold."
+ steps:
+ actor: {kind: change_method, detail: "Add the tool '{tool}' to the method's toolset, or steer the prompt away from it, then run the method again."}
+ other: {kind: contact_owner, detail: "Ask the method's owner to add the tool '{tool}' to its toolset."}
+ params:
+ tool: {type: identifier, description: "The tool the model asked for."}
+ available: {type: list, items: {type: identifier}, description: "The tools the toolset holds."}
+ meaning: "A model called a tool that the method's connector toolset does not hold, so the runtime refused the call."
+ what_to_do: "Compare the tool with those `params.available` lists, then add it to the toolset or steer the prompt away from it."
+
+ # --- pipelex.erasure. -------------------------------------------------------------------
+
+ - code: pipelex.erasure.incomplete
+ title: "The erasure left data behind"
+ domain: runtime
+ retry: "yes"
+ raised_as: problem
+ status: 503
+ detail: "The erasure of the {resource} '{id}' did not complete, and some of its data remains."
+ steps:
+ actor: {kind: retry, detail: "Request the erasure of the {resource} '{id}' again."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ resource: {type: enum, values: [run, method, method_version, workflow], description: "What was being erased: a run, a method, a method's version or a workflow's history."}
+ id: {type: identifier, description: "The id of what was being erased."}
+ meaning: "A purge of a run, a method, a method's version or a workflow's history did not complete, so part of its data remains. Requesting the erasure again resumes it."
+ what_to_do: "Request the erasure again. If it keeps failing, report it to whoever runs the runtime, since data that should be gone remains."
+
+ # --- pipelex.webhook. -------------------------------------------------------------------
+
+ - code: pipelex.webhook.delivery_failed
+ title: "A webhook was not delivered"
+ domain: input
+ retry: "yes"
+ raised_as: problem
+ status: 502
+ detail: "The webhook was not delivered to its receiver (reason: {reason})."
+ steps:
+ actor: {kind: change_input, detail: "Check that the webhook's receiver is reachable and answers with a success status."}
+ other: {kind: change_input, detail: "Pass this to the caller, whose webhook receiver refused the delivery or could not be reached."}
+ params:
+ reason: {type: enum, values: [http_status, unreachable], description: "Why the delivery failed: the receiver answered with an error status, or could not be reached."}
+ receiver_status: {type: integer, optional: true, description: "The HTTP status the receiver answered with, when it answered."}
+ meaning: "A caller's webhook receiver answered with an error status, or could not be reached. The failure is recorded on the delivery, never on the run, and the platform repeats the delivery on its own."
+ what_to_do: "Fix the receiver so that it answers with a `2xx` status. The platform repeats the delivery, so nothing needs to be sent again."
diff --git a/pipelex/errors/registry/pipelex_codes.py b/pipelex/errors/registry/pipelex_codes.py
new file mode 100644
index 000000000..93d061739
--- /dev/null
+++ b/pipelex/errors/registry/pipelex_codes.py
@@ -0,0 +1,1016 @@
+"""The Pipelex error codes and the typed parameters of each, generated from ``pipelex-error-registry.yaml``.
+
+Generated by ``pipelex-dev generate-error-registry`` (``make generate-error-registry``): never edit it by
+hand. The registry beside it is the single source, and the test suite fails when this module is not what
+the generator writes from it.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import ClassVar, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class PipelexErrorCode(StrEnum):
+ """Every code of the Pipelex error registry."""
+
+ BILLING_PLAN_LIMIT = "pipelex.billing.plan_limit"
+ BILLING_CREDIT_EXHAUSTED = "pipelex.billing.credit_exhausted"
+ BILLING_SUBSCRIPTION_CONFLICT = "pipelex.billing.subscription_conflict"
+ BILLING_PLAN_REFUSED = "pipelex.billing.plan_refused"
+ ORG_REQUIRED = "pipelex.org.required"
+ ORG_MISMATCH = "pipelex.org.mismatch"
+ ORG_NOT_FOUND = "pipelex.org.not_found"
+ ORG_NOT_MANAGEABLE = "pipelex.org.not_manageable"
+ ORG_ALREADY_EXISTS = "pipelex.org.already_exists"
+ ORG_PROMO_INVALID = "pipelex.org.promo_invalid"
+ ORG_PROMO_CREDIT_PENDING = "pipelex.org.promo_credit_pending"
+ CATALOG_NOT_FOUND = "pipelex.catalog.not_found"
+ CATALOG_NOT_PUBLISHED = "pipelex.catalog.not_published"
+ CATALOG_BEING_DELETED = "pipelex.catalog.being_deleted"
+ CATALOG_DELETION_FAILED = "pipelex.catalog.deletion_failed"
+ CATALOG_UPDATE_CONFLICT = "pipelex.catalog.update_conflict"
+ CATALOG_SELECTOR_INVALID = "pipelex.catalog.selector_invalid"
+ CATALOG_LINK_CONFLICT = "pipelex.catalog.link_conflict"
+ RUN_ALREADY_EXISTS = "pipelex.run.already_exists"
+ STORAGE_URI_INVALID = "pipelex.storage.uri_invalid"
+ STORAGE_NOT_FOUND = "pipelex.storage.not_found"
+ STORAGE_UNAVAILABLE = "pipelex.storage.unavailable"
+ STORAGE_NOT_CONFIGURED = "pipelex.storage.not_configured"
+ STORAGE_GRANT_UNUSABLE = "pipelex.storage.grant_unusable"
+ STORAGE_GRANT_MISMATCH = "pipelex.storage.grant_mismatch"
+ STORAGE_UPLOAD_REFUSED = "pipelex.storage.upload_refused"
+ SECURITY_RESERVED_KEY = "pipelex.security.reserved_key"
+ SECURITY_RESULT_OUTSIDE_SCOPE = "pipelex.security.result_outside_scope"
+ CONFIG_INVALID = "pipelex.config.invalid"
+ CONFIG_SYNTAX = "pipelex.config.syntax"
+ CONFIG_FILE_MISSING = "pipelex.config.file_missing"
+ CONFIG_VARIABLE_MISSING = "pipelex.config.variable_missing"
+ CONFIG_CREDENTIAL_MISSING = "pipelex.config.credential_missing"
+ CONFIG_CREDENTIAL_REFUSED = "pipelex.config.credential_refused"
+ CONFIG_DEPENDENCY_MISSING = "pipelex.config.dependency_missing"
+ PLUGIN_NOT_FOUND = "pipelex.plugin.not_found"
+ PLUGIN_BROKEN = "pipelex.plugin.broken"
+ PLUGIN_CONFLICT = "pipelex.plugin.conflict"
+ PLUGIN_API_MISMATCH = "pipelex.plugin.api_mismatch"
+ DEPLOYMENT_ORCHESTRATION_OVERRIDE_FORBIDDEN = "pipelex.deployment.orchestration_override_forbidden"
+ DEPLOYMENT_CUSTOM_CODE_REQUIRES_SANDBOX = "pipelex.deployment.custom_code_requires_sandbox"
+ DEPLOYMENT_PYTHON_STRUCTURES_REFUSED = "pipelex.deployment.python_structures_refused"
+ DEPLOYMENT_TOKEN_CLAIMS_INVALID = "pipelex.deployment.token_claims_invalid"
+ DOCGEN_ENGINE_UNAVAILABLE = "pipelex.docgen.engine_unavailable"
+ DOCGEN_TEMPLATE_INVALID = "pipelex.docgen.template_invalid"
+ DOCGEN_RESOURCE_REFUSED = "pipelex.docgen.resource_refused"
+ DOCGEN_CONTENT_UNPRINTABLE = "pipelex.docgen.content_unprintable"
+ DOCGEN_PRINT_TIMEOUT = "pipelex.docgen.print_timeout"
+ DOCGEN_TEMPLATE_WARNING = "pipelex.docgen.template_warning"
+ SANDBOX_UNAVAILABLE = "pipelex.sandbox.unavailable"
+ CODEGEN_OUTPUT_CONFLICT = "pipelex.codegen.output_conflict"
+ CODEGEN_LOCK_INVALID = "pipelex.codegen.lock_invalid"
+ CODEGEN_LOCK_UNSUPPORTED = "pipelex.codegen.lock_unsupported"
+ CODEGEN_LOCK_NOT_FOUND = "pipelex.codegen.lock_not_found"
+ CODEGEN_DRIFTED = "pipelex.codegen.drifted"
+ CONNECTOR_TOOL_NOT_IN_TOOLSET = "pipelex.connector.tool_not_in_toolset"
+ ERASURE_INCOMPLETE = "pipelex.erasure.incomplete"
+ WEBHOOK_DELIVERY_FAILED = "pipelex.webhook.delivery_failed"
+
+
+class PipelexErrorParams(BaseModel):
+ """The parameters of a Pipelex code: the base of each code's own model, closed, frozen and strict.
+
+ Strict, so that a value of another type is refused rather than coerced: a line given as ``"3"`` or
+ ``True`` is refused rather than read as an integer. An integer is still accepted where a number of
+ seconds is declared.
+
+ Attributes:
+ code: The code whose parameters the model holds.
+ operator_only_params: The parameters that only whoever runs the runtime may read, which an
+ implementation leaves out of every problem it answers to a caller.
+ """
+
+ model_config = ConfigDict(extra="forbid", frozen=True, strict=True)
+
+ code: ClassVar[PipelexErrorCode]
+ operator_only_params: ClassVar[frozenset[str]] = frozenset()
+
+
+class BillingPlanLimitParams(PipelexErrorParams):
+ """The parameters of `pipelex.billing.plan_limit`.
+
+ The account's plan does not allow this.
+
+ Attributes:
+ limit: What the plan caps, such as the account's API keys.
+ value: The most the account's plan allows.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.BILLING_PLAN_LIMIT
+
+ limit: str
+ value: int
+
+
+class BillingCreditExhaustedParams(PipelexErrorParams):
+ """The parameters of `pipelex.billing.credit_exhausted`.
+
+ The organization is out of credit.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.BILLING_CREDIT_EXHAUSTED
+
+
+class BillingSubscriptionConflictParams(PipelexErrorParams):
+ """The parameters of `pipelex.billing.subscription_conflict`.
+
+ The subscription's state does not allow this.
+
+ Attributes:
+ subscription: The organization's subscription: it has none, or it has an active one.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.BILLING_SUBSCRIPTION_CONFLICT
+
+ subscription: Literal["none", "active"]
+
+
+class BillingPlanRefusedParams(PipelexErrorParams):
+ """The parameters of `pipelex.billing.plan_refused`.
+
+ The plan's rules refuse this change.
+
+ Attributes:
+ reason: Why the change is refused: an enterprise plan is only ever paid, the plan cannot be edited, or
+ the change applies only to an enterprise plan and this one is not.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.BILLING_PLAN_REFUSED
+
+ reason: Literal["enterprise_is_paid_only", "plan_not_editable", "plan_not_enterprise"]
+
+
+class OrgRequiredParams(PipelexErrorParams):
+ """The parameters of `pipelex.org.required`.
+
+ An organization is required.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.ORG_REQUIRED
+
+
+class OrgMismatchParams(PipelexErrorParams):
+ """The parameters of `pipelex.org.mismatch`.
+
+ The reference belongs to another organization.
+
+ Attributes:
+ reference: The kind of reference that names another organization: an organization's id or a storage
+ address.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.ORG_MISMATCH
+
+ reference: Literal["organization_id", "storage_uri"]
+
+
+class OrgNotFoundParams(PipelexErrorParams):
+ """The parameters of `pipelex.org.not_found`.
+
+ The organization's resource does not exist.
+
+ Attributes:
+ resource: The kind of resource the request names.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.ORG_NOT_FOUND
+
+ resource: Literal["organization", "member", "invitation", "api_key", "user", "promo_code", "promo_redemption", "flag_target"]
+
+
+class OrgNotManageableParams(PipelexErrorParams):
+ """The parameters of `pipelex.org.not_manageable`.
+
+ The resource cannot be changed this way in its state.
+
+ Attributes:
+ reason: What about the resource's state refuses the change.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.ORG_NOT_MANAGEABLE
+
+ reason: str
+
+
+class OrgAlreadyExistsParams(PipelexErrorParams):
+ """The parameters of `pipelex.org.already_exists`.
+
+ The organization's resource already exists.
+
+ Attributes:
+ resource: The kind of resource that already exists.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.ORG_ALREADY_EXISTS
+
+ resource: Literal["member", "invitation", "promo_code", "api_key_label"]
+
+
+class OrgPromoInvalidParams(PipelexErrorParams):
+ """The parameters of `pipelex.org.promo_invalid`.
+
+ The promo code cannot be redeemed.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.ORG_PROMO_INVALID
+
+
+class OrgPromoCreditPendingParams(PipelexErrorParams):
+ """The parameters of `pipelex.org.promo_credit_pending`.
+
+ The promo credit is pending.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.ORG_PROMO_CREDIT_PENDING
+
+
+class CatalogNotFoundParams(PipelexErrorParams):
+ """The parameters of `pipelex.catalog.not_found`.
+
+ The saved method does not exist.
+
+ Attributes:
+ resource: What the request names: a saved method, one of its versions, or one of its examples.
+ method_id: The catalog id of the method the request names.
+ version: The version the request names, when what it names is a version.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CATALOG_NOT_FOUND
+
+ resource: Literal["method", "version", "example"]
+ method_id: str
+ version: int | None = None
+
+
+class CatalogNotPublishedParams(PipelexErrorParams):
+ """The parameters of `pipelex.catalog.not_published`.
+
+ The saved method has no published version.
+
+ Attributes:
+ method_id: The catalog id of the method.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CATALOG_NOT_PUBLISHED
+
+ method_id: str
+
+
+class CatalogBeingDeletedParams(PipelexErrorParams):
+ """The parameters of `pipelex.catalog.being_deleted`.
+
+ The saved method is being deleted.
+
+ Attributes:
+ method_id: The catalog id of the method.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CATALOG_BEING_DELETED
+
+ method_id: str
+
+
+class CatalogDeletionFailedParams(PipelexErrorParams):
+ """The parameters of `pipelex.catalog.deletion_failed`.
+
+ The saved method's deletion failed.
+
+ Attributes:
+ method_id: The catalog id of the method.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CATALOG_DELETION_FAILED
+
+ method_id: str
+
+
+class CatalogUpdateConflictParams(PipelexErrorParams):
+ """The parameters of `pipelex.catalog.update_conflict`.
+
+ The saved method changed since it was read.
+
+ Attributes:
+ method_id: The catalog id of the method.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CATALOG_UPDATE_CONFLICT
+
+ method_id: str
+
+
+class CatalogSelectorInvalidParams(PipelexErrorParams):
+ """The parameters of `pipelex.catalog.selector_invalid`.
+
+ The catalog selector is malformed.
+
+ Attributes:
+ reason: What is wrong: the catalog id itself, the suffix after its '@', or a suffix where the request
+ runs the source it sends and names no version.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CATALOG_SELECTOR_INVALID
+
+ reason: Literal["malformed_method_id", "malformed_version_suffix", "suffix_on_linkage"]
+
+
+class CatalogLinkConflictParams(PipelexErrorParams):
+ """The parameters of `pipelex.catalog.link_conflict`.
+
+ The directory is linked to another method.
+
+ Attributes:
+ method_id: The catalog id of the method the save targets.
+ path: The local directory whose link stops the save.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CATALOG_LINK_CONFLICT
+
+ method_id: str
+ path: str
+
+
+class RunAlreadyExistsParams(PipelexErrorParams):
+ """The parameters of `pipelex.run.already_exists`.
+
+ A run with this id already exists.
+
+ Attributes:
+ pipeline_run_id: The run id the caller chose.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.RUN_ALREADY_EXISTS
+
+ pipeline_run_id: str
+
+
+class StorageUriInvalidParams(PipelexErrorParams):
+ """The parameters of `pipelex.storage.uri_invalid`.
+
+ The storage address is malformed.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.STORAGE_URI_INVALID
+
+
+class StorageNotFoundParams(PipelexErrorParams):
+ """The parameters of `pipelex.storage.not_found`.
+
+ A stored file is gone.
+
+ Attributes:
+ scheme: The kind of storage that no longer holds the file.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.STORAGE_NOT_FOUND
+
+ scheme: Literal["local", "s3", "gcs", "memory"]
+
+
+class StorageUnavailableParams(PipelexErrorParams):
+ """The parameters of `pipelex.storage.unavailable`.
+
+ Storage is unavailable.
+
+ Attributes:
+ scheme: The kind of storage that failed.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.STORAGE_UNAVAILABLE
+
+ scheme: Literal["local", "s3", "gcs", "memory"]
+
+
+class StorageNotConfiguredParams(PipelexErrorParams):
+ """The parameters of `pipelex.storage.not_configured`.
+
+ This deployment serves no storage for that address.
+
+ Attributes:
+ scheme: The scheme of the storage address.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.STORAGE_NOT_CONFIGURED
+
+ scheme: str
+
+
+class StorageGrantUnusableParams(PipelexErrorParams):
+ """The parameters of `pipelex.storage.grant_unusable`.
+
+ The upload grant is spent or expired.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.STORAGE_GRANT_UNUSABLE
+
+
+class StorageGrantMismatchParams(PipelexErrorParams):
+ """The parameters of `pipelex.storage.grant_mismatch`.
+
+ The upload differs from its grant.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.STORAGE_GRANT_MISMATCH
+
+
+class StorageUploadRefusedParams(PipelexErrorParams):
+ """The parameters of `pipelex.storage.upload_refused`.
+
+ Storage refused the upload.
+
+ Attributes:
+ status: The HTTP status storage answered the upload with.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.STORAGE_UPLOAD_REFUSED
+
+ status: int
+
+
+class SecurityReservedKeyParams(PipelexErrorParams):
+ """The parameters of `pipelex.security.reserved_key`.
+
+ The request carries a reserved key.
+
+ Attributes:
+ keys: The reserved keys the request carries.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.SECURITY_RESERVED_KEY
+
+ keys: list[str]
+
+
+class SecurityResultOutsideScopeParams(PipelexErrorParams):
+ """The parameters of `pipelex.security.result_outside_scope`.
+
+ A result location lies outside the run.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.SECURITY_RESULT_OUTSIDE_SCOPE
+
+
+class ConfigInvalidParams(PipelexErrorParams):
+ """The parameters of `pipelex.config.invalid`.
+
+ The runtime's configuration is invalid.
+
+ Attributes:
+ surface: The part of the configuration at fault, such as the backends, the model deck, the routing,
+ the plugins, the storage, the telemetry, the log sinks, the libraries or the API server's
+ settings.
+ file: The configuration file that holds the setting.
+ setting: The setting that does not validate.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CONFIG_INVALID
+ operator_only_params: ClassVar[frozenset[str]] = frozenset({"surface", "file", "setting"})
+
+ surface: str
+ file: str
+ setting: str
+
+
+class ConfigSyntaxParams(PipelexErrorParams):
+ """The parameters of `pipelex.config.syntax`.
+
+ A configuration file does not parse.
+
+ Attributes:
+ surface: The part of the configuration the file belongs to.
+ file: The file that does not parse.
+ line: The line of the first fault.
+ column: The column of the first fault.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CONFIG_SYNTAX
+ operator_only_params: ClassVar[frozenset[str]] = frozenset({"surface", "file", "line", "column"})
+
+ surface: str
+ file: str
+ line: int
+ column: int
+
+
+class ConfigFileMissingParams(PipelexErrorParams):
+ """The parameters of `pipelex.config.file_missing`.
+
+ A configuration file is missing.
+
+ Attributes:
+ surface: The part of the configuration the file belongs to.
+ file: The file that is missing.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CONFIG_FILE_MISSING
+ operator_only_params: ClassVar[frozenset[str]] = frozenset({"surface", "file"})
+
+ surface: str
+ file: str
+
+
+class ConfigVariableMissingParams(PipelexErrorParams):
+ """The parameters of `pipelex.config.variable_missing`.
+
+ A configuration variable is not set.
+
+ Attributes:
+ variable: The variable that is not set.
+ source: Where the configuration reads the variable from: the environment or a secret.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CONFIG_VARIABLE_MISSING
+ operator_only_params: ClassVar[frozenset[str]] = frozenset({"variable", "source"})
+
+ variable: str
+ source: Literal["env", "secret"]
+
+
+class ConfigCredentialMissingParams(PipelexErrorParams):
+ """The parameters of `pipelex.config.credential_missing`.
+
+ An inference backend has no credential.
+
+ Attributes:
+ backend: The inference backend that lacks its credential.
+ variable: The variable or the file that should hold the credential.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CONFIG_CREDENTIAL_MISSING
+ operator_only_params: ClassVar[frozenset[str]] = frozenset({"backend", "variable"})
+
+ backend: str
+ variable: str
+
+
+class ConfigCredentialRefusedParams(PipelexErrorParams):
+ """The parameters of `pipelex.config.credential_refused`.
+
+ A service refused the configured credential.
+
+ Attributes:
+ surface: The part of the configuration that holds the credential.
+ service: The service that refused it.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CONFIG_CREDENTIAL_REFUSED
+ operator_only_params: ClassVar[frozenset[str]] = frozenset({"surface", "service"})
+
+ surface: Literal["log_sink", "storage"]
+ service: str
+
+
+class ConfigDependencyMissingParams(PipelexErrorParams):
+ """The parameters of `pipelex.config.dependency_missing`.
+
+ An optional dependency is not installed.
+
+ Attributes:
+ dependency: The package, the SDK or the program that is missing.
+ extra: The Pipelex extra that provides it.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CONFIG_DEPENDENCY_MISSING
+ operator_only_params: ClassVar[frozenset[str]] = frozenset({"dependency", "extra"})
+
+ dependency: str
+ extra: str
+
+
+class PluginNotFoundParams(PipelexErrorParams):
+ """The parameters of `pipelex.plugin.not_found`.
+
+ No plugin provides the configured choice.
+
+ Attributes:
+ setting: The setting that makes the choice.
+ value: The choice no installed plugin provides.
+ available: The choices the installed plugins provide.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.PLUGIN_NOT_FOUND
+ operator_only_params: ClassVar[frozenset[str]] = frozenset({"setting", "value", "available"})
+
+ setting: str
+ value: str
+ available: list[str]
+
+
+class PluginBrokenParams(PipelexErrorParams):
+ """The parameters of `pipelex.plugin.broken`.
+
+ A plugin failed to load.
+
+ Attributes:
+ plugin: The plugin that failed.
+ reason: What failed: its loading, its registration, or a rule its package breaks.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.PLUGIN_BROKEN
+ operator_only_params: ClassVar[frozenset[str]] = frozenset({"plugin", "reason"})
+
+ plugin: str
+ reason: str
+
+
+class PluginConflictParams(PipelexErrorParams):
+ """The parameters of `pipelex.plugin.conflict`.
+
+ Two plugins claim the same slot.
+
+ Attributes:
+ plugin: One of the two plugins.
+ other_plugin: The other plugin.
+ slot: The name or the process-wide slot both claim.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.PLUGIN_CONFLICT
+ operator_only_params: ClassVar[frozenset[str]] = frozenset({"plugin", "other_plugin", "slot"})
+
+ plugin: str
+ other_plugin: str
+ slot: str
+
+
+class PluginApiMismatchParams(PipelexErrorParams):
+ """The parameters of `pipelex.plugin.api_mismatch`.
+
+ A plugin targets another plugin API.
+
+ Attributes:
+ plugin: The plugin.
+ targets_api: The plugin API version the plugin was built for.
+ supported_api: The plugin API version this runtime supports.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.PLUGIN_API_MISMATCH
+ operator_only_params: ClassVar[frozenset[str]] = frozenset({"plugin", "targets_api", "supported_api"})
+
+ plugin: str
+ targets_api: int
+ supported_api: int
+
+
+class DeploymentOrchestrationOverrideForbiddenParams(PipelexErrorParams):
+ """The parameters of `pipelex.deployment.orchestration_override_forbidden`.
+
+ This deployment does not allow choosing the orchestration mode.
+
+ Attributes:
+ requested_mode: The orchestration mode the request asks for.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.DEPLOYMENT_ORCHESTRATION_OVERRIDE_FORBIDDEN
+
+ requested_mode: str
+
+
+class DeploymentCustomCodeRequiresSandboxParams(PipelexErrorParams):
+ """The parameters of `pipelex.deployment.custom_code_requires_sandbox`.
+
+ Custom code needs a sandbox-hosted deployment.
+
+ Attributes:
+ origin: Where the method ships its code: in its bundle or in its package.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.DEPLOYMENT_CUSTOM_CODE_REQUIRES_SANDBOX
+
+ origin: Literal["bundle", "package"]
+
+
+class DeploymentPythonStructuresRefusedParams(PipelexErrorParams):
+ """The parameters of `pipelex.deployment.python_structures_refused`.
+
+ Python structure classes are not allowed here.
+
+ Attributes:
+ files: The method's files that declare structures as Python classes.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.DEPLOYMENT_PYTHON_STRUCTURES_REFUSED
+
+ files: list[str]
+
+
+class DeploymentTokenClaimsInvalidParams(PipelexErrorParams):
+ """The parameters of `pipelex.deployment.token_claims_invalid`.
+
+ The token's claims cannot be used.
+
+ Attributes:
+ claim: The claim at fault.
+ reason: What is wrong with the claim: it is missing, unsafe as an identifier, or reserved.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.DEPLOYMENT_TOKEN_CLAIMS_INVALID
+ operator_only_params: ClassVar[frozenset[str]] = frozenset({"claim", "reason"})
+
+ claim: str
+ reason: Literal["missing", "unsafe", "reserved"]
+
+
+class DocgenEngineUnavailableParams(PipelexErrorParams):
+ """The parameters of `pipelex.docgen.engine_unavailable`.
+
+ No document engine prints this here.
+
+ Attributes:
+ engine: The document engine the step needs.
+ format: The format the step prints.
+ gap: What is missing: the engine, a system library it needs, its declaration or its enablement.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.DOCGEN_ENGINE_UNAVAILABLE
+ operator_only_params: ClassVar[frozenset[str]] = frozenset({"engine", "gap"})
+
+ engine: str
+ format: Literal["pdf", "xlsx", "docx", "pptx"]
+ gap: str
+
+
+class DocgenTemplateInvalidParams(PipelexErrorParams):
+ """The parameters of `pipelex.docgen.template_invalid`.
+
+ The document template cannot be used.
+
+ Attributes:
+ template: The template.
+ reason: Why it cannot be used: it is not a readable file of its format, it does not fit the step's
+ inputs, it fails the engine's check, or it maps a value no cell can take.
+ finding: What the engine found, about the method's own template.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.DOCGEN_TEMPLATE_INVALID
+
+ template: str
+ reason: Literal["unreadable", "does_not_fit", "check_failed", "value_unsupported"]
+ finding: str
+
+
+class DocgenResourceRefusedParams(PipelexErrorParams):
+ """The parameters of `pipelex.docgen.resource_refused`.
+
+ The document names a file it may not read.
+
+ Attributes:
+ reason: Why the file was refused: a relative URL, a plain http URL, a data URL that does not decode,
+ or a font the engine does not know.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.DOCGEN_RESOURCE_REFUSED
+
+ reason: Literal["relative_url", "plain_http_url", "undecodable_data_url", "unknown_font"]
+
+
+class DocgenContentUnprintableParams(PipelexErrorParams):
+ """The parameters of `pipelex.docgen.content_unprintable`.
+
+ The document's content cannot be printed.
+
+ Attributes:
+ reason: What cannot be printed: an element taller than a page, an image that cannot be read, is too
+ large or is empty, or HTML past its size limit.
+ element: The element of the document that holds it.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.DOCGEN_CONTENT_UNPRINTABLE
+
+ reason: Literal["too_tall_for_page", "image_unreadable", "image_too_large", "image_empty", "html_too_large"]
+ element: str
+
+
+class DocgenPrintTimeoutParams(PipelexErrorParams):
+ """The parameters of `pipelex.docgen.print_timeout`.
+
+ Printing the document took too long.
+
+ Attributes:
+ limit: The time the print was allowed.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.DOCGEN_PRINT_TIMEOUT
+
+ limit: float = Field(ge=0)
+
+
+class DocgenTemplateWarningParams(PipelexErrorParams):
+ """The parameters of `pipelex.docgen.template_warning`.
+
+ The document template may be faulty.
+
+ Attributes:
+ template: The template.
+ finding: What the check found, about the method's own template.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.DOCGEN_TEMPLATE_WARNING
+
+ template: str
+ finding: str
+
+
+class SandboxUnavailableParams(PipelexErrorParams):
+ """The parameters of `pipelex.sandbox.unavailable`.
+
+ The Daytona sandbox could not be started.
+
+ Attributes:
+ backend: What could not be started: a Daytona sandbox, or the local subprocess that stands in for it.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.SANDBOX_UNAVAILABLE
+
+ backend: Literal["daytona", "subprocess"]
+
+
+class CodegenOutputConflictParams(PipelexErrorParams):
+ """The parameters of `pipelex.codegen.output_conflict`.
+
+ Codegen will not write there.
+
+ Attributes:
+ path: The path codegen would write.
+ reason: Why codegen will not write there: a file it does not own sits there, the path lies outside the
+ output root, is not a file, or is a symbolic link.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CODEGEN_OUTPUT_CONFLICT
+
+ path: str
+ reason: Literal["unowned_file", "escapes_root", "not_a_file", "symlink"]
+
+
+class CodegenLockInvalidParams(PipelexErrorParams):
+ """The parameters of `pipelex.codegen.lock_invalid`.
+
+ The codegen lock is unreadable.
+
+ Attributes:
+ file: The lock file.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CODEGEN_LOCK_INVALID
+
+ file: str
+
+
+class CodegenLockUnsupportedParams(PipelexErrorParams):
+ """The parameters of `pipelex.codegen.lock_unsupported`.
+
+ The codegen lock needs a newer Pipelex.
+
+ Attributes:
+ lock_version: The format version the lock was written in.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CODEGEN_LOCK_UNSUPPORTED
+
+ lock_version: int
+
+
+class CodegenLockNotFoundParams(PipelexErrorParams):
+ """The parameters of `pipelex.codegen.lock_not_found`.
+
+ No codegen lock in this directory.
+
+ Attributes:
+ path: The directory checked.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CODEGEN_LOCK_NOT_FOUND
+
+ path: str
+
+
+class CodegenDriftedParams(PipelexErrorParams):
+ """The parameters of `pipelex.codegen.drifted`.
+
+ The generated code has drifted from its method.
+
+ Attributes:
+ artifacts: The generated artifacts that no longer match.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CODEGEN_DRIFTED
+
+ artifacts: list[str]
+
+
+class ConnectorToolNotInToolsetParams(PipelexErrorParams):
+ """The parameters of `pipelex.connector.tool_not_in_toolset`.
+
+ The tool is not in the connector's toolset.
+
+ Attributes:
+ tool: The tool the model asked for.
+ available: The tools the toolset holds.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.CONNECTOR_TOOL_NOT_IN_TOOLSET
+
+ tool: str
+ available: list[str]
+
+
+class ErasureIncompleteParams(PipelexErrorParams):
+ """The parameters of `pipelex.erasure.incomplete`.
+
+ The erasure left data behind.
+
+ Attributes:
+ resource: What was being erased: a run, a method, a method's version or a workflow's history.
+ id: The id of what was being erased.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.ERASURE_INCOMPLETE
+
+ resource: Literal["run", "method", "method_version", "workflow"]
+ id: str
+
+
+class WebhookDeliveryFailedParams(PipelexErrorParams):
+ """The parameters of `pipelex.webhook.delivery_failed`.
+
+ A webhook was not delivered.
+
+ Attributes:
+ reason: Why the delivery failed: the receiver answered with an error status, or could not be reached.
+ receiver_status: The HTTP status the receiver answered with, when it answered.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.WEBHOOK_DELIVERY_FAILED
+
+ reason: Literal["http_status", "unreachable"]
+ receiver_status: int | None = None
+
+
+PIPELEX_ERROR_PARAMS: dict[PipelexErrorCode, type[PipelexErrorParams]] = {
+ PipelexErrorCode.BILLING_PLAN_LIMIT: BillingPlanLimitParams,
+ PipelexErrorCode.BILLING_CREDIT_EXHAUSTED: BillingCreditExhaustedParams,
+ PipelexErrorCode.BILLING_SUBSCRIPTION_CONFLICT: BillingSubscriptionConflictParams,
+ PipelexErrorCode.BILLING_PLAN_REFUSED: BillingPlanRefusedParams,
+ PipelexErrorCode.ORG_REQUIRED: OrgRequiredParams,
+ PipelexErrorCode.ORG_MISMATCH: OrgMismatchParams,
+ PipelexErrorCode.ORG_NOT_FOUND: OrgNotFoundParams,
+ PipelexErrorCode.ORG_NOT_MANAGEABLE: OrgNotManageableParams,
+ PipelexErrorCode.ORG_ALREADY_EXISTS: OrgAlreadyExistsParams,
+ PipelexErrorCode.ORG_PROMO_INVALID: OrgPromoInvalidParams,
+ PipelexErrorCode.ORG_PROMO_CREDIT_PENDING: OrgPromoCreditPendingParams,
+ PipelexErrorCode.CATALOG_NOT_FOUND: CatalogNotFoundParams,
+ PipelexErrorCode.CATALOG_NOT_PUBLISHED: CatalogNotPublishedParams,
+ PipelexErrorCode.CATALOG_BEING_DELETED: CatalogBeingDeletedParams,
+ PipelexErrorCode.CATALOG_DELETION_FAILED: CatalogDeletionFailedParams,
+ PipelexErrorCode.CATALOG_UPDATE_CONFLICT: CatalogUpdateConflictParams,
+ PipelexErrorCode.CATALOG_SELECTOR_INVALID: CatalogSelectorInvalidParams,
+ PipelexErrorCode.CATALOG_LINK_CONFLICT: CatalogLinkConflictParams,
+ PipelexErrorCode.RUN_ALREADY_EXISTS: RunAlreadyExistsParams,
+ PipelexErrorCode.STORAGE_URI_INVALID: StorageUriInvalidParams,
+ PipelexErrorCode.STORAGE_NOT_FOUND: StorageNotFoundParams,
+ PipelexErrorCode.STORAGE_UNAVAILABLE: StorageUnavailableParams,
+ PipelexErrorCode.STORAGE_NOT_CONFIGURED: StorageNotConfiguredParams,
+ PipelexErrorCode.STORAGE_GRANT_UNUSABLE: StorageGrantUnusableParams,
+ PipelexErrorCode.STORAGE_GRANT_MISMATCH: StorageGrantMismatchParams,
+ PipelexErrorCode.STORAGE_UPLOAD_REFUSED: StorageUploadRefusedParams,
+ PipelexErrorCode.SECURITY_RESERVED_KEY: SecurityReservedKeyParams,
+ PipelexErrorCode.SECURITY_RESULT_OUTSIDE_SCOPE: SecurityResultOutsideScopeParams,
+ PipelexErrorCode.CONFIG_INVALID: ConfigInvalidParams,
+ PipelexErrorCode.CONFIG_SYNTAX: ConfigSyntaxParams,
+ PipelexErrorCode.CONFIG_FILE_MISSING: ConfigFileMissingParams,
+ PipelexErrorCode.CONFIG_VARIABLE_MISSING: ConfigVariableMissingParams,
+ PipelexErrorCode.CONFIG_CREDENTIAL_MISSING: ConfigCredentialMissingParams,
+ PipelexErrorCode.CONFIG_CREDENTIAL_REFUSED: ConfigCredentialRefusedParams,
+ PipelexErrorCode.CONFIG_DEPENDENCY_MISSING: ConfigDependencyMissingParams,
+ PipelexErrorCode.PLUGIN_NOT_FOUND: PluginNotFoundParams,
+ PipelexErrorCode.PLUGIN_BROKEN: PluginBrokenParams,
+ PipelexErrorCode.PLUGIN_CONFLICT: PluginConflictParams,
+ PipelexErrorCode.PLUGIN_API_MISMATCH: PluginApiMismatchParams,
+ PipelexErrorCode.DEPLOYMENT_ORCHESTRATION_OVERRIDE_FORBIDDEN: DeploymentOrchestrationOverrideForbiddenParams,
+ PipelexErrorCode.DEPLOYMENT_CUSTOM_CODE_REQUIRES_SANDBOX: DeploymentCustomCodeRequiresSandboxParams,
+ PipelexErrorCode.DEPLOYMENT_PYTHON_STRUCTURES_REFUSED: DeploymentPythonStructuresRefusedParams,
+ PipelexErrorCode.DEPLOYMENT_TOKEN_CLAIMS_INVALID: DeploymentTokenClaimsInvalidParams,
+ PipelexErrorCode.DOCGEN_ENGINE_UNAVAILABLE: DocgenEngineUnavailableParams,
+ PipelexErrorCode.DOCGEN_TEMPLATE_INVALID: DocgenTemplateInvalidParams,
+ PipelexErrorCode.DOCGEN_RESOURCE_REFUSED: DocgenResourceRefusedParams,
+ PipelexErrorCode.DOCGEN_CONTENT_UNPRINTABLE: DocgenContentUnprintableParams,
+ PipelexErrorCode.DOCGEN_PRINT_TIMEOUT: DocgenPrintTimeoutParams,
+ PipelexErrorCode.DOCGEN_TEMPLATE_WARNING: DocgenTemplateWarningParams,
+ PipelexErrorCode.SANDBOX_UNAVAILABLE: SandboxUnavailableParams,
+ PipelexErrorCode.CODEGEN_OUTPUT_CONFLICT: CodegenOutputConflictParams,
+ PipelexErrorCode.CODEGEN_LOCK_INVALID: CodegenLockInvalidParams,
+ PipelexErrorCode.CODEGEN_LOCK_UNSUPPORTED: CodegenLockUnsupportedParams,
+ PipelexErrorCode.CODEGEN_LOCK_NOT_FOUND: CodegenLockNotFoundParams,
+ PipelexErrorCode.CODEGEN_DRIFTED: CodegenDriftedParams,
+ PipelexErrorCode.CONNECTOR_TOOL_NOT_IN_TOOLSET: ConnectorToolNotInToolsetParams,
+ PipelexErrorCode.ERASURE_INCOMPLETE: ErasureIncompleteParams,
+ PipelexErrorCode.WEBHOOK_DELIVERY_FAILED: WebhookDeliveryFailedParams,
+}
+"""The parameters model of every Pipelex code."""
diff --git a/pipelex/errors/registry/registry_document.py b/pipelex/errors/registry/registry_document.py
new file mode 100644
index 000000000..25242dad7
--- /dev/null
+++ b/pipelex/errors/registry/registry_document.py
@@ -0,0 +1,369 @@
+"""The typed model of an MTHDS error registry document, and the loader of Pipelex's own.
+
+An error registry, in the format the MTHDS standard defines (`spec/error-registry.md` on mthds.ai),
+declares one entry per error code: its title, the domain whose actor must act, its retry verdict,
+the step for that actor and for any other reader, its typed parameters, its templates and its HTTP
+status. The model below reads that format, the core registry's as well as an extension owner's, and
+refuses what the format's JSON Schema refuses: a member missing, a member it does not know, a value
+outside its closed lists, a member present where the format forbids it, and a member written as `null`.
+
+Pipelex's own registry, under the `pipelex` extension prefix, is authored in
+`pipelex-error-registry.yaml` beside this module and ships as its JSON snapshot,
+`pipelex-error-registry.json`, which :func:`load_pipelex_error_registry` reads.
+"""
+
+from __future__ import annotations
+
+import functools
+import importlib.resources
+import re
+from enum import StrEnum
+from typing import Any, Self, cast
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+PIPELEX_ERROR_REGISTRY_PACKAGE = "pipelex.errors.registry"
+PIPELEX_ERROR_REGISTRY_SNAPSHOT_NAME = "pipelex-error-registry.json"
+
+_SEGMENT_PATTERN = r"[a-z][a-z0-9_]*"
+_SEGMENT_REGEX = re.compile(rf"^{_SEGMENT_PATTERN}$")
+# An https URL with a lowercase host, an optional port and a path of non-empty segments, with no trailing slash, query or fragment.
+_BASE_URL_PATTERN = (
+ r"^https://[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?::[0-9]{1,5})?(?:/[A-Za-z0-9._~%!$&'()*+,;=:@-]+)*$"
+)
+
+
+class RegistryDomain(StrEnum):
+ """Who must act on a code: the closed list of `ProblemDomain` in the MTHDS protocol."""
+
+ INPUT = "input"
+ METHOD = "method"
+ ACCOUNT = "account"
+ OPERATOR = "operator"
+ RUNTIME = "runtime"
+
+
+class RegistryRetry(StrEnum):
+ """Whether repeating the operation can succeed: the closed list of `RetryVerdict` in the MTHDS protocol."""
+
+ NO = "no"
+ YES = "yes"
+ OUTCOME_UNKNOWN = "outcome_unknown"
+
+
+class RegistryStepKind(StrEnum):
+ """What the reader does next: the closed list of `StepKind` in the MTHDS protocol."""
+
+ RETRY = "retry"
+ WAIT = "wait"
+ READ_RUN = "read_run"
+ REFRESH = "refresh"
+ CHANGE_INPUT = "change_input"
+ CHANGE_METHOD = "change_method"
+ CHANGE_MODEL = "change_model"
+ CHECK_CREDENTIALS = "check_credentials"
+ REQUEST_ACCESS = "request_access"
+ CHECK_ACCOUNT = "check_account"
+ FIX_CONFIGURATION = "fix_configuration"
+ UPGRADE = "upgrade"
+ CONTACT_OWNER = "contact_owner"
+ REPORT = "report"
+
+
+class RegistryRaisedAs(StrEnum):
+ """How a code reaches a reader, which decides whether it has an HTTP status."""
+
+ PROBLEM = "problem"
+ WARNING = "warning"
+ CLIENT = "client"
+
+ @property
+ def has_status(self) -> bool:
+ """Whether a code raised this way carries an HTTP status: only a problem document does."""
+ match self:
+ case RegistryRaisedAs.PROBLEM:
+ return True
+ case RegistryRaisedAs.WARNING | RegistryRaisedAs.CLIENT:
+ return False
+
+
+class RegistryParamType(StrEnum):
+ """The type of a parameter: a scalar type, or `list` for a list of items of a scalar type."""
+
+ IDENTIFIER = "identifier"
+ INTEGER = "integer"
+ SECONDS = "seconds"
+ BYTES = "bytes"
+ SHA256 = "sha256"
+ ENUM = "enum"
+ CALLER_TEXT = "caller_text"
+ LIST = "list"
+
+ @property
+ def is_enum(self) -> bool:
+ """Whether a parameter of this type lists the values it may hold."""
+ match self:
+ case RegistryParamType.ENUM:
+ return True
+ case (
+ RegistryParamType.IDENTIFIER
+ | RegistryParamType.INTEGER
+ | RegistryParamType.SECONDS
+ | RegistryParamType.BYTES
+ | RegistryParamType.SHA256
+ | RegistryParamType.CALLER_TEXT
+ | RegistryParamType.LIST
+ ):
+ return False
+
+ @property
+ def is_list(self) -> bool:
+ """Whether a parameter of this type holds a list of items."""
+ match self:
+ case RegistryParamType.LIST:
+ return True
+ case (
+ RegistryParamType.IDENTIFIER
+ | RegistryParamType.INTEGER
+ | RegistryParamType.SECONDS
+ | RegistryParamType.BYTES
+ | RegistryParamType.SHA256
+ | RegistryParamType.ENUM
+ | RegistryParamType.CALLER_TEXT
+ ):
+ return False
+
+
+class _RegistryModel(BaseModel):
+ """The base of every part of a registry document: closed, so a member the format does not know is refused.
+
+ Strict, so that a value of another JSON type is refused rather than coerced, as the format's schema refuses
+ it: a status written `"402"`, or an `optional` written `"true"` or `1`, is not read as the integer or the
+ boolean. The closed lists stay lax fields, since a document names their members by their string values.
+
+ No member of the format may be null: a member the format makes optional is left out, never written as
+ `null`, and one it forbids in a case is absent in that case. The fields that model such a member are
+ `None` when it is absent, so an explicit `null` is refused before validation, as the format's schema
+ refuses it, rather than read as the member being absent.
+ """
+
+ model_config = ConfigDict(extra="forbid", frozen=True, strict=True)
+
+ @model_validator(mode="before")
+ @classmethod
+ def _refuse_null_members(cls, data: Any) -> Any:
+ if not isinstance(data, dict):
+ return data
+ members = cast("dict[Any, Any]", data)
+ for member, value in members.items():
+ if value is None:
+ msg = f"the member '{member}' is null, which the format never allows: leave it out instead"
+ raise ValueError(msg)
+ return members
+
+
+def _check_enum_values(*, param_type: RegistryParamType, values: list[str] | None) -> None:
+ """Refuse values on a type that is not an enum, and an enum without values, as the format's schema does."""
+ if param_type.is_enum:
+ if not values:
+ msg = "an enum lists its values"
+ raise ValueError(msg)
+ if len(set(values)) != len(values):
+ msg = "an enum lists each of its values once"
+ raise ValueError(msg)
+ for value in values:
+ if not _SEGMENT_REGEX.match(value):
+ msg = f"the enum value '{value}' is not a lowercase segment"
+ raise ValueError(msg)
+ elif values is not None:
+ msg = f"a parameter of type '{param_type}' lists no values"
+ raise ValueError(msg)
+
+
+class RegistryItemType(_RegistryModel):
+ """The type of each item of a list parameter."""
+
+ item_type: RegistryParamType = Field(alias="type", strict=False)
+ values: list[str] | None = None
+
+ @model_validator(mode="after")
+ def _validate_item_type(self) -> Self:
+ if self.item_type.is_list:
+ msg = "the item of a list is a scalar type, never a list"
+ raise ValueError(msg)
+ _check_enum_values(param_type=self.item_type, values=self.values)
+ return self
+
+
+class RegistryParam(_RegistryModel):
+ """One parameter of a code: a typed fact its sentences are written from."""
+
+ param_type: RegistryParamType = Field(alias="type", strict=False)
+ values: list[str] | None = None
+ items: RegistryItemType | None = None
+ description: str = Field(min_length=1, pattern=r"\S")
+ optional: bool = False
+ operator_only: bool = False
+
+ @model_validator(mode="after")
+ def _validate_param_type(self) -> Self:
+ _check_enum_values(param_type=self.param_type, values=self.values)
+ if self.param_type.is_list:
+ if self.items is None:
+ msg = "a list parameter declares the type of its items"
+ raise ValueError(msg)
+ elif self.items is not None:
+ msg = f"a parameter of type '{self.param_type}' declares no items"
+ raise ValueError(msg)
+ return self
+
+
+class RegistryStep(_RegistryModel):
+ """One next step: its closed kind and the template of its detail sentence."""
+
+ kind: RegistryStepKind = Field(strict=False)
+ detail: str = Field(min_length=1, pattern=r"\S")
+
+
+class RegistrySteps(_RegistryModel):
+ """The step for the domain's actor and the step for any other reader."""
+
+ actor: RegistryStep
+ other: RegistryStep
+
+
+class RegistryReference(_RegistryModel):
+ """A documentation page that defines the situation a code names, and the text to link it with.
+
+ The href is a path from the documentation's root. The format's schema lets a segment after the first hold
+ dots, which also lets one be `.` or `..` and climb out of the documentation (`x/../../README.md`); this model
+ refuses a segment made of dots alone, so a reference always names a page under the documentation's root.
+ """
+
+ title: str = Field(min_length=1, pattern=r"\S")
+ href: str = Field(pattern=r"^[a-z0-9_\-]+(/[a-z0-9_\-.]*[a-z0-9_\-][a-z0-9_\-.]*)*\.md(#[a-z0-9_\-]+)?$")
+
+
+class RegistryFamily(_RegistryModel):
+ """A family of codes and what its codes are about."""
+
+ family: str
+ description: str = Field(min_length=1, pattern=r"\S")
+
+
+class RegistryExtensionPrefix(_RegistryModel):
+ """A registered extension prefix, as the core registry lists it."""
+
+ prefix: str = Field(pattern=rf"^{_SEGMENT_PATTERN}$")
+ owner: str = Field(min_length=1, pattern=r"\S")
+ base_url: str = Field(pattern=_BASE_URL_PATTERN)
+
+
+class RegistryEntry(_RegistryModel):
+ """One code and everything a reader needs from it."""
+
+ code: str
+ title: str = Field(min_length=1, pattern=r"\S")
+ domain: RegistryDomain = Field(strict=False)
+ retry: RegistryRetry = Field(strict=False)
+ raised_as: RegistryRaisedAs = Field(strict=False)
+ status: int | None = Field(default=None, ge=400, le=599)
+ detail: str = Field(min_length=1, pattern=r"\S")
+ steps: RegistrySteps
+ params: dict[str, RegistryParam]
+ meaning: str = Field(min_length=1, pattern=r"\S")
+ what_to_do: str = Field(min_length=1, pattern=r"\S")
+ see: list[RegistryReference] | None = Field(default=None, min_length=1)
+
+ @field_validator("status", mode="before")
+ @classmethod
+ def _accept_an_integral_number(cls, value: Any) -> Any:
+ # JSON Schema's `integer` is any number with no fractional part, so the format accepts a status written
+ # `422.0`, which the strict field would refuse; a boolean, never a number to the schema, stays refused.
+ if isinstance(value, float) and value.is_integer():
+ return int(value)
+ return value
+
+ @model_validator(mode="after")
+ def _validate_entry(self) -> Self:
+ if self.raised_as.has_status:
+ if self.status is None:
+ msg = f"the code '{self.code}', raised as a problem, has an HTTP status"
+ raise ValueError(msg)
+ elif self.status is not None:
+ msg = f"the code '{self.code}', raised as '{self.raised_as}', has no HTTP status"
+ raise ValueError(msg)
+ for param_name in self.params:
+ if not _SEGMENT_REGEX.match(param_name):
+ msg = f"the parameter name '{param_name}' of the code '{self.code}' is not a lowercase segment"
+ raise ValueError(msg)
+ return self
+
+ @property
+ def family(self) -> str:
+ """The code's family: the code without its last segment."""
+ return self.code.rsplit(".", 1)[0]
+
+ @property
+ def page_path(self) -> str:
+ """The code's documentation page, from the documentation's root: one directory per segment but the last."""
+ return f"errors/{self.code.replace('.', '/')}.md"
+
+
+class ErrorRegistryDocument(_RegistryModel):
+ """An error registry: the core registry, or the registry of an extension prefix's owner."""
+
+ version: str = Field(pattern=r"^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.\-]+)?$")
+ prefix: str | None = Field(default=None, pattern=rf"^{_SEGMENT_PATTERN}$")
+ base_url: str = Field(pattern=_BASE_URL_PATTERN)
+ extension_prefixes: list[RegistryExtensionPrefix] | None = None
+ families: list[RegistryFamily] = Field(min_length=1)
+ codes: list[RegistryEntry] = Field(min_length=1)
+
+ @model_validator(mode="after")
+ def _validate_document(self) -> Self:
+ segment_count: int
+ if self.prefix is None:
+ if self.extension_prefixes is None:
+ msg = "a core registry, which has no prefix, lists the registered extension prefixes"
+ raise ValueError(msg)
+ segment_count = 2
+ else:
+ if self.extension_prefixes is not None:
+ msg = "an extension registry lists no extension prefixes"
+ raise ValueError(msg)
+ segment_count = 3
+ code_pattern = re.compile(rf"^{_SEGMENT_PATTERN}(\.{_SEGMENT_PATTERN}){{{segment_count - 1}}}$")
+ family_pattern = re.compile(rf"^{_SEGMENT_PATTERN}(\.{_SEGMENT_PATTERN}){{{segment_count - 2}}}$")
+ for family in self.families:
+ if not family_pattern.match(family.family):
+ msg = f"the family '{family.family}' does not have {segment_count - 1} segment(s)"
+ raise ValueError(msg)
+ for entry in self.codes:
+ if not code_pattern.match(entry.code):
+ msg = f"the code '{entry.code}' does not have {segment_count} segments"
+ raise ValueError(msg)
+ return self
+
+ def type_uri(self, *, code: str) -> str:
+ """The type URI of a code: the registry's base URL, a slash, then the whole code."""
+ return f"{self.base_url}/{code}"
+
+ def entry(self, *, code: str) -> RegistryEntry | None:
+ """The entry of a code, or `None` when this registry does not declare it."""
+ for registry_entry in self.codes:
+ if registry_entry.code == code:
+ return registry_entry
+ return None
+
+
+def read_pipelex_error_registry_snapshot_text() -> str:
+ """The text of Pipelex's error registry snapshot, as the package ships it."""
+ resource = importlib.resources.files(PIPELEX_ERROR_REGISTRY_PACKAGE).joinpath(PIPELEX_ERROR_REGISTRY_SNAPSHOT_NAME)
+ return resource.read_text(encoding="utf-8")
+
+
+def load_pipelex_error_registry() -> ErrorRegistryDocument:
+ """Pipelex's error registry, read once from the snapshot the package ships."""
+ return ErrorRegistryDocument.model_validate_json(read_pipelex_error_registry_snapshot_text())
diff --git a/pipelex/kit/agent_rules/codex_commands.md b/pipelex/kit/agent_rules/codex_commands.md
index 5345dcc8e..4f5838b52 100644
--- a/pipelex/kit/agent_rules/codex_commands.md
+++ b/pipelex/kit/agent_rules/codex_commands.md
@@ -81,10 +81,16 @@
.venv/bin/pipelex-dev generate-mthds-schema
```
- - **`generate-error-pages`**: Regenerate the per-class error reference pages under `docs/errors/` — one Markdown page per `PipelexError` subclass, which is what each error's `type_uri` dereferences to. Run after adding or renaming an error class. Pages a maintainer claims with a `<!-- pipelex:authored -->` marker are preserved across runs. Also available as `make generate-error-pages` (alias `make gep`).
+ - **`generate-error-registry`**: Write every file derived from the Pipelex error registry, `pipelex/errors/registry/pipelex-error-registry.yaml`: its JSON snapshot, its typed codes in `pipelex/errors/registry/pipelex_codes.py`, and one page per code under `docs/errors/`. Run after adding or changing a code in the registry, and after a version bump, since the snapshot carries the version. A source the format's schema, the typed model or the registry's rules refuse writes nothing. Also available as `make generate-error-registry` (alias `make ger`). See `docs/contribute/error-registry.md`.
```bash
- .venv/bin/pipelex-dev generate-error-pages
+ .venv/bin/pipelex-dev generate-error-registry
+ ```
+
+ - **`check-error-registry`**: Check the error registry against the MTHDS standard, and that every file derived from it is what `generate-error-registry` writes, without writing anything. Also available as `make check-error-registry` (alias `make cer`).
+
+ ```bash
+ .venv/bin/pipelex-dev check-error-registry
```
- **`generate-error-identity`**: Regenerate the committed `(error_type, title, type_uri)` snapshot of every `PipelexError` subclass at `tests/data/errors/error_identity.txt`. `error_type` is the bare class name and consumers outside this repo branch on it, so a rename is a silent wire break — the snapshot turns it into a reviewable diff, gated by `tests/unit/pipelex/errors/test_error_identity_snapshot.py`. Run after adding, renaming or removing an error class. Also available as `make generate-error-identity` (alias `make gei`).
diff --git a/pipelex/kit/agent_rules/commands.md b/pipelex/kit/agent_rules/commands.md
index 3b762187f..89a112303 100644
--- a/pipelex/kit/agent_rules/commands.md
+++ b/pipelex/kit/agent_rules/commands.md
@@ -10,4 +10,4 @@
- **`make test-ts-gates` (`ttg`) after touching anything under `pipelex/codegen/emitters/`, or moving the pinned prettier version.** `make agent-test` does not cover the TypeScript emission: the two gates that read the emitted TypeScript as TypeScript need a node toolchain and skip silently without one. This target provisions a pinned prettier and zod into `.ts-toolchain/` (npm, node >= 22.6) and makes those gates fail instead of skip, as CI does. See `docs/contribute/typescript-emission-gates.md`.
- **`make cleanderived`** when linters or pytest collection get confused after files were erased or moved.
- **`CLAUDE.md` and `AGENTS.md` are generated.** Edit the sources in `pipelex/kit/agent_rules/` (assembled per `pipelex/kit/index.toml`) and run `make rules`; `make check-rules` is the CI gate, and `make agent-check` does not include it.
-- **`pipelex-dev`** (`.venv/bin/pipelex-dev --help`) holds the internal generators, most with a `make` alias. `generate-mthds-schema` (`gms`) after modifying `mthds_schema_generator.py`. `generate-error-pages` (`gep`) and `generate-error-identity` (`gei`) after adding, renaming or removing an error class: consumers outside this repo branch on `error_type`, so a rename is a silent wire break that the committed snapshot turns into a reviewable diff. `refresh-graph-ui-sri --mthds-ui-version <v> [--elkjs-version <v>]` when bumping the pinned mthds-ui or elkjs. `trace-input-semantics` when changing the structure blueprint, the structure generator, the schema render or the contract builder (`docs/contribute/trace-input-semantics.md`). `generate-projection-corpus` to rewrite the fixture corpus committed byte-identically in `mthds-js` and `mthds-python` (`docs/contribute/generate-projection-corpus.md`). `drift` carries the drift-contract commands above.
+- **`pipelex-dev`** (`.venv/bin/pipelex-dev --help`) holds the internal generators, most with a `make` alias. `generate-mthds-schema` (`gms`) after modifying `mthds_schema_generator.py`. `generate-error-identity` (`gei`) after adding, renaming or removing an error class: consumers outside this repo branch on `error_type`, so a rename is a silent wire break that the committed snapshot turns into a reviewable diff. `generate-error-registry` (`ger`) after changing the error registry, `pipelex/errors/registry/pipelex-error-registry.yaml`, or bumping the version, and `check-error-registry` (`cer`) to check its snapshot, typed codes and pages without writing them (`docs/contribute/error-registry.md`). `refresh-graph-ui-sri --mthds-ui-version <v> [--elkjs-version <v>]` when bumping the pinned mthds-ui or elkjs. `trace-input-semantics` when changing the structure blueprint, the structure generator, the schema render or the contract builder (`docs/contribute/trace-input-semantics.md`). `generate-projection-corpus` to rewrite the fixture corpus committed byte-identically in `mthds-js` and `mthds-python` (`docs/contribute/generate-projection-corpus.md`). `drift` carries the drift-contract commands above.
diff --git a/pipelex/test_extras/mthds_corpus/exceptions.py b/pipelex/test_extras/mthds_corpus/exceptions.py
index 6c7e19cf1..b256c882a 100644
--- a/pipelex/test_extras/mthds_corpus/exceptions.py
+++ b/pipelex/test_extras/mthds_corpus/exceptions.py
@@ -2,7 +2,8 @@ class CorpusEntryError(Exception):
"""An entry directory that does not satisfy the layout the corpus contract pins.
Deliberately not a ``PipelexError``: error discovery excludes ``test_extras`` (see
- ``_FIXTURE_DIR_NAMES`` in the error-pages generator), so a ``PipelexError`` here would carry a
- ``type_uri`` pointing at a documentation page nothing generates, and a wire identity no
- snapshot gates. This failure is a malformed fixture directory, which is nobody's wire contract.
+ ``_FIXTURE_DIR_NAMES`` in ``pipelex/errors/error_class_discovery.py``), so a ``PipelexError``
+ here would carry a wire identity that no snapshot gates and a class-derived ``type_uri`` that
+ the uniqueness check never sees. This failure is a malformed fixture directory, which is
+ nobody's wire contract.
"""
diff --git a/subject_grants.toml b/subject_grants.toml
index eb53a8f53..bf930a8ab 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -3020,58 +3020,10 @@ rationale = "Verb-object: renders the stuff data; options stay keyword."
param = "stuff"
rationale = "Verb-object: renders the stuff; options stay keyword."
-["pipelex/errors/error_pages_generator.py::_group_by_subsystem"]
-param = "classes"
-rationale = "Verb-object: groups the error classes; single operand."
-
-["pipelex/errors/error_pages_generator.py::_humanize_subsystem"]
-param = "key"
-rationale = "Transforms the subsystem key into a human heading; single operand."
-
-["pipelex/errors/error_pages_generator.py::_is_production_subclass"]
+["pipelex/errors/error_class_discovery.py::_is_production_subclass"]
param = "cls"
rationale = "Predicate on the error class; single operand."
-["pipelex/errors/error_pages_generator.py::_parent_link"]
-param = "cls"
-rationale = "Derivation from the error class ('the parent link of cls'); single operand."
-
-["pipelex/errors/error_pages_generator.py::_remove_orphans"]
-param = "output_dir"
-rationale = "Verb-object: prunes the output dir; expected stems and report stay keyword."
-
-["pipelex/errors/error_pages_generator.py::_resolve_class_level_domain"]
-param = "cls"
-rationale = "Derivation from the error class; single operand."
-
-["pipelex/errors/error_pages_generator.py::_resolve_class_level_user_action"]
-param = "cls"
-rationale = "Derivation from the error class; single operand."
-
-["pipelex/errors/error_pages_generator.py::_short_docstring"]
-param = "cls"
-rationale = "Derivation from the error class; single operand."
-
-["pipelex/errors/error_pages_generator.py::_subsystem_key"]
-param = "cls"
-rationale = "Derivation from the error class; single operand."
-
-["pipelex/errors/error_pages_generator.py::has_authored_marker"]
-param = "content"
-rationale = "Predicate on the page content; single operand."
-
-["pipelex/errors/error_pages_generator.py::page_slug"]
-param = "cls"
-rationale = "Derivation from the error class ('the page slug of cls'); single operand."
-
-["pipelex/errors/error_pages_generator.py::render_error_page"]
-param = "cls"
-rationale = "Verb-object: renders the page for the error class; single operand."
-
-["pipelex/errors/error_pages_generator.py::render_index_page"]
-param = "by_subsystem"
-rationale = "Verb-object: renders the index from the subsystem grouping; single operand."
-
["pipelex/fix_ops/applier.py::_as_tomlkit_value"]
param = "value"
rationale = "Single-operand conversion of the value."
diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txt
index 93a7f72f5..eaae7c828 100644
--- a/tests/data/errors/error_identity.txt
+++ b/tests/data/errors/error_identity.txt
@@ -90,6 +90,7 @@ EmptyMethodTreeError | Empty method tree | https://docs.pipelex.com/latest/error
EntryPipeAmbiguousError | Entry pipe ambiguous | https://docs.pipelex.com/latest/errors/entry-pipe-ambiguous-error/
EntryPipeNotFoundError | Entry pipe not found | https://docs.pipelex.com/latest/errors/entry-pipe-not-found-error/
EnvVarNotFoundError | Environment variable not set | https://docs.pipelex.com/latest/errors/env-var-not-found-error/
+ErrorRegistryError | Error registry | https://docs.pipelex.com/latest/errors/error-registry-error/
EventLogError | Event log | https://docs.pipelex.com/latest/errors/event-log-error/
EventLogReadError | Event log read | https://docs.pipelex.com/latest/errors/event-log-read-error/
EventLogSchemaMismatchError | Event log schema mismatch | https://docs.pipelex.com/latest/errors/event-log-schema-mismatch-error/
diff --git a/tests/unit/pipelex/errors/registry/conftest.py b/tests/unit/pipelex/errors/registry/conftest.py
new file mode 100644
index 000000000..d87ff44ad
--- /dev/null
+++ b/tests/unit/pipelex/errors/registry/conftest.py
@@ -0,0 +1,33 @@
+"""Shared fixtures for the error registry tests: the committed registry, the standard's schema and the core registry."""
+
+from __future__ import annotations
+
+import copy
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+from pipelex.cli.dev_cli.commands.error_registry.registry_outputs import load_core_registry
+from pipelex.cli.dev_cli.commands.error_registry.registry_source import STANDARD_SCHEMA_PATH, load_composed_document, load_json_file
+
+if TYPE_CHECKING:
+ from pipelex.errors.registry.registry_document import ErrorRegistryDocument
+
+
+def composed_document() -> dict[str, Any]:
+ """A fresh copy of the registry document composed from the committed source, safe to mutate."""
+ return copy.deepcopy(load_composed_document())
+
+
+def standard_schema() -> dict[str, Any]:
+ """The registry format's JSON Schema, vendored from the standard."""
+ schema: dict[str, Any] = load_json_file(path=STANDARD_SCHEMA_PATH)
+ return schema
+
+
+def core_registry() -> ErrorRegistryDocument:
+ """The MTHDS core registry, from the vendored snapshot."""
+ return load_core_registry()
diff --git a/tests/unit/pipelex/errors/registry/test_error_registry_checks.py b/tests/unit/pipelex/errors/registry/test_error_registry_checks.py
new file mode 100644
index 000000000..8a08e81b8
--- /dev/null
+++ b/tests/unit/pipelex/errors/registry/test_error_registry_checks.py
@@ -0,0 +1,464 @@
+from __future__ import annotations
+
+import copy
+import json
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from pydantic import ValidationError as PydanticValidationError
+
+from pipelex.cli.dev_cli.commands.error_registry.exceptions import ErrorRegistryError
+from pipelex.cli.dev_cli.commands.error_registry.registry_checks import (
+ model_errors,
+ reference_errors,
+ registry_errors,
+ schema_errors,
+ semantic_errors,
+)
+from pipelex.cli.dev_cli.commands.error_registry.registry_source import DOCS_DIR, compose_registry_document, load_registry_source
+from pipelex.errors.registry.registry_document import ErrorRegistryDocument, RegistryReference
+
+if TYPE_CHECKING:
+ from collections.abc import Callable
+ from pathlib import Path
+
+WHERE = "registry"
+
+# The members the format requires of every entry.
+REQUIRED_ENTRY_MEMBERS = ["code", "title", "domain", "retry", "raised_as", "detail", "steps", "params", "meaning", "what_to_do"]
+
+
+def _entry(document: dict[str, Any], code: str) -> dict[str, Any]:
+ for entry in document["codes"]:
+ if entry["code"] == code:
+ found: dict[str, Any] = entry
+ return found
+ msg = f"no entry {code}"
+ raise KeyError(msg)
+
+
+def _set_member(code: str, member: str, value: Any) -> Callable[[dict[str, Any]], None]:
+ def mutate(document: dict[str, Any]) -> None:
+ _entry(document, code)[member] = value
+
+ return mutate
+
+
+def _add_param(code: str, name: str, param: dict[str, Any]) -> Callable[[dict[str, Any]], None]:
+ def mutate(document: dict[str, Any]) -> None:
+ _entry(document, code)["params"][name] = param
+
+ return mutate
+
+
+def _set_document_member(member: str, value: Any) -> Callable[[dict[str, Any]], None]:
+ def mutate(document: dict[str, Any]) -> None:
+ document[member] = value
+
+ return mutate
+
+
+def _set_actor_detail(code: str, detail: str) -> Callable[[dict[str, Any]], None]:
+ def mutate(document: dict[str, Any]) -> None:
+ _entry(document, code)["steps"]["actor"]["detail"] = detail
+
+ return mutate
+
+
+def _duplicate_first_code(document: dict[str, Any]) -> None:
+ document["codes"].append(copy.deepcopy(document["codes"][0]))
+
+
+def _add_unused_family(document: dict[str, Any]) -> None:
+ document["families"].append({"family": "pipelex.unused", "description": "A family no code uses."})
+
+
+def _add_family_outside_prefix(document: dict[str, Any]) -> None:
+ document["families"].append({"family": "other.billing", "description": "A family outside the prefix."})
+ entry = copy.deepcopy(_entry(document, "pipelex.billing.credit_exhausted"))
+ entry["code"] = "other.billing.credit_exhausted"
+ document["codes"].append(entry)
+
+
+def _move_code_to_undeclared_family(document: dict[str, Any]) -> None:
+ _entry(document, "pipelex.billing.credit_exhausted")["code"] = "pipelex.nowhere.credit_exhausted"
+
+
+def _add_codes(families: list[str], codes: list[str]) -> Callable[[dict[str, Any]], None]:
+ """Declare families and codes, each code a copy of an existing entry, to test names derived from the codes."""
+
+ def mutate(document: dict[str, Any]) -> None:
+ declared = {family["family"] for family in document["families"]}
+ for family in families:
+ if family not in declared:
+ document["families"].append({"family": family, "description": "A family for the test."})
+ for code in codes:
+ entry = copy.deepcopy(_entry(document, "pipelex.storage.unavailable"))
+ entry["code"] = code
+ document["codes"].append(entry)
+
+ return mutate
+
+
+def _remove_status_of_a_problem(document: dict[str, Any]) -> None:
+ del _entry(document, "pipelex.billing.credit_exhausted")["status"]
+
+
+class TestErrorRegistryChecks:
+ def test_the_committed_registry_passes_every_check(
+ self, composed_document: dict[str, Any], standard_schema: dict[str, Any], core_registry: ErrorRegistryDocument
+ ) -> None:
+ """The committed source, composed with Pipelex's version, has no fault in any pass."""
+ errors = registry_errors(document=composed_document, schema=standard_schema, core=core_registry, docs_dir=DOCS_DIR, where=WHERE)
+ assert errors == []
+ registry = ErrorRegistryDocument.model_validate(composed_document)
+ assert registry.prefix == "pipelex"
+ assert registry.base_url == "https://docs.pipelex.com/errors"
+ assert all(entry.code.startswith("pipelex.") for entry in registry.codes)
+
+ @pytest.mark.parametrize("member", REQUIRED_ENTRY_MEMBERS)
+ def test_an_entry_missing_a_member_is_refused_by_the_schema_and_the_typed_model(
+ self, composed_document: dict[str, Any], standard_schema: dict[str, Any], member: str
+ ) -> None:
+ """Every entry declares every member its code needs: removing one is refused by both readers."""
+ del _entry(composed_document, "pipelex.storage.unavailable")[member]
+ found_by_schema = schema_errors(document=composed_document, schema=standard_schema, where=WHERE)
+ assert any(f"'{member}' is a required property" in error for error in found_by_schema), found_by_schema
+ registry, found_by_model = model_errors(document=composed_document, where=WHERE)
+ assert registry is None
+ assert found_by_model
+
+ @pytest.mark.parametrize(
+ ("topic", "mutate"),
+ [
+ ("a domain outside the closed list", _set_member("pipelex.storage.unavailable", "domain", "caller")),
+ ("a retry verdict outside the closed list", _set_member("pipelex.storage.unavailable", "retry", "maybe")),
+ ("an empty step detail", _set_actor_detail("pipelex.storage.unavailable", "")),
+ ("a member the format does not know", _set_member("pipelex.storage.unavailable", "severity", "high")),
+ ("a status on a warning", _set_member("pipelex.docgen.template_warning", "status", 422)),
+ ("a status on a client code", _set_member("pipelex.catalog.link_conflict", "status", 409)),
+ ("a problem without a status", _remove_status_of_a_problem),
+ ("a status outside the HTTP error range", _set_member("pipelex.storage.unavailable", "status", 302)),
+ ("an empty title", _set_member("pipelex.storage.unavailable", "title", "")),
+ ("an enum without values", _add_param("pipelex.storage.unavailable", "kind", {"type": "enum", "description": "A kind."})),
+ ("a list without items", _add_param("pipelex.storage.unavailable", "names", {"type": "list", "description": "Names."})),
+ (
+ "values on an identifier",
+ _add_param("pipelex.storage.unavailable", "name", {"type": "identifier", "values": ["one"], "description": "A name."}),
+ ),
+ ("an unknown parameter type", _add_param("pipelex.storage.unavailable", "size", {"type": "float", "description": "A size."})),
+ (
+ "a parameter name that is not a segment",
+ _add_param("pipelex.storage.unavailable", "Name", {"type": "identifier", "description": "A."}),
+ ),
+ (
+ "a reference to a page with uppercase letters",
+ _set_member("pipelex.storage.unavailable", "see", [{"title": "PipeDocGen", "href": "building-methods/PipeDocGen.md"}]),
+ ),
+ ("an empty list of references", _set_member("pipelex.storage.unavailable", "see", [])),
+ ("a code with two segments only", _set_member("pipelex.storage.unavailable", "code", "pipelex.unavailable")),
+ ("a null status on a warning", _set_member("pipelex.docgen.template_warning", "status", None)),
+ ("a null status on a client code", _set_member("pipelex.catalog.link_conflict", "status", None)),
+ ("a null status on a problem", _set_member("pipelex.storage.unavailable", "status", None)),
+ ("a null list of references", _set_member("pipelex.storage.unavailable", "see", None)),
+ (
+ "null items on a parameter that is not a list",
+ _add_param("pipelex.storage.unavailable", "name", {"type": "identifier", "items": None, "description": "A name."}),
+ ),
+ (
+ "null values on a parameter that is not an enum",
+ _add_param("pipelex.storage.unavailable", "name", {"type": "identifier", "values": None, "description": "A name."}),
+ ),
+ (
+ "null values on a list item that is not an enum",
+ _add_param(
+ "pipelex.storage.unavailable",
+ "names",
+ {"type": "list", "items": {"type": "identifier", "values": None}, "description": "Names."},
+ ),
+ ),
+ (
+ "a null optional mark",
+ _add_param("pipelex.storage.unavailable", "name", {"type": "identifier", "optional": None, "description": "A name."}),
+ ),
+ ("a null list of extension prefixes", _set_document_member("extension_prefixes", None)),
+ ("a null prefix", _set_document_member("prefix", None)),
+ ("a status written as a string", _set_member("pipelex.storage.unavailable", "status", "503")),
+ ("a status written as a boolean", _set_member("pipelex.storage.unavailable", "status", True)),
+ ("a status with a fractional part", _set_member("pipelex.storage.unavailable", "status", 503.5)),
+ (
+ "an optional mark written as a string",
+ _add_param("pipelex.storage.unavailable", "name", {"type": "identifier", "optional": "true", "description": "A name."}),
+ ),
+ (
+ "an optional mark written as an integer",
+ _add_param("pipelex.storage.unavailable", "name", {"type": "identifier", "optional": 1, "description": "A name."}),
+ ),
+ (
+ "an operator-only mark written as a string",
+ _add_param("pipelex.storage.unavailable", "name", {"type": "identifier", "operator_only": "yes", "description": "A name."}),
+ ),
+ (
+ "an enum value written as a number",
+ _add_param("pipelex.storage.unavailable", "kind", {"type": "enum", "values": [1], "description": "A kind."}),
+ ),
+ ("a retry verdict written as a boolean", _set_member("pipelex.storage.unavailable", "retry", False)),
+ ],
+ )
+ def test_a_malformed_entry_is_refused_by_the_schema_and_the_typed_model(
+ self,
+ composed_document: dict[str, Any],
+ standard_schema: dict[str, Any],
+ topic: str,
+ mutate: Callable[[dict[str, Any]], None],
+ ) -> None:
+ """What the format's schema refuses, the typed model refuses too, so the model never accepts a document the schema would not."""
+ mutate(composed_document)
+ assert schema_errors(document=composed_document, schema=standard_schema, where=WHERE), f"the schema accepted {topic}"
+ registry, found_by_model = model_errors(document=composed_document, where=WHERE)
+ assert registry is None, f"the typed model accepted {topic}"
+ assert found_by_model
+
+ def test_a_status_written_as_an_integral_number_is_accepted_by_both(
+ self, composed_document: dict[str, Any], standard_schema: dict[str, Any]
+ ) -> None:
+ """JSON Schema's integer is any number with no fractional part, so the strict model reads `503.0` as the status 503."""
+ _entry(composed_document, "pipelex.storage.unavailable")["status"] = 503.0
+ assert schema_errors(document=composed_document, schema=standard_schema, where=WHERE) == []
+ registry, found_by_model = model_errors(document=composed_document, where=WHERE)
+ assert found_by_model == []
+ assert registry is not None
+ entry = registry.entry(code="pipelex.storage.unavailable")
+ assert entry is not None
+ assert entry.status == 503
+
+ def test_the_snapshot_reader_refuses_a_null_member(self, composed_document: dict[str, Any]) -> None:
+ """The public loader reads JSON through the typed model alone, so the model refuses a null as the schema does, naming it."""
+ _entry(composed_document, "pipelex.docgen.template_warning")["status"] = None
+ with pytest.raises(PydanticValidationError, match="the member 'status' is null"):
+ ErrorRegistryDocument.model_validate_json(json.dumps(composed_document))
+
+ def test_a_step_kind_outside_the_closed_list_is_refused(self, composed_document: dict[str, Any], standard_schema: dict[str, Any]) -> None:
+ """The step kinds are the protocol's closed list."""
+ _entry(composed_document, "pipelex.storage.unavailable")["steps"]["actor"]["kind"] = "shout"
+ assert schema_errors(document=composed_document, schema=standard_schema, where=WHERE)
+ registry, _found = model_errors(document=composed_document, where=WHERE)
+ assert registry is None
+
+ @pytest.mark.parametrize(
+ ("mutate", "expected"),
+ [
+ (_duplicate_first_code, "the code is declared twice"),
+ (_move_code_to_undeclared_family, "its family pipelex.nowhere is not declared under families"),
+ (_add_unused_family, "the family pipelex.unused is declared but no code belongs to it"),
+ (_add_family_outside_prefix, "the family other.billing does not start with the prefix pipelex"),
+ (
+ _set_member("pipelex.storage.unavailable", "detail", "The storage failed on {nothing}."),
+ "detail names {nothing}, which the code does not declare",
+ ),
+ (
+ _set_member("pipelex.catalog.not_found", "detail", "No version {version} here."),
+ "detail names {version}, which is optional and may be absent",
+ ),
+ (
+ _set_member("pipelex.config.invalid", "detail", "The file '{file}' is invalid."),
+ "detail names the operator-only {file}, which a caller may read",
+ ),
+ (
+ _set_member("pipelex.config.invalid", "detail", "The runtime's configuration is {invalid!r}."),
+ "detail: placeholder {invalid} carries a format specification",
+ ),
+ (
+ _set_member("pipelex.storage.unavailable", "see", [{"title": "Nowhere", "href": "nowhere/page.md"}]),
+ "see names nowhere/page.md, which the documentation does not hold",
+ ),
+ (
+ _set_member("pipelex.storage.unavailable", "meaning", "Not `input.nonexistent`, but this."),
+ "names `input.nonexistent`, which the core registry",
+ ),
+ (
+ _set_member("pipelex.storage.unavailable", "what_to_do", "Read `pipelex.storage.vanished` first."),
+ "names `pipelex.storage.vanished`, which this registry does not declare",
+ ),
+ (
+ _add_param("pipelex.storage.unavailable", "class", {"type": "identifier", "description": "A class."}),
+ "the parameter class is a Python keyword",
+ ),
+ (
+ _add_param("pipelex.storage.unavailable", "model_dump", {"type": "identifier", "description": "A dump."}),
+ "the parameter model_dump names an attribute of the generated parameters model",
+ ),
+ (
+ _add_param("pipelex.storage.unavailable", "code", {"type": "identifier", "description": "A code."}),
+ "the parameter code names an attribute of the generated parameters model",
+ ),
+ (
+ _add_param("pipelex.storage.unavailable", "int", {"type": "integer", "optional": True, "description": "A number."}),
+ "the parameter int would shadow the builtin int the generated annotations name",
+ ),
+ (
+ _add_codes(["pipelex.run_job", "pipelex.run"], ["pipelex.run_job.failed", "pipelex.run.job_failed"]),
+ "the codes pipelex.run_job.failed, pipelex.run.job_failed generate the same PipelexErrorCode member, RUN_JOB_FAILED",
+ ),
+ (
+ _add_codes(["pipelex.run_job", "pipelex.run"], ["pipelex.run_job.failed", "pipelex.run.job_failed"]),
+ "the codes pipelex.run_job.failed, pipelex.run.job_failed generate the same parameters model, RunJobFailedParams",
+ ),
+ (
+ _add_codes(["pipelex.run_job", "pipelex.run__job"], ["pipelex.run_job.failed", "pipelex.run__job.failed"]),
+ "the codes pipelex.run_job.failed, pipelex.run__job.failed generate the same parameters model, RunJobFailedParams",
+ ),
+ (
+ _add_codes(["pipelex.pipelex"], ["pipelex.pipelex.error"]),
+ "pipelex.pipelex.error: its parameters model would be named PipelexErrorParams, which the generated module already defines",
+ ),
+ (
+ _set_member("pipelex.storage.unavailable", "title", "The storage at C:\\data failed"),
+ "pipelex.storage.unavailable: title cannot be written into a docstring as it stands",
+ ),
+ (
+ _add_param("pipelex.storage.unavailable", "name", {"type": "identifier", "description": 'A name, such as "acme"'}),
+ "pipelex.storage.unavailable: params.name.description cannot be written into a docstring as it stands",
+ ),
+ (
+ _add_param(
+ "pipelex.storage.unavailable",
+ "kind",
+ {"type": "enum", "values": [f"a_rather_long_value_{index}" for index in range(8)], "description": "A kind."},
+ ),
+ "pipelex.storage.unavailable: the field of the parameter kind runs past 150 characters",
+ ),
+ ],
+ )
+ def test_a_rule_beyond_the_schema_is_enforced(
+ self,
+ composed_document: dict[str, Any],
+ standard_schema: dict[str, Any],
+ core_registry: ErrorRegistryDocument,
+ mutate: Callable[[dict[str, Any]], None],
+ expected: str,
+ ) -> None:
+ """The rules a JSON Schema cannot state are refused, each with the code it found the fault in."""
+ mutate(composed_document)
+ assert schema_errors(document=composed_document, schema=standard_schema, where=WHERE) == []
+ errors = registry_errors(document=composed_document, schema=standard_schema, core=core_registry, docs_dir=DOCS_DIR, where=WHERE)
+ assert any(expected in error for error in errors), errors
+
+ def test_an_operator_only_parameter_is_named_only_in_the_actor_step_of_an_operator_code(
+ self, composed_document: dict[str, Any], standard_schema: dict[str, Any], core_registry: ErrorRegistryDocument
+ ) -> None:
+ """The actor of a runtime code is whoever made the call, who may not read an operator-only parameter."""
+ entry = _entry(composed_document, "pipelex.storage.unavailable")
+ entry["params"]["bucket"] = {"type": "identifier", "operator_only": True, "description": "The bucket."}
+ entry["steps"]["actor"]["detail"] = "Check the bucket '{bucket}'."
+ errors = registry_errors(document=composed_document, schema=standard_schema, core=core_registry, docs_dir=DOCS_DIR, where=WHERE)
+ assert any("steps.actor.detail names the operator-only {bucket}" in error for error in errors), errors
+ config_entry = _entry(composed_document, "pipelex.config.invalid")
+ assert "{setting}" in config_entry["steps"]["actor"]["detail"]
+
+ def test_the_prefix_must_be_registered_in_the_core_registry_under_the_same_base_url(
+ self, composed_document: dict[str, Any], core_registry: ErrorRegistryDocument
+ ) -> None:
+ """The core registry registers the prefix, and the pages are published under the base URL it names."""
+ registry = ErrorRegistryDocument.model_validate(composed_document)
+ unregistered_core = core_registry.model_copy(update={"extension_prefixes": []})
+ errors = semantic_errors(registry=registry, core=unregistered_core, docs_dir=DOCS_DIR, where=WHERE)
+ assert any("does not register the prefix pipelex" in error for error in errors), errors
+ elsewhere = registry.model_copy(update={"base_url": "https://errors.pipelex.com/codes"})
+ errors = semantic_errors(registry=elsewhere, core=core_registry, docs_dir=DOCS_DIR, where=WHERE)
+ assert any("is not the https://docs.pipelex.com/errors that the core registry" in error for error in errors), errors
+
+ def test_a_duplicate_yaml_key_is_refused(self, tmp_path: Path) -> None:
+ """A YAML loader would keep the second of two equal keys silently; the registry's loader refuses it."""
+ source_path = tmp_path / "registry.yaml"
+ source_path.write_text("prefix: pipelex\nprefix: acme\n", encoding="utf-8")
+ with pytest.raises(ErrorRegistryError, match="duplicate key 'prefix'"):
+ load_registry_source(path=source_path)
+
+ @pytest.mark.parametrize(
+ ("topic", "text"),
+ [
+ ("a sequence key at the top", "? [a, b]\n: value\n"),
+ ("a mapping key in a nested mapping", "codes:\n ? {a: 1}\n : value\n"),
+ ],
+ )
+ def test_a_complex_yaml_key_is_refused_as_a_load_fault(self, tmp_path: Path, topic: str, text: str) -> None:
+ """A sequence or a mapping written as a key is unhashable, so the loader refuses it as a fault rather than raise a TypeError."""
+ source_path = tmp_path / "registry.yaml"
+ source_path.write_text(text, encoding="utf-8")
+ with pytest.raises(ErrorRegistryError, match="found a key that is a sequence or a mapping") as exc_info:
+ load_registry_source(path=source_path)
+ assert "registry.yaml" in str(exc_info.value), topic
+
+ @pytest.mark.parametrize(
+ "href",
+ [
+ "building-methods/../../changelog.md",
+ "under-the-hood/./error-model.md",
+ "under-the-hood/../under-the-hood/error-model.md#anchor",
+ ],
+ )
+ def test_a_see_reference_with_a_dot_segment_is_refused_by_the_typed_model(
+ self, composed_document: dict[str, Any], standard_schema: dict[str, Any], href: str
+ ) -> None:
+ """The format's schema lets a segment be `.` or `..`, which climbs out of the documentation; the typed model refuses it."""
+ _entry(composed_document, "pipelex.storage.unavailable")["see"] = [{"title": "Elsewhere", "href": href}]
+ assert schema_errors(document=composed_document, schema=standard_schema, where=WHERE) == []
+ registry, found_by_model = model_errors(document=composed_document, where=WHERE)
+ assert registry is None
+ assert any("codes/" in error and "see/0/href" in error for error in found_by_model), found_by_model
+
+ @pytest.mark.parametrize(
+ ("topic", "href", "expected"),
+ [
+ ("a page the documentation holds", "guide/page.md", None),
+ ("a page the documentation holds, with an anchor", "guide/page.md#a-section", None),
+ ("the index the registry generates", "errors/index.md", None),
+ ("a code page the registry generates, not on disk yet", "errors/pipelex/fresh/code.md", None),
+ ("a page on disk under errors/ the registry no longer generates", "errors/pipelex/old/gone.md", "which this registry does not generate"),
+ ("a page the documentation does not hold", "guide/missing.md", "which the documentation does not hold"),
+ ("a page that climbs out of the documentation", "guide/../../outside.md", "which lies outside the documentation"),
+ ("a symbolic link out of the documentation", "escape.md", "which lies outside the documentation"),
+ ],
+ )
+ def test_a_see_reference_names_a_page_of_the_documentation(
+ self, composed_document: dict[str, Any], tmp_path: Path, topic: str, href: str, expected: str | None
+ ) -> None:
+ """A reference names a page the documentation holds or one this registry generates, and never one outside the documentation."""
+ docs_dir = tmp_path / "docs"
+ for page in ("guide/page.md", "errors/pipelex/old/gone.md"):
+ (docs_dir / page).parent.mkdir(parents=True, exist_ok=True)
+ (docs_dir / page).write_text("page", encoding="utf-8")
+ (tmp_path / "outside.md").write_text("outside", encoding="utf-8")
+ (docs_dir / "escape.md").symlink_to(tmp_path / "outside.md")
+ registry = ErrorRegistryDocument.model_validate(composed_document)
+ entry = registry.entry(code="pipelex.storage.unavailable")
+ assert entry is not None
+ # Built without validation, as the typed model would refuse the `..` segment before this check ever runs.
+ referencing = entry.model_copy(update={"see": [RegistryReference.model_construct(title="A page", href=href)]})
+ generated_pages = frozenset({"errors/index.md", "errors/pipelex/fresh/code.md"})
+ errors = reference_errors(entry=referencing, here=WHERE, docs_dir=docs_dir, generated_pages=generated_pages)
+ if expected is None:
+ assert errors == [], topic
+ else:
+ assert errors == [f"{WHERE}: see names {href.split('#', 1)[0]}, {expected}"], topic
+
+ def test_a_see_reference_may_name_the_page_of_a_code_not_yet_generated(
+ self, composed_document: dict[str, Any], standard_schema: dict[str, Any], core_registry: ErrorRegistryDocument
+ ) -> None:
+ """A new code may name another new code's page, which the generator writes from this same registry."""
+ _add_codes(["pipelex.fresh"], ["pipelex.fresh.first", "pipelex.fresh.second"])(composed_document)
+ assert not (DOCS_DIR / "errors" / "pipelex" / "fresh" / "second.md").exists()
+ _entry(composed_document, "pipelex.fresh.first")["see"] = [{"title": "Second", "href": "errors/pipelex/fresh/second.md"}]
+ errors = registry_errors(document=composed_document, schema=standard_schema, core=core_registry, docs_dir=DOCS_DIR, where=WHERE)
+ assert errors == []
+ _entry(composed_document, "pipelex.fresh.first")["see"] = [{"title": "Third", "href": "errors/pipelex/fresh/third.md"}]
+ errors = registry_errors(document=composed_document, schema=standard_schema, core=core_registry, docs_dir=DOCS_DIR, where=WHERE)
+ assert errors == [f"{WHERE}: pipelex.fresh.first: see names errors/pipelex/fresh/third.md, which this registry does not generate"]
+
+ def test_a_source_that_writes_its_own_version_is_refused(self) -> None:
+ """The version is Pipelex's, from pyproject.toml, and written nowhere else."""
+ with pytest.raises(ErrorRegistryError, match="writes a version"):
+ compose_registry_document(source={"version": "1.0.0", "prefix": "pipelex"}, version="0.87.0")
+ composed = compose_registry_document(source={"prefix": "pipelex"}, version="0.87.0")
+ assert list(composed) == ["version", "prefix"]
diff --git a/tests/unit/pipelex/errors/registry/test_error_registry_outputs.py b/tests/unit/pipelex/errors/registry/test_error_registry_outputs.py
new file mode 100644
index 000000000..f22702ac6
--- /dev/null
+++ b/tests/unit/pipelex/errors/registry/test_error_registry_outputs.py
@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import io
+import json
+import re
+from typing import TYPE_CHECKING, Any
+
+import pytest
+import typer
+from rich.console import Console
+
+from pipelex.cli.dev_cli.commands.error_registry import error_registry_cmd, registry_outputs
+from pipelex.cli.dev_cli.commands.error_registry.error_registry_cmd import (
+ check_error_registry_cmd,
+ generate_error_registry_cmd,
+ write_error_type_redirects_cmd,
+)
+from pipelex.cli.dev_cli.commands.error_registry.pages_generator import generated_page_paths, render_pages
+from pipelex.cli.dev_cli.commands.error_registry.registry_outputs import check_error_registry, orphan_pages, source_errors
+from pipelex.cli.dev_cli.commands.error_registry.registry_source import (
+ DOCS_DIR,
+ REGISTRY_SNAPSHOT_PATH,
+ compose_registry_document,
+ load_registry_source,
+ load_vendored_record,
+ read_pipelex_version,
+ read_registry_version,
+ vendored_file_errors,
+)
+from pipelex.cli.dev_cli.commands.error_registry.registry_version import registry_version_of
+from pipelex.errors.registry.pipelex_codes import PIPELEX_ERROR_PARAMS, PipelexErrorCode
+from pipelex.errors.registry.registry_document import load_pipelex_error_registry, read_pipelex_error_registry_snapshot_text
+
+if TYPE_CHECKING:
+ from collections.abc import Callable
+ from pathlib import Path
+
+ from pytest_mock import MockerFixture
+
+REMEDY = "run `make generate-error-registry` to rewrite them from pipelex/errors/registry/pipelex-error-registry.yaml"
+
+
+class TestErrorRegistryOutputs:
+ def test_every_derived_file_is_what_the_generator_writes(self) -> None:
+ """The snapshot, the typed codes and the pages are exactly what the generator writes from the source, with no stray page."""
+ checked, errors = check_error_registry()
+ assert checked is not None, errors
+ assert errors == [], f"the error registry's derived files are stale: {REMEDY}:\n" + "\n".join(errors)
+
+ def test_the_check_command_passes(self) -> None:
+ """`pipelex-dev check-error-registry` exits normally on the committed registry."""
+ check_error_registry_cmd(quiet=True)
+
+ def test_the_snapshot_carries_pipelex_version(self) -> None:
+ """The registry is published under Pipelex's own version, which only pyproject.toml writes, in the form the release gate reads."""
+ snapshot = json.loads(REGISTRY_SNAPSHOT_PATH.read_text(encoding="utf-8"))
+ expected = registry_version_of(package_version=read_pipelex_version())
+ assert snapshot["version"] == expected, f"the snapshot's version is not pyproject.toml's: {REMEDY}"
+ assert next(iter(snapshot)) == "version"
+ assert "version" not in load_registry_source()
+
+ def test_the_shipped_snapshot_loads_into_the_typed_model(self) -> None:
+ """The package's snapshot, read through importlib.resources, is the committed one and validates."""
+ assert read_pipelex_error_registry_snapshot_text() == REGISTRY_SNAPSHOT_PATH.read_text(encoding="utf-8")
+ registry = load_pipelex_error_registry()
+ assert registry.prefix == "pipelex"
+ assert registry.base_url == "https://docs.pipelex.com/errors"
+ assert len(registry.codes) == len(load_registry_source()["codes"])
+ assert registry.type_uri(code="pipelex.billing.credit_exhausted") == "https://docs.pipelex.com/errors/pipelex.billing.credit_exhausted"
+
+ def test_every_code_has_its_page_and_its_parameters_model(self) -> None:
+ """Each code is a member of PipelexErrorCode, has a parameters model and a page at the path its type URI leads to."""
+ registry = load_pipelex_error_registry()
+ assert {str(code) for code in PipelexErrorCode} == {entry.code for entry in registry.codes}
+ assert set(PIPELEX_ERROR_PARAMS) == set(PipelexErrorCode)
+ for entry in registry.codes:
+ assert PIPELEX_ERROR_PARAMS[PipelexErrorCode(entry.code)].code == entry.code
+ assert entry.page_path == "errors/" + entry.code.replace(".", "/") + ".md"
+ assert (DOCS_DIR / entry.page_path).is_file()
+
+ def test_the_generated_page_paths_are_the_pages_the_generator_renders(self) -> None:
+ """The paths a `see` reference may name before the pages are written are exactly the pages the generator writes."""
+ registry = load_pipelex_error_registry()
+ assert generated_page_paths(registry=registry) == frozenset(render_pages(registry=registry))
+
+ def test_the_vendored_standard_files_are_the_recorded_ones(self) -> None:
+ """The standard's schema and core snapshot are copied verbatim, at the digests and the commit vendored.toml records."""
+ record = load_vendored_record()
+ assert vendored_file_errors(record=record) == []
+ assert set(record.files) == {"mthds-error-registry.schema.json", "mthds-error-registry.json"}
+ assert re.fullmatch(r"[0-9a-f]{40}", record.source.commit)
+
+ def test_a_hidden_file_under_the_pages_is_no_orphan(self, tmp_path: Path) -> None:
+ """A `.DS_Store` a desktop leaves under docs/errors/ is neither reported nor removed; a stray page is."""
+ pages_dir = tmp_path / "errors"
+ (pages_dir / "pipelex" / ".cache").mkdir(parents=True)
+ generated = pages_dir / "index.md"
+ stray = pages_dir / "pipelex" / "stray.md"
+ for path in (generated, stray, pages_dir / ".DS_Store", pages_dir / "pipelex" / ".DS_Store", pages_dir / "pipelex" / ".cache" / "page.md"):
+ path.write_text("text", encoding="utf-8")
+ assert orphan_pages(outputs={generated: "text"}, pages_dir=pages_dir) == [stray]
+
+
+def _source_from(text: str) -> Callable[[Path], Callable[[], dict[str, Any]]]:
+ """A composed-document loader reading a source file of this text, written under the test's directory."""
+
+ def loader_in(tmp_path: Path) -> Callable[[], dict[str, Any]]:
+ source_path = tmp_path / "registry.yaml"
+ source_path.write_text(text, encoding="utf-8")
+ return lambda: compose_registry_document(source=load_registry_source(path=source_path), version=read_registry_version())
+
+ return loader_in
+
+
+def _missing_source(tmp_path: Path) -> Callable[[], dict[str, Any]]:
+ return lambda: compose_registry_document(source=load_registry_source(path=tmp_path / "absent.yaml"), version="0.1.0")
+
+
+def _pyproject_from(text: str) -> Callable[[Path], Callable[[], dict[str, Any]]]:
+ """A composed-document loader reading the committed source and a ``pyproject.toml`` of this text."""
+
+ def loader_in(tmp_path: Path) -> Callable[[], dict[str, Any]]:
+ pyproject_path = tmp_path / "pyproject.toml"
+ pyproject_path.write_text(text, encoding="utf-8")
+ return lambda: compose_registry_document(source=load_registry_source(), version=read_registry_version(pyproject_path=pyproject_path))
+
+ return loader_in
+
+
+class TestErrorRegistryFaultsArePrinted:
+ @pytest.fixture
+ def console_buffer(self, mocker: MockerFixture) -> io.StringIO:
+ """Route the commands' console to a buffer, wide enough that no assertion depends on where Rich wraps."""
+ buffer = io.StringIO()
+ mocker.patch.object(error_registry_cmd, "get_console", return_value=Console(file=buffer, width=400, force_terminal=False))
+ return buffer
+
+ @pytest.mark.parametrize(
+ ("loader_in", "expected"),
+ [
+ (_source_from("codes: [\n"), "registry.yaml: while parsing"),
+ (_source_from("prefix: pipelex\nprefix: acme\n"), "duplicate key 'prefix'"),
+ (_source_from("? [a, b]\n: value\n"), "found a key that is a sequence or a mapping"),
+ (_source_from("- a list\n"), "the registry is a mapping of its members"),
+ (_source_from("version: 1.0.0\nprefix: pipelex\n"), "writes a version"),
+ (_missing_source, "absent.yaml cannot be read"),
+ (_pyproject_from('[project]\nversion = "0.88.0.post1"\n'), "pyproject.toml"),
+ (_pyproject_from("[project\n"), "pyproject.toml is not valid TOML"),
+ (_pyproject_from('[project]\nname = "pipelex"\n'), "has no [project].version"),
+ ],
+ )
+ def test_a_source_that_does_not_load_is_a_printed_fault(
+ self,
+ mocker: MockerFixture,
+ tmp_path: Path,
+ console_buffer: io.StringIO,
+ loader_in: Callable[[Path], Callable[[], dict[str, Any]]],
+ expected: str,
+ ) -> None:
+ """A source or a version the loaders refuse is reported as a fault, and the generator exits with 1 having written nothing."""
+ mocker.patch.object(registry_outputs, "load_composed_document", side_effect=loader_in(tmp_path))
+ write_outputs = mocker.patch.object(error_registry_cmd, "write_outputs")
+ checked, errors = source_errors()
+ assert checked is None
+ assert any(expected in error for error in errors), errors
+ with pytest.raises(typer.Exit) as exit_info:
+ generate_error_registry_cmd(quiet=True)
+ assert exit_info.value.exit_code == 1
+ write_outputs.assert_not_called()
+ assert expected in console_buffer.getvalue()
+
+ @pytest.mark.parametrize(
+ ("core_text", "expected"),
+ [
+ ("{not json", "is not valid JSON"),
+ ('{"version": "1.0.0"}', "is not a registry the typed model reads"),
+ (None, "cannot be read"),
+ ],
+ )
+ def test_a_core_snapshot_that_does_not_load_is_a_printed_fault(
+ self, mocker: MockerFixture, tmp_path: Path, console_buffer: io.StringIO, core_text: str | None, expected: str
+ ) -> None:
+ """A core snapshot that is not valid JSON, not a registry or not a file is reported as a fault by the check command."""
+ core_path = tmp_path / "core.json"
+ if core_text is None:
+ core_path.mkdir()
+ else:
+ core_path.write_text(core_text, encoding="utf-8")
+ mocker.patch.object(registry_outputs, "STANDARD_CORE_SNAPSHOT_PATH", core_path)
+ checked, errors = source_errors()
+ assert checked is None
+ assert any(expected in error for error in errors), errors
+ with pytest.raises(typer.Exit) as exit_info:
+ check_error_registry_cmd(quiet=True)
+ assert exit_info.value.exit_code == 1
+ assert expected in console_buffer.getvalue()
+
+ def test_a_site_without_a_latest_version_is_a_printed_fault(self, tmp_path: Path, console_buffer: io.StringIO) -> None:
+ """The redirect command reports a site it cannot write the redirects into, rather than raise."""
+ with pytest.raises(typer.Exit) as exit_info:
+ write_error_type_redirects_cmd(site_root=tmp_path, quiet=True)
+ assert exit_info.value.exit_code == 1
+ assert "holds no 'latest' version" in console_buffer.getvalue()
diff --git a/tests/unit/pipelex/errors/registry/test_pipelex_codes.py b/tests/unit/pipelex/errors/registry/test_pipelex_codes.py
new file mode 100644
index 000000000..021ba9edb
--- /dev/null
+++ b/tests/unit/pipelex/errors/registry/test_pipelex_codes.py
@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import ast
+import importlib.util
+import sys
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from pydantic import ValidationError
+
+from pipelex.cli.dev_cli.commands.error_registry.codes_generator import ANNOTATION_BUILTIN_NAMES, render_pipelex_codes
+from pipelex.errors.registry.pipelex_codes import (
+ PIPELEX_ERROR_PARAMS,
+ CatalogNotFoundParams,
+ ConfigSyntaxParams,
+ DocgenPrintTimeoutParams,
+ PipelexErrorCode,
+ SecurityReservedKeyParams,
+ WebhookDeliveryFailedParams,
+)
+from pipelex.errors.registry.registry_document import ErrorRegistryDocument, load_pipelex_error_registry
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+# Items of a list parameter typed as each constrained scalar, added to a code to test what the generator writes for them.
+CONSTRAINED_LIST_PARAMS: dict[str, dict[str, Any]] = {
+ "sizes": {"type": "list", "items": {"type": "bytes"}, "description": "Sizes."},
+ "durations": {"type": "list", "items": {"type": "seconds"}, "description": "Durations."},
+ "digests": {"type": "list", "items": {"type": "sha256"}, "description": "Digests."},
+}
+
+
+# A parameter of every type, plain, optional and as a list's items, so the generated module names every annotation it can.
+EVERY_TYPE_PARAMS: dict[str, dict[str, Any]] = {
+ **{
+ f"{prefix}_{scalar}": {"type": scalar, "description": "A value.", **({"optional": True} if prefix == "optional" else {})}
+ for scalar in ("identifier", "integer", "seconds", "bytes", "sha256", "caller_text")
+ for prefix in ("plain", "optional")
+ },
+ "plain_enum": {"type": "enum", "values": ["a", "b"], "description": "A value."},
+ "optional_enum": {"type": "enum", "values": ["a", "b"], "optional": True, "description": "A value."},
+ "operator_value": {"type": "identifier", "operator_only": True, "description": "A value."},
+ **{
+ f"list_of_{scalar}": {"type": "list", "items": {"type": scalar}, "description": "Values."}
+ for scalar in ("identifier", "integer", "seconds", "bytes", "sha256", "caller_text")
+ },
+ "list_of_enum": {"type": "list", "items": {"type": "enum", "values": ["a", "b"]}, "description": "Values."},
+}
+
+
+class TestPipelexCodes:
+ def test_each_parameters_model_declares_the_registry_parameters(self) -> None:
+ """A code's model has a field per declared parameter, optional ones defaulting to None, and names its operator-only ones."""
+ for entry in load_pipelex_error_registry().codes:
+ model = PIPELEX_ERROR_PARAMS[PipelexErrorCode(entry.code)]
+ assert list(model.model_fields) == list(entry.params), entry.code
+ for param_name, param in entry.params.items():
+ field = model.model_fields[param_name]
+ assert field.is_required() is not param.optional, f"{entry.code}.{param_name}"
+ expected_operator_only = {param_name for param_name, param in entry.params.items() if param.operator_only}
+ assert model.operator_only_params == expected_operator_only, entry.code
+
+ @pytest.mark.parametrize(
+ ("topic", "model", "values"),
+ [
+ ("an undeclared parameter", ConfigSyntaxParams, {"surface": "backends", "file": "backends.toml", "line": 3, "column": 1, "path": "x"}),
+ ("a missing parameter", ConfigSyntaxParams, {"surface": "backends", "file": "backends.toml", "line": 3}),
+ ("a value outside the enum", WebhookDeliveryFailedParams, {"reason": "timeout"}),
+ ("a negative number of seconds", DocgenPrintTimeoutParams, {"limit": -1.0}),
+ ("a list item of the wrong type", SecurityReservedKeyParams, {"keys": [{"name": "__class__"}]}),
+ ("an integer given as a string", ConfigSyntaxParams, {"surface": "backends", "file": "backends.toml", "line": "3", "column": 1}),
+ ("an integer given as a boolean", ConfigSyntaxParams, {"surface": "backends", "file": "backends.toml", "line": True, "column": 1}),
+ ("a number of seconds given as a string", DocgenPrintTimeoutParams, {"limit": "30"}),
+ ],
+ )
+ def test_a_parameters_model_refuses_what_the_registry_does_not_declare(self, topic: str, model: Any, values: dict[str, Any]) -> None:
+ """The models are closed and typed as the registry declares, so a raise site cannot carry a fact the code does not."""
+ with pytest.raises(ValidationError):
+ model(**values)
+ assert topic
+
+ def test_a_parameters_model_holds_the_declared_values(self) -> None:
+ """A valid occurrence validates, its optional parameters may be absent, and the model is frozen."""
+ params = CatalogNotFoundParams(resource="method", method_id="mt_abc")
+ assert params.version is None
+ assert params.code == PipelexErrorCode.CATALOG_NOT_FOUND
+ with pytest.raises(ValidationError):
+ params.method_id = "mt_other" # type: ignore[misc] # pyright: ignore[reportAttributeAccessIssue]
+ delivery = WebhookDeliveryFailedParams(reason="http_status", receiver_status=500)
+ assert delivery.model_dump() == {"reason": "http_status", "receiver_status": 500}
+ timeout = DocgenPrintTimeoutParams(limit=30)
+ assert timeout.limit == 30.0
+
+ @pytest.mark.parametrize(
+ ("topic", "values"),
+ [
+ ("a negative size", {"sizes": [-4], "durations": [], "digests": []}),
+ ("a negative duration", {"sizes": [], "durations": [-0.5], "digests": []}),
+ ("a digest that is not lowercase hexadecimal", {"sizes": [], "durations": [], "digests": ["NOT-HEX"]}),
+ ],
+ )
+ def test_a_list_item_carries_the_constraints_of_its_type(
+ self,
+ composed_document: dict[str, Any],
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+ topic: str,
+ values: dict[str, Any],
+ ) -> None:
+ """An item of a list of sizes, durations or digests is refused where a single parameter of its type would be."""
+ entry = next(entry for entry in composed_document["codes"] if entry["code"] == "pipelex.storage.unavailable")
+ entry["params"].update(CONSTRAINED_LIST_PARAMS)
+ text = render_pipelex_codes(registry=ErrorRegistryDocument.model_validate(composed_document))
+ assert " sizes: list[Annotated[int, Field(ge=0)]]" in text
+ assert " durations: list[Annotated[float, Field(ge=0)]]" in text
+ assert ' digests: list[Annotated[str, Field(pattern="^[0-9a-f]{64}$")]]' in text
+ module_path = tmp_path / "generated_pipelex_codes.py"
+ module_path.write_text(text, encoding="utf-8")
+ spec = importlib.util.spec_from_file_location("generated_pipelex_codes", module_path)
+ assert spec is not None
+ assert spec.loader is not None
+ module = importlib.util.module_from_spec(spec)
+ # Pydantic resolves the module's postponed annotations through sys.modules.
+ monkeypatch.setitem(sys.modules, spec.name, module)
+ spec.loader.exec_module(module)
+ model: Any = module.StorageUnavailableParams
+ valid = model(scheme="s3", sizes=[0, 4096], durations=[0.5], digests=["a" * 64])
+ assert valid.sizes == [0, 4096]
+ with pytest.raises(ValidationError):
+ model(scheme="s3", **values)
+ assert topic
+
+ def test_the_generated_annotations_name_only_the_builtins_a_parameter_may_not_take(self, composed_document: dict[str, Any]) -> None:
+ """Every lowercase name a generated class annotates with is one the checks refuse as a parameter name, so no field shadows it.
+
+ Only a class body's annotations are resolved in a namespace a field's name enters; the module's own are not.
+ """
+ entry = next(entry for entry in composed_document["codes"] if entry["code"] == "pipelex.storage.unavailable")
+ entry["params"].update(EVERY_TYPE_PARAMS)
+ text = render_pipelex_codes(registry=ErrorRegistryDocument.model_validate(composed_document))
+ annotated_names: set[str] = set()
+ for class_node in ast.walk(ast.parse(text)):
+ if not isinstance(class_node, ast.ClassDef):
+ continue
+ for statement in class_node.body:
+ if isinstance(statement, ast.AnnAssign):
+ annotated_names.update(name.id for name in ast.walk(statement.annotation) if isinstance(name, ast.Name) and name.id.islower())
+ assert {"str", "int", "float", "list", "frozenset"} <= annotated_names
+ assert annotated_names <= ANNOTATION_BUILTIN_NAMES, annotated_names - ANNOTATION_BUILTIN_NAMES
diff --git a/tests/unit/pipelex/errors/registry/test_registry_version.py b/tests/unit/pipelex/errors/registry/test_registry_version.py
new file mode 100644
index 000000000..a98b07a36
--- /dev/null
+++ b/tests/unit/pipelex/errors/registry/test_registry_version.py
@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import subprocess # ruff: ignore[suspicious-subprocess-import]
+import sys
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+from pipelex.cli.dev_cli.commands.error_registry import registry_version
+from pipelex.cli.dev_cli.commands.error_registry.exceptions import ErrorRegistryError
+from pipelex.cli.dev_cli.commands.error_registry.registry_checks import registry_errors
+from pipelex.cli.dev_cli.commands.error_registry.registry_source import (
+ DOCS_DIR,
+ compose_registry_document,
+ load_registry_source,
+ read_registry_version,
+)
+from pipelex.cli.dev_cli.commands.error_registry.registry_version import registry_version_of
+from pipelex.errors.registry.registry_document import ErrorRegistryDocument
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+# The module the release workflow's version gate runs as a script on a bare runner.
+REGISTRY_VERSION_SCRIPT = registry_version.__file__
+
+
+class TestRegistryVersion:
+ @pytest.mark.parametrize(
+ ("package_version", "expected"),
+ [
+ ("0.88.0", "0.88.0"),
+ ("0.88.0a1", "0.88.0-a.1"),
+ ("0.88.0b2", "0.88.0-b.2"),
+ ("0.88.0rc1", "0.88.0-rc.1"),
+ ("1.10.3rc12", "1.10.3-rc.12"),
+ ],
+ )
+ def test_a_pipelex_version_is_written_as_semver(
+ self,
+ package_version: str,
+ expected: str,
+ standard_schema: dict[str, Any],
+ core_registry: ErrorRegistryDocument,
+ ) -> None:
+ """A release keeps its number, an alpha, a beta and a release candidate take their SemVer form, which the format accepts."""
+ version = registry_version_of(package_version=package_version)
+ assert version == expected
+ document = compose_registry_document(source=load_registry_source(), version=version)
+ errors = registry_errors(document=document, schema=standard_schema, core=core_registry, docs_dir=DOCS_DIR, where="registry")
+ assert errors == []
+ assert ErrorRegistryDocument.model_validate(document).version == expected
+
+ @pytest.mark.parametrize("package_version", ["0.88", "0.88.0.post1", "0.88.0.dev1", "0.88.0-rc.1", "0.88.0rc", "v0.88.0"])
+ def test_a_version_pipelex_never_releases_under_is_refused(self, package_version: str) -> None:
+ """Only the forms the release workflows accept are converted; anything else is refused rather than guessed."""
+ with pytest.raises(ValueError, match="cannot be published under it"):
+ registry_version_of(package_version=package_version)
+
+ def test_the_pyproject_version_is_read_in_its_registry_form(self, tmp_path: Path) -> None:
+ """The generator composes the snapshot with the converted version, and names pyproject.toml when it cannot convert it."""
+ pyproject_path = tmp_path / "pyproject.toml"
+ pyproject_path.write_text('[project]\nname = "pipelex"\nversion = "0.88.0rc1"\n', encoding="utf-8")
+ assert read_registry_version(pyproject_path=pyproject_path) == "0.88.0-rc.1"
+ pyproject_path.write_text('[project]\nname = "pipelex"\nversion = "0.88.0.post1"\n', encoding="utf-8")
+ with pytest.raises(ErrorRegistryError, match="cannot be published under it"):
+ read_registry_version(pyproject_path=pyproject_path)
+
+ @pytest.mark.parametrize(("package_version", "expected"), [("0.88.0rc1", "0.88.0-rc.1"), ("0.88.0", "0.88.0")])
+ def test_the_release_gate_runs_the_conversion_on_a_bare_interpreter(self, package_version: str, expected: str) -> None:
+ """The release workflow runs the module with `python3 -I`, which imports nothing of the repository's environment."""
+ result = subprocess.run( # ruff: ignore[subprocess-without-shell-equals-true] -- fixed, trusted argv
+ [sys.executable, "-I", REGISTRY_VERSION_SCRIPT, package_version],
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+ assert result.returncode == 0, result.stderr
+ assert result.stdout == f"{expected}\n"
+
+ def test_the_release_gate_fails_on_a_version_it_cannot_convert(self) -> None:
+ """A version the registry cannot carry stops the gate with a message, rather than comparing an empty string."""
+ result = subprocess.run( # ruff: ignore[subprocess-without-shell-equals-true] -- fixed, trusted argv
+ [sys.executable, "-I", REGISTRY_VERSION_SCRIPT, "0.88.0.dev1"],
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+ assert result.returncode == 2
+ assert result.stdout == ""
+ assert "cannot be published under it" in result.stderr
diff --git a/tests/unit/pipelex/errors/registry/test_type_redirects.py b/tests/unit/pipelex/errors/registry/test_type_redirects.py
new file mode 100644
index 000000000..5f9433ae5
--- /dev/null
+++ b/tests/unit/pipelex/errors/registry/test_type_redirects.py
@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pipelex.cli.dev_cli.commands.error_registry.exceptions import ErrorRegistryError
+from pipelex.cli.dev_cli.commands.error_registry.type_redirects import ROOT_STUB_NAME, STUB_MARKER, write_type_redirects
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+BASE_URL = "https://docs.pipelex.com/errors"
+
+
+def _publish_page(site_root: Path, *, version: str, page_dir: str) -> None:
+ page_path = site_root / version / "errors" / page_dir / "index.html"
+ page_path.parent.mkdir(parents=True, exist_ok=True)
+ page_path.write_text("<html>page</html>", encoding="utf-8")
+
+
+class TestTypeRedirects:
+ def test_a_stub_per_documented_code_redirects_its_type_uri_to_the_latest_page(self, tmp_path: Path) -> None:
+ """The type URI's directory, named after the whole code, redirects to the code's page under /latest/."""
+ _publish_page(tmp_path, version="latest", page_dir="pipelex/billing/credit_exhausted")
+ _publish_page(tmp_path, version="latest", page_dir="pipelex/config/syntax")
+ _publish_page(tmp_path, version="0.86.0", page_dir="pipelex/old/code")
+
+ report = write_type_redirects(site_root=tmp_path, base_url=BASE_URL)
+
+ assert report.written == ["pipelex.billing.credit_exhausted", "pipelex.config.syntax", ROOT_STUB_NAME]
+ stub = (tmp_path / "errors" / "pipelex.billing.credit_exhausted" / "index.html").read_text(encoding="utf-8")
+ assert STUB_MARKER in stub
+ assert '<meta http-equiv="refresh" content="0; url=/latest/errors/pipelex/billing/credit_exhausted/">' in stub
+ assert '<link rel="canonical" href="https://docs.pipelex.com/latest/errors/pipelex/billing/credit_exhausted/">' in stub
+ index_stub = (tmp_path / "errors" / "index.html").read_text(encoding="utf-8")
+ assert "url=/latest/errors/" in index_stub
+ assert not (tmp_path / "errors" / "pipelex.old.code").exists()
+
+ def test_a_second_run_changes_nothing_and_a_stale_stub_is_removed(self, tmp_path: Path) -> None:
+ """Rerunning is idempotent; a stub whose code latest no longer documents goes, a directory the tool did not write stays."""
+ _publish_page(tmp_path, version="latest", page_dir="pipelex/billing/credit_exhausted")
+ _publish_page(tmp_path, version="latest", page_dir="pipelex/billing/plan_limit")
+ write_type_redirects(site_root=tmp_path, base_url=BASE_URL)
+ foreign_dir = tmp_path / "errors" / "pipelex.hand.written"
+ foreign_dir.mkdir()
+ (foreign_dir / "index.html").write_text("<html>mine</html>", encoding="utf-8")
+
+ report = write_type_redirects(site_root=tmp_path, base_url=BASE_URL)
+ assert report.written == []
+ assert report.removed == []
+ assert sorted(report.unchanged) == [ROOT_STUB_NAME, "pipelex.billing.credit_exhausted", "pipelex.billing.plan_limit"]
+
+ (tmp_path / "latest" / "errors" / "pipelex" / "billing" / "plan_limit" / "index.html").unlink()
+ report = write_type_redirects(site_root=tmp_path, base_url=BASE_URL)
+ assert report.removed == ["pipelex.billing.plan_limit"]
+ assert not (tmp_path / "errors" / "pipelex.billing.plan_limit").exists()
+ assert (foreign_dir / "index.html").is_file()
+
+ def test_no_root_stub_is_written_while_latest_documents_no_code(self, tmp_path: Path) -> None:
+ """Before a release that documents the codes is latest, a root stub would redirect into a 404, so no stub is written."""
+ _publish_page(tmp_path, version="latest", page_dir="env-var-not-found-error")
+ (tmp_path / "latest" / "errors" / "index.html").write_text("<html>the retired class pages' index</html>", encoding="utf-8")
+ _publish_page(tmp_path, version="0.88.0", page_dir="pipelex/billing/credit_exhausted")
+
+ report = write_type_redirects(site_root=tmp_path, base_url=BASE_URL)
+
+ assert report.written == []
+ assert report.unchanged == []
+ assert report.removed == []
+ assert not (tmp_path / "errors").exists()
+
+ def test_a_root_stub_written_earlier_is_removed_once_latest_documents_no_code(self, tmp_path: Path) -> None:
+ """The root stub this command wrote goes with the codes' stubs when latest no longer documents any code."""
+ _publish_page(tmp_path, version="latest", page_dir="pipelex/billing/credit_exhausted")
+ assert write_type_redirects(site_root=tmp_path, base_url=BASE_URL).written == ["pipelex.billing.credit_exhausted", ROOT_STUB_NAME]
+ (tmp_path / "latest" / "errors" / "pipelex" / "billing" / "credit_exhausted" / "index.html").unlink()
+
+ report = write_type_redirects(site_root=tmp_path, base_url=BASE_URL)
+
+ assert report.written == []
+ assert report.removed == ["pipelex.billing.credit_exhausted", ROOT_STUB_NAME]
+ assert not (tmp_path / "errors" / "index.html").exists()
+ assert not (tmp_path / "errors" / "pipelex.billing.credit_exhausted").exists()
+
+ def test_a_root_index_this_command_did_not_write_is_never_removed(self, tmp_path: Path) -> None:
+ """A file at the root stub's place without the stubs' marker is not a stub, so it stays when there is no root stub to write."""
+ (tmp_path / "latest").mkdir()
+ foreign_index = tmp_path / "errors" / "index.html"
+ foreign_index.parent.mkdir()
+ foreign_index.write_text("<html>mine</html>", encoding="utf-8")
+
+ report = write_type_redirects(site_root=tmp_path, base_url=BASE_URL)
+
+ assert report.removed == []
+ assert foreign_index.read_text(encoding="utf-8") == "<html>mine</html>"
+
+ def test_a_site_without_a_latest_version_is_refused(self, tmp_path: Path) -> None:
+ """With no released version there is no page for a type URI to reach."""
+ with pytest.raises(ErrorRegistryError, match="holds no 'latest' version"):
+ write_type_redirects(site_root=tmp_path, base_url=BASE_URL)
+
+ def test_a_base_url_without_a_path_is_refused(self, tmp_path: Path) -> None:
+ """Stubs written at the site's very root would overwrite its own pages."""
+ (tmp_path / "latest").mkdir()
+ with pytest.raises(ErrorRegistryError, match="has no path"):
+ write_type_redirects(site_root=tmp_path, base_url="https://docs.pipelex.com")
diff --git a/tests/unit/pipelex/errors/test_error_class_discovery.py b/tests/unit/pipelex/errors/test_error_class_discovery.py
new file mode 100644
index 000000000..5d68585a2
--- /dev/null
+++ b/tests/unit/pipelex/errors/test_error_class_discovery.py
@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pipelex.base_exceptions import PipelexError
+from pipelex.core.bundle_resources.exceptions import BundleResourceNotNamedError
+from pipelex.errors.error_class_discovery import (
+ _force_load_all_error_modules, # pyright: ignore[reportPrivateUsage]
+ iter_pipelex_error_subclasses,
+)
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+
+class TestErrorClassDiscovery:
+ def test_discovery_yields_the_root_and_a_subclass_of_a_deferred_module(self) -> None:
+ """The root comes first, and a subclass defined in an ``exceptions.py`` module is found."""
+ discovered = list(iter_pipelex_error_subclasses())
+ assert discovered[0] is PipelexError
+ assert BundleResourceNotNamedError in discovered
+
+ def test_force_load_walk_continues_past_first_failure(self, mocker: MockerFixture) -> None:
+ """Every per-module import failure is aggregated: the walk does not abort on the first one."""
+ _force_load_all_error_modules.cache_clear()
+ try:
+ mocker.patch(
+ "pipelex.errors.error_class_discovery.importlib.import_module",
+ side_effect=NameError("boom"),
+ )
+ with pytest.raises(RuntimeError) as exc_info:
+ _force_load_all_error_modules()
+ message = str(exc_info.value)
+ distinct_module_names = {line.strip(" -").split(":", 1)[0] for line in message.splitlines() if line.strip().startswith("- ")}
+ assert len(distinct_module_names) >= 2, (
+ f"expected at least 2 distinct walked dotted module names in the aggregated RuntimeError; "
+ f"saw {len(distinct_module_names)}: {sorted(distinct_module_names)}"
+ )
+ finally:
+ _force_load_all_error_modules.cache_clear()
+
+ def test_force_load_aggregates_non_import_error_failures(self, mocker: MockerFixture) -> None:
+ """A ``NameError`` raised while a module initializes is aggregated, not propagated raw."""
+ _force_load_all_error_modules.cache_clear()
+ try:
+ mocker.patch(
+ "pipelex.errors.error_class_discovery.importlib.import_module",
+ side_effect=NameError("boom"),
+ )
+ with pytest.raises(RuntimeError, match="boom") as exc_info:
+ _force_load_all_error_modules()
+ message = str(exc_info.value)
+ assert "pipelex.base_exceptions" in message, "RuntimeError should list at least one walked dotted module"
+ finally:
+ _force_load_all_error_modules.cache_clear()
diff --git a/tests/unit/pipelex/errors/test_error_class_location_convention.py b/tests/unit/pipelex/errors/test_error_class_location_convention.py
index 920e90d01..497bc0d63 100644
--- a/tests/unit/pipelex/errors/test_error_class_location_convention.py
+++ b/tests/unit/pipelex/errors/test_error_class_location_convention.py
@@ -34,7 +34,7 @@ from pathlib import Path
import pipelex
from pipelex.base_exceptions import PipelexError
-from pipelex.errors.error_pages_generator import (
+from pipelex.errors.error_class_discovery import (
_FIXTURE_DIR_NAMES, # pyright: ignore[reportPrivateUsage]
iter_pipelex_error_subclasses,
)
diff --git a/tests/unit/pipelex/errors/test_error_pages_generator.py b/tests/unit/pipelex/errors/test_error_pages_generator.py
deleted file mode 100644
index 032f97464..000000000
--- a/tests/unit/pipelex/errors/test_error_pages_generator.py
+++ /dev/null
@@ -1,253 +0,0 @@
-"""Smoke tests for the per-class error documentation page generator."""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-import pytest
-
-from pipelex.base_exceptions import PipelexError
-from pipelex.core.bundle_resources.exceptions import BundleResourceNotNamedError
-from pipelex.core.method_trees.exceptions import MethodFileUnavailableError
-from pipelex.errors.error_pages_generator import (
- _MACRO_SECTIONS, # pyright: ignore[reportPrivateUsage]
- AUTHORED_MARKER,
- GENERATED_MARKER,
- INDEX_STEM,
- ErrorPagesReport,
- _force_load_all_error_modules, # pyright: ignore[reportPrivateUsage]
- generate_error_pages,
- has_authored_marker,
- iter_pipelex_error_subclasses,
- page_slug,
- render_error_page,
-)
-from pipelex.tools.misc.string_utils import pascal_case_to_kebab
-
-if TYPE_CHECKING:
- from pytest_mock import MockerFixture
-
-
-def _find_mkdocs_config() -> Path:
- """Walk up from this test module to the repo root holding ``mkdocs.yml``."""
- for parent in Path(__file__).resolve().parents:
- candidate = parent / "mkdocs.yml"
- if candidate.is_file():
- return candidate
- msg = "mkdocs.yml not found in any parent of the test module"
- raise FileNotFoundError(msg)
-
-
-class TestErrorPagesGenerator:
- def test_emits_one_page_per_loaded_subclass_plus_index_and_macros(self, tmp_path: Path) -> None:
- """Every subclass gets a per-class page; a landing ``index.md`` and the macro pages are emitted too."""
- report = generate_error_pages(output_dir=tmp_path)
-
- subclasses = list(iter_pipelex_error_subclasses())
- class_stems = {pascal_case_to_kebab(cls.__name__) for cls in subclasses}
- macro_stems = {slug for slug, _ in _MACRO_SECTIONS}
-
- emitted_paths = report.written + report.unchanged + report.preserved
- emitted_stems = {path.stem for path in emitted_paths}
-
- assert class_stems <= emitted_stems, "every per-class page must be emitted"
- assert INDEX_STEM in emitted_stems
- assert macro_stems <= emitted_stems, "every macro listing page must be emitted (all are non-empty in the full set)"
- assert report.removed == []
- assert report.total == len(emitted_stems)
-
- for stem in emitted_stems:
- page = tmp_path / f"{stem}.md"
- assert page.exists(), f"missing page for stem {stem!r}"
- assert GENERATED_MARKER in page.read_text(encoding="utf-8")
-
- def test_macro_pages_link_every_class(self, tmp_path: Path) -> None:
- """Every per-class page is reachable from exactly one macro listing page."""
- generate_error_pages(output_dir=tmp_path)
- macro_bodies = "".join(
- (tmp_path / f"{slug}.md").read_text(encoding="utf-8") for slug, _ in _MACRO_SECTIONS if (tmp_path / f"{slug}.md").exists()
- )
- for cls in iter_pipelex_error_subclasses():
- link_target = f"]({page_slug(cls)}.md)"
- assert link_target in macro_bodies, f"no macro page links {link_target!r}"
-
- def test_index_links_each_emitted_macro_page(self, tmp_path: Path) -> None:
- """The overview ``index.md`` links every macro listing page that was emitted."""
- generate_error_pages(output_dir=tmp_path)
- index_body = (tmp_path / f"{INDEX_STEM}.md").read_text(encoding="utf-8")
- for slug, _ in _MACRO_SECTIONS:
- if (tmp_path / f"{slug}.md").exists():
- assert f"]({slug}.md)" in index_body, f"index missing link to macro page {slug!r}"
-
- def test_macro_slugs_are_wired_into_mkdocs_nav(self) -> None:
- """Each generator macro slug must be wired into ``mkdocs.yml`` — as a nav entry and a
- ``not_in_nav`` re-include — so the hand-maintained nav can never drift from
- ``_MACRO_SECTIONS`` and break ``mkdocs build --strict`` on a missing or renamed page.
- """
- config_lines = [line.strip() for line in _find_mkdocs_config().read_text(encoding="utf-8").splitlines()]
- for slug, _ in _MACRO_SECTIONS:
- nav_suffix = f": errors/{slug}.md"
- assert any(line.endswith(nav_suffix) for line in config_lines), f"mkdocs.yml nav has no entry for macro page errors/{slug}.md"
- assert f"!errors/{slug}.md" in config_lines, f"mkdocs.yml not_in_nav is missing the re-include !errors/{slug}.md"
-
- def test_run_is_idempotent(self, tmp_path: Path) -> None:
- """Re-running the generator over its own output writes nothing — every page is byte-identical."""
- first = generate_error_pages(output_dir=tmp_path)
- assert first.unchanged == []
- assert first.preserved == []
- assert first.removed == []
-
- second = generate_error_pages(output_dir=tmp_path)
- assert second.written == []
- assert second.preserved == []
- assert second.removed == []
- assert len(second.unchanged) == first.total
-
- def test_authored_marker_preserves_hand_edited_page(self, tmp_path: Path) -> None:
- """A page bearing the standalone authored marker survives regeneration verbatim."""
- target_class = next(iter_pipelex_error_subclasses())
- slug = page_slug(target_class)
- page_path = tmp_path / f"{slug}.md"
- authored_body = f"{AUTHORED_MARKER}\n\n# Custom title\n\nMaintainer-curated content.\n"
- page_path.write_text(authored_body, encoding="utf-8")
-
- report = generate_error_pages(output_dir=tmp_path)
-
- assert page_path in report.preserved
- assert page_path not in report.written
- assert page_path.read_text(encoding="utf-8") == authored_body
-
- def test_authored_marker_detection_ignores_marker_inside_other_content(self) -> None:
- """The marker must appear as its own (stripped) line — substring matches don't count."""
- body_with_marker_in_prose = "<!-- pipelex:generated -->\n<!-- Add the `<!-- pipelex:authored -->` marker to claim this page -->\n"
- assert has_authored_marker(body_with_marker_in_prose) is False
-
- body_with_standalone_marker = f"some content\n{AUTHORED_MARKER}\nmore content\n"
- assert has_authored_marker(body_with_standalone_marker) is True
-
- def test_a_class_declaring_retryable_shows_it_and_one_declaring_nothing_does_not(self) -> None:
- assert "| `retryable` | `false` |" in render_error_page(BundleResourceNotNamedError)
- assert "`retryable`" not in render_error_page(MethodFileUnavailableError)
-
- def test_report_total_sums_four_populations(self) -> None:
- """``total`` should equal the sum of ``written`` + ``unchanged`` + ``preserved`` + ``removed``."""
- report = ErrorPagesReport(
- written=[Path("a.md"), Path("b.md")],
- unchanged=[Path("c.md")],
- preserved=[Path("d.md"), Path("e.md"), Path("f.md")],
- removed=[Path("g.md"), Path("h.md")],
- )
- assert report.total == 8
-
- def test_kebab_slug_collision_raises(self, tmp_path: Path) -> None:
- """Two classes that kebab to the same slug fail generation loudly."""
-
- class LLMError(PipelexError):
- pass
-
- class LlmError(PipelexError):
- pass
-
- with pytest.raises(RuntimeError, match="Kebab-slug collision on 'llm-error'"):
- generate_error_pages(output_dir=tmp_path, classes=[LLMError, LlmError])
-
- def test_reserved_slug_collision_raises(self, tmp_path: Path) -> None:
- """A class kebab-ing to a listing-page stem (a macro area, here ``platform-and-tooling``)
- fails loudly instead of having its per-class page silently overwritten by the listing page.
- """
-
- # Deliberately no `Error` suffix: the collision can only arise for a name that kebabs
- # onto a reserved listing-page stem, and an ``…Error`` name always kebabs to ``…-error``.
- class PlatformAndTooling(PipelexError): # ruff: ignore[error-suffix-on-exception-name]
- pass
-
- with pytest.raises(RuntimeError, match="Reserved-slug collision on 'platform-and-tooling'"):
- generate_error_pages(output_dir=tmp_path, classes=[PlatformAndTooling])
-
- def test_orphan_generated_page_is_deleted(self, tmp_path: Path) -> None:
- """A generated page whose slug is no longer in target_classes is deleted and reported under ``removed``."""
-
- class FooError(PipelexError):
- pass
-
- first = generate_error_pages(output_dir=tmp_path, classes=[FooError])
- foo_page = tmp_path / f"{page_slug(FooError)}.md"
- assert foo_page in first.written
- assert foo_page.exists()
-
- # Re-run with an empty target set — FooError's page is now an orphan.
- second = generate_error_pages(output_dir=tmp_path, classes=[])
- assert foo_page in second.removed
- assert not foo_page.exists()
-
- def test_orphan_authored_page_is_preserved_not_deleted(self, tmp_path: Path) -> None:
- """A hand-authored page (no longer mapped to a target class) is preserved, not removed."""
- authored_page = tmp_path / "stale-but-authored.md"
- authored_body = f"{AUTHORED_MARKER}\n\n# Custom notes\n"
- authored_page.write_text(authored_body, encoding="utf-8")
-
- report = generate_error_pages(output_dir=tmp_path, classes=[])
-
- assert authored_page in report.preserved
- assert authored_page not in report.removed
- assert authored_page.read_text(encoding="utf-8") == authored_body
-
- def test_orphan_unmarked_file_is_left_alone(self, tmp_path: Path) -> None:
- """A file with neither marker is treated as out-of-scope and never touched."""
- unmarked_page = tmp_path / "random-note.md"
- unmarked_body = "# Random note\n\nNot ours to manage.\n"
- unmarked_page.write_text(unmarked_body, encoding="utf-8")
-
- report = generate_error_pages(output_dir=tmp_path, classes=[])
-
- assert unmarked_page not in report.removed
- assert unmarked_page not in report.preserved
- assert unmarked_page.read_text(encoding="utf-8") == unmarked_body
-
- def test_force_load_walk_continues_past_first_failure(self, mocker: MockerFixture) -> None:
- """Every per-module import failure is aggregated — the walk must NOT abort on the first one.
-
- Pins the multi-failure aggregation contract: the existing
- ``test_force_load_aggregates_non_import_error_failures`` only asserts
- the first module's name appears in the message, so a regression that
- re-raises on the first failure (instead of accumulating) would still
- pass. This test asserts at least two distinct dotted module names
- appear in the raised ``RuntimeError.args[0]``.
- """
- _force_load_all_error_modules.cache_clear()
- try:
- mocker.patch(
- "pipelex.errors.error_pages_generator.importlib.import_module",
- side_effect=NameError("boom"),
- )
- with pytest.raises(RuntimeError) as exc_info:
- _force_load_all_error_modules()
- message = str(exc_info.value)
- distinct_module_names = {line.strip(" -").split(":", 1)[0] for line in message.splitlines() if line.strip().startswith("- ")}
- assert len(distinct_module_names) >= 2, (
- f"expected at least 2 distinct walked dotted module names in the aggregated RuntimeError; "
- f"saw {len(distinct_module_names)}: {sorted(distinct_module_names)}"
- )
- finally:
- _force_load_all_error_modules.cache_clear()
-
- def test_force_load_aggregates_non_import_error_failures(self, mocker: MockerFixture) -> None:
- """A `NameError` (or any non-ImportError) raised during module init is aggregated, not propagated raw.
-
- Regression for greptile review: if a `*_exceptions.py` has a typo at module scope, its
- import raises `NameError` — not `ImportError`. The walk must still finish for every other
- module and surface the broken module's dotted name in the final `RuntimeError`.
- """
- _force_load_all_error_modules.cache_clear()
- try:
- mocker.patch(
- "pipelex.errors.error_pages_generator.importlib.import_module",
- side_effect=NameError("boom"),
- )
- with pytest.raises(RuntimeError, match="boom") as exc_info:
- _force_load_all_error_modules()
- message = str(exc_info.value)
- assert "pipelex.base_exceptions" in message, "RuntimeError should list at least one walked dotted module"
- finally:
- _force_load_all_error_modules.cache_clear()
diff --git a/tests/unit/pipelex/test_pipelex_error_message_init.py b/tests/unit/pipelex/test_pipelex_error_message_init.py
index b2338bd3f..09193326e 100644
--- a/tests/unit/pipelex/test_pipelex_error_message_init.py
+++ b/tests/unit/pipelex/test_pipelex_error_message_init.py
@@ -12,7 +12,7 @@ import pytest
from pipelex.base_exceptions import PipelexError
from pipelex.cogt.exceptions import RoutingProfileBlueprintValueError
-from pipelex.errors.error_pages_generator import iter_pipelex_error_subclasses
+from pipelex.errors.error_class_discovery import iter_pipelex_error_subclasses
from pipelex.pipe_operators.compose.exceptions import ConstructFieldBlueprintValueError
diff --git a/tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py b/tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py
index a2be91111..f1d1b68b9 100644
--- a/tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py
+++ b/tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py
@@ -1,21 +1,12 @@
"""Class-name uniqueness guard for the ``PipelexError.type_uri()`` keyspace.
Every loaded ``PipelexError`` subclass whose ``type_uri`` is derived from its class name must produce
-a unique one. A collision there would mean two distinct error classes kebab to the same documentation
-page by accident — this catches class-name reuses at CI time, not at docs-build time.
-
-A class that declares ``_declared_type_uri`` points at a page on purpose, usually the existing page of
-the generic family it belongs to, so it may share that page with the family's own class. What it may
-not do is point at a page that does not exist, which the second case checks.
+a unique one. A collision there would mean two distinct error classes kebab to the same URI by
+accident — this catches class-name reuses at CI time. A class that declares ``_declared_type_uri``
+shares a URI on purpose, so it is left out.
"""
-from pathlib import Path
-
-from pipelex.errors.error_pages_generator import iter_pipelex_error_subclasses
-from pipelex.urls import URLs
-
-_TESTS_ROOT = next(parent for parent in Path(__file__).resolve().parents if parent.name == "tests")
-_ERROR_PAGES_DIR = _TESTS_ROOT.parent / "docs" / "errors"
+from pipelex.errors.error_class_discovery import iter_pipelex_error_subclasses
class TestPipelexErrorTypeUriUniqueness:
@@ -30,15 +21,3 @@ class TestPipelexErrorTypeUriUniqueness:
msg = f"type_uri collision: {cls.__name__} and {seen[uri]} both produce {uri!r}"
raise AssertionError(msg)
seen[uri] = cls.__name__
-
- def test_every_declared_type_uri_under_the_error_docs_names_an_existing_page(self) -> None:
- """A declared URI that points into the error docs must land on a page that is there."""
- missing: list[str] = []
- for cls in iter_pipelex_error_subclasses():
- declared = cls.__dict__.get("_declared_type_uri")
- if not isinstance(declared, str) or not declared.startswith(f"{URLs.error_docs_base}/"):
- continue
- slug = declared.removeprefix(f"{URLs.error_docs_base}/").strip("/")
- if not (_ERROR_PAGES_DIR / f"{slug}.md").is_file():
- missing.append(f"{cls.__name__} -> {declared}")
- assert not missing, "declared type URIs pointing at no error page:\n" + "\n".join(missing)