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.

fix: derive error_domain for the CogtError family from InferenceErrorCategory (#1175)

Louis Choquelb3b496dee45c
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index 4b54c0589..92948cd0b 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:c28a7ec0b029ea11e2ca96dccf909609b4b34ed1079e67d6e24f5bb34e5863d1"
+digest = "sha256:98cd6d18e164724aa99408c14e3975728c57006cedf1460f1d354e9bf8b5ed9d"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-08-30T16:39:08Z"
-rationale = "Escaping the rich markup in the NAME argument help of the eight method subcommands. No command, flag, argument or documented surface changed: the address grammar the help states is identical before and after, and the escape exists only because typer renders argument help through rich's markup parser, which read the literal [/name] as a closing tag and crashed. Reviewed docs/tools/cli/ — run.md, validate.md, run-by-address.md and the three build pages state the same grammar in Markdown, where the brackets are already literal, so nothing there was stale; no page carries a verbatim --help transcript. pipelex/cli/agent_cli/CLAUDE.md is unaffected, since the two-stream output contract it documents is untouched."
+reviewed_at = "2026-08-31T16:15:54Z"
+rationale = "Inference errors now derive error_domain from their InferenceErrorCategory, so agent_error's report-first read supersedes the AGENT_ERROR_DOMAINS lookup for every categorized CogtError. Removed the three now-unreachable entries and gave ModelChoiceNotFoundError an explicit class-level INPUT domain, since a mistyped model reference is the caller's to fix even though its category is CONFIGURATION. Reviewed docs/tools/cli/ — agent-cli.md states the generic error envelope and enumerates no dict entries, so nothing there was stale. Updated the Error classification bullet in pipelex/cli/agent_cli/CLAUDE.md, which named the dict as the only source and no longer described how a class self-describes."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -12,7 +12,7 @@ rationale = "Escaping the rich markup in the NAME argument help of the eight met
"pipelex/cli/agent_cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.py" = "blob:cb8338c09a7b5dee6088551c156d69dab613213a"
"pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:c9a251db61d8655bdb41002c62eab88b486fc32f"
-"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:19cb8df5cf764c85aeaf91d24ce13b26607fff1c"
+"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:a1ffa37559c51d6272d0ec26bfbd073303233096"
"pipelex/cli/agent_cli/commands/bundle_path_resolver.py" = "blob:30339c5d91048f4e67312d5691ed9a65d57472e0"
"pipelex/cli/agent_cli/commands/check_model_cmd.py" = "blob:ff33446143044332983a0cb7b204b8eca349795a"
"pipelex/cli/agent_cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d870e7161..94ff4e6ab 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@
### Changed
+- **Inference errors now declare an `error_domain`, derived from the category the worker already assigned** (breaking): the whole `CogtError` family used to report no domain at all, so every inference failure — a content-policy refusal included — was rendered as HTTP 500 by any consumer reading `ErrorReport.http_status`. `InferenceErrorCategory` gains an `error_domain` property and `CogtError.to_error_report()` derives from it, which means a **content-classified failure now answers 422 instead of 500**: a provider content-policy refusal, a malformed prompt image, a bad prompt parameter and their siblings are all properties of material the caller submitted. The widest reach of that mapping is worth stating plainly, because it goes past the classes that declare `CONTENT` on themselves: **every provider HTTP 400 classifies as `CONTENT`**, as does a builtin `ValueError` / `RuntimeError` / `FileNotFoundError` out of a local file extractor, so a context-length overflow, a parameter a model rejects, and an engine-side request-construction fault all answer 422 now and leave the 5xx rate. The `UserAction` on those was already `CHANGE_INPUT`, so the status is only catching up with the advice the report was already giving. The other mappings change no status and only make the report truthful about why — `CONFIGURATION` is `config`, `TRANSIENT` / `CAPACITY` / `AMBIGUOUS` are `runtime`, and `UNKNOWN` deliberately asserts no domain, since classification itself failed there and an absent domain already renders 500. Deriving rather than declaring per class is what keeps `error_domain` and `error_category` from contradicting each other on the wire; a leaf that declares its own domain still wins, and the provider-429 passthrough is still checked before the domain. The effect reaches the HTTP boundary through every wrapping layer: `PipelineExecutionError`'s generic `RUNTIME` was documented as a floor applied only when the cause chain surfaced no domain, and until now the cause chain surfaced none for any inference failure, so the floor fired every time. Consumers that route on the domain rather than the status see the same correction — a validate hook classifying `config` / `runtime` as a warning and everything else as a block now warns on a genuine backend or model-deck misconfiguration surfacing through dry-run inference, where before an undomained error fell through to the default block and told the agent to edit a `.mthds` file that was not at fault. On the agent CLI this makes three `AGENT_ERROR_DOMAINS` entries unreachable, since a report that carries its own domain is read before that fallback lookup: `ModelDeckPresetValidatonError` and `GatewayUnknownModelError` derive the `config` the dict already stated and are simply removed, while `ModelChoiceNotFoundError` now declares `error_domain = input` on the class itself — a mistyped model reference is the caller's to fix, on the hosted API as much as in a local file, even though its category is `CONFIGURATION` from the provider call's point of view, and an operator-side deck fault surfaces as `ModelDeckPresetValidatonError` instead. The drift test that bars a self-describing class from those dicts gained the arm that covers derivation, so the next such entry cannot go dead unnoticed. See [Error Model](under-the-hood/error-model.md).
- **`kajson` version**: The pin moves to `kajson==0.7.1`, the release making `ClassRegistry.register_classes_dict({})` a no-op instead of raising `IndexError` — its logging branch for the single-class case indexed into an empty collection. This engine seeds a fresh per-run or per-library registry from a snapshot of the process-global one, so a snapshot that happens to be empty used to crash the seeding rather than register nothing; both seeding sites (distributed-run rehydration and the scoped-registry test fixture) are now safe unconditionally. The release changes nothing in the encoder or decoder, so the serialized wire format is untouched in both directions. Everyone downstream inherits that exact version.
### Removed
@@ -18,6 +19,7 @@
### Fixed
+- **A bad pipeline-input url survives STRICT disclosure as caller-facing copy**: `PipelineInputContentError` declared `caller_facing_message = True`, which is the name of the *report field*, not of the class-level flag that sets it (`_authors_caller_facing_message`). The declaration therefore did nothing, and the message a caller who simply omitted a url needs to see — the one listing the accepted schemes — was replaced by the generic internal-error placeholder on any surface serializing in STRICT mode, exactly the redaction the declaration was written to prevent. Repairing the flag also revealed why the class could not carry it as it stood: its other raise site reports an unreadable local path, and that message names the resolved path and the `OSError` subclass that rejected it, which would have made STRICT answer "does this server-side path exist, and may the runner read it?" for any authenticated caller of a deployment leaving `is_upload_local_content_enabled` on. The family is therefore split: `PipelineInputUrlMissingError` carries the blank-url message and is caller-facing, while `PipelineInputContentError` keeps the unreadable-path message and stays redacted. Both are pinned in the class-level-metadata sweep, in both directions.
- **The projection corpus's divergence gate sees every engine/projection difference**: `pipelex-dev generate-projection-corpus` states that every difference between the reference projection and the engine's own renderer lands in a declared class, and that an undeclared one fails the command — but the walk missed differences in one direction and absorbed regressions into existing classes in the other, so a projection defect could pass generation green and be committed into `mthds-js` and `mthds-python` as contract bytes. The dict walk iterated only the projected keys, so a field the projection stopped rendering was never compared at all; it is now recorded under an id deliberately absent from the declared reasons, which makes the record refuse rather than pass. The file-leaf arm returned on the expansion without ever comparing the URL both sides carry, where plain recursion would have handed a regressed placeholder to the url-named-text class that absorbs it; the shared keys are now compared strictly. And `fixed-count-honoured` fired on any list longer than the engine's single element, which cannot tell an honoured `Concept[N]` from a wrong count or from a variable `[]` slot wrongly duplicated; it now consults the slot's declared `item_count`, taken from the descriptor. Separately, a pipe declaring no inputs used to abort the whole capture — an empty input form is valid and the projection renders it as `{}`, but the engine's renderer refuses one — and is now captured from the projection alone, with no engine half and nothing compared. Re-measuring the same corpus produces bytes identical to the committed capture, with the same classes at the same counts. See [Projection Fixture Corpus](contribute/generate-projection-corpus.md).
- **`--help` works again on every `method` subcommand**: `pipelex validate method`, `pipelex run method`, the three `pipelex build ... method` commands and their agent-CLI twins all crashed with a rich `MarkupError` traceback instead of printing their help. The method-address example in each command's `NAME` argument help — `github.com/owner/repo[/name][@tag]` — reaches rich's markup parser through typer, which read `[/name]` as a closing tag with no opening one. The brackets are escaped at each of the sites, so the example renders as written and the help exits zero.
- **Class-backed concepts reflect field by field in the input-form descriptor**: a concept declaring `structure = "SomeClass"` used to collapse to `kind: "unknown"` the moment one field annotation could not be mapped, taking every sibling field with it — and a nested non-native pydantic model was reported as an opaque payload rather than walked into. Every `document` and `image` position beneath such a concept disappeared from the descriptor, so a consumer preparing inputs from it passed a local file path at one of those positions through un-uploaded and the run failed on the unresolved path. Reflection is now partial: each annotation is mapped on its own, an unmappable one is `unknown` at that field alone, a nested model is an `object` the reflection walks into, a `list[X]` reports its element node, and a class that holds itself is cut at the revisit instead of recursing. A `RootModel` is reported as its root annotation's node wherever it appears — as a field of a reflected class, and as the registered class backing the concept itself — because the value it accepts is the root value, so the descriptor no longer states an object over a synthetic `root` key that contradicts the `json_schema` derived beside it. The native consistency probe keeps its faithful-or-absent rule — it is compared against a normative pinned blueprint, where a plausible-looking partial answer would be the failure — and the two reflections now share one annotation vocabulary (`pipelex/core/concepts/annotation_shapes.py`) instead of one calling the other. See [Input-Form Descriptor](under-the-hood/input-form-descriptor.md).
diff --git a/docs/errors/execution-and-runtime.md b/docs/errors/execution-and-runtime.md
index 3d3f74f67..812306929 100644
--- a/docs/errors/execution-and-runtime.md
+++ b/docs/errors/execution-and-runtime.md
@@ -32,6 +32,7 @@ own page. Classes are grouped by subsystem.
- [`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
+- [`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
diff --git a/docs/errors/model-choice-not-found-error.md b/docs/errors/model-choice-not-found-error.md
index 8cb15fd92..39179d80d 100644
--- a/docs/errors/model-choice-not-found-error.md
+++ b/docs/errors/model-choice-not-found-error.md
@@ -14,7 +14,7 @@ Error raised when a model choice cannot be found in the model deck.
| `error_type` | `ModelChoiceNotFoundError` |
| `title` | Model choice not found |
| `type_uri` | `https://docs.pipelex.com/latest/errors/model-choice-not-found-error/` |
-| `error_domain` | _(inherited from parent)_ |
+| `error_domain` | `input` |
| Defined in | `pipelex.cogt.exceptions` |
| Parent class | [`CogtError`](cogt-error.md) |
diff --git a/docs/errors/pipeline-input-url-missing-error.md b/docs/errors/pipeline-input-url-missing-error.md
new file mode 100644
index 000000000..9859ab7b6
--- /dev/null
+++ b/docs/errors/pipeline-input-url-missing-error.md
@@ -0,0 +1,21 @@
+---
+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/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index b412631d6..351560a96 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -39,7 +39,7 @@ An error rises through a series of layers. Each layer has exactly one job.
| **1 — Workers / SDK calls** | `pipelex/providers/*/` | **Catch the SDK exception → classify → raise `CogtError`** |
| **0 — Third-party SDKs** | OpenAI, Anthropic, Google, … | Raise raw, untyped provider exceptions |
-Classification happens once, at **Layer 1**. Layers 2–5 are wrappers: they attach context as they catch and re-raise, but the `error_category`, `error_domain`, `model`, and `provider` set at Layer 1 reach Layer 5 unchanged (see [Cause-Chain Enrichment](#cause-chain-enrichment)).
+Classification happens once, at **Layer 1**. Layers 2–5 are wrappers: they attach context as they catch and re-raise, but the `error_category`, `error_domain`, `model`, and `provider` set at Layer 1 reach Layer 5 unchanged (see [Cause-Chain Enrichment](#cause-chain-enrichment)). The worker states only the `error_category`; the matching `error_domain` is [derived from it](#the-cogterror-family-derives-its-domain-from-its-category), so a single Layer-1 decision settles both the retry question and the HTTP status.
---
@@ -54,7 +54,7 @@ Classification happens once, at **Layer 1**. Layers 2–5 are wrappers: they att
| `title` | `str` | Stable human-readable summary — the RFC 7807 `title` |
| `type_uri` | `str` | Per-class documentation URI — the RFC 7807 `type` |
| `error_category` | `str \| None` | `InferenceErrorCategory` value (inference errors only) |
-| `error_domain` | `str \| None` | `ErrorDomain` value — `input` / `config` / `runtime` |
+| `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 |
| `user_action` | `UserAction \| None` | Typed advice — `kind` + free-form `detail` |
| `model` | `str \| None` | Model handle, when the failure is attributable to one |
@@ -139,16 +139,16 @@ Two `StrEnum`s drive every downstream decision.
### InferenceErrorCategory
-Defined in `pipelex/cogt/exceptions.py`. Drives retry decisions — `is_retryable` is `True` only for `TRANSIENT`.
+Defined in `pipelex/cogt/exceptions.py`. It carries two derived properties: `is_retryable` drives retry decisions and is `True` only for `TRANSIENT`; `error_domain` drives the HTTP status the whole `CogtError` family answers with.
-| Category | Meaning | Retryable | Typical cause |
-|----------|---------|-----------|---------------|
-| `TRANSIENT` | A brief, self-correcting failure | ✅ | Rate limit, 5xx, connection blip |
-| `CONFIGURATION` | The setup is wrong | ❌ | Bad API key, missing backend |
-| `CONTENT` | The input or prompt is wrong | ❌ | Content-policy violation, bad prompt |
-| `CAPACITY` | Account quota / billing exhausted | ❌ | `insufficient_quota`, HTTP 402 |
-| `AMBIGUOUS` | Outcome unknown — may have committed | ❌ | Connection dropped mid-request |
-| `UNKNOWN` | Could not classify | ❌ | Unrecognized inner exception |
+| Category | Meaning | Retryable | Domain | Typical cause |
+|----------|---------|-----------|--------|---------------|
+| `TRANSIENT` | A brief, self-correcting failure | ✅ | `RUNTIME` | Rate limit, 5xx, connection blip |
+| `CONFIGURATION` | The setup is wrong | ❌ | `CONFIG` | Bad API key, missing backend |
+| `CONTENT` | The input or prompt is wrong | ❌ | **`INPUT`** | Content-policy violation, bad prompt |
+| `CAPACITY` | Account quota / billing exhausted | ❌ | `RUNTIME` | `insufficient_quota`, HTTP 402 |
+| `AMBIGUOUS` | Outcome unknown — may have committed | ❌ | `RUNTIME` | Connection dropped mid-request |
+| `UNKNOWN` | Could not classify | ❌ | *none* | Unrecognized inner exception |
```python
class InferenceErrorCategory(StrEnum):
@@ -163,11 +163,23 @@ class InferenceErrorCategory(StrEnum):
return True
case _: # all other categories
return False
+
+ @property
+ def error_domain(self) -> ErrorDomain | None:
+ match self:
+ case InferenceErrorCategory.CONTENT:
+ return ErrorDomain.INPUT
+ case InferenceErrorCategory.CONFIGURATION:
+ return ErrorDomain.CONFIG
+ # ... TRANSIENT / CAPACITY / AMBIGUOUS -> RUNTIME, UNKNOWN -> None ...
```
!!! info "`AMBIGUOUS` vs `UNKNOWN`"
`AMBIGUOUS` means the *error type is known* but the operation may or may not have committed — a blind retry is unsafe for a non-idempotent call. `UNKNOWN` means classification itself failed. Both are non-retryable, for different reasons.
+!!! info "`UNKNOWN` maps to no domain at all"
+ `UNKNOWN` means the classification step itself failed, so claiming `RUNTIME` would assert something the code cannot support. An absent `error_domain` already renders 500 (see below), so the honest answer costs nothing at the HTTP boundary and keeps "could not classify" distinguishable from "classified as a server-side fault".
+
### ErrorDomain
Defined in `pipelex/base_exceptions.py`. Set as a class-level attribute on the exception, drives HTTP status.
@@ -178,13 +190,26 @@ Defined in `pipelex/base_exceptions.py`. Set as a class-level attribute on the e
| `CONFIG` | Environment / configuration change needed | **500** | The operator |
| `RUNTIME` | A failure during execution | **500** | Depends on the cause |
-`error_domain_to_http_status()` is the pure mapping table. `ErrorReport.http_status` layers one rule on top: a provider 429 (`provider_metadata.status_code == 429`) takes precedence over the domain, so the API can emit a `Retry-After` header.
+`error_domain_to_http_status()` is the pure mapping table — it maps an unset or unrecognized domain to 500 as well. `ErrorReport.http_status` layers one rule on top: a provider 429 (`provider_metadata.status_code == 429`) takes precedence over the domain, so the API can emit a `Retry-After` header. That precedence is why `CAPACITY -> RUNTIME` does not swallow a rate-limit passthrough.
```python
class PipelexConfigError(PipelexError):
error_domain = ErrorDomain.CONFIG # class-level — every instance carries it
```
+#### The `CogtError` family derives its domain from its category
+
+The inference branch is the one place where `error_domain` is **not** declared per class. A worker has already decided whose fault the failure is when it assigns an `InferenceErrorCategory`, so `CogtError.to_error_report()` derives the domain from that category rather than asking several dozen leaf classes to state the same fact twice — which is also what keeps `error_domain` and `error_category` from ever contradicting each other on the wire.
+
+Precedence on the derived field mirrors every other field on that method: an `error_domain` declared explicitly on the leaf class wins, then the category derivation, then whatever the `__cause__` chain surfaced.
+
+```python
+own_domain = self.error_category.error_domain if self.error_category is not None else None
+"error_domain": self.error_domain or own_domain or base_report.error_domain,
+```
+
+The consequence worth knowing at the HTTP boundary: a **content-classified inference failure answers 422, not 500** — a content-policy refusal, a malformed prompt image, a bad prompt parameter are all properties of material the caller submitted. Everything else keeps the status it already had; only the report became truthful about why.
+
---
## Worker Classification
@@ -376,7 +401,7 @@ flowchart TB
### Class Hierarchy
-`PipelexError` is the single root. `CogtError` is the inference branch — it overrides `to_error_report()` to add `error_category`, `retryable`, `user_action`, `provider_metadata`, and reads `model_handle` / `backend_name` from the instance.
+`PipelexError` is the single root. `CogtError` is the inference branch — it overrides `to_error_report()` to add `error_category`, `retryable`, `user_action`, `provider_metadata`, and reads `model_handle` / `backend_name` from the instance. It is also where `error_domain` is *derived* rather than declared: the whole subtree gets its domain from its category.
```
Exception
@@ -384,23 +409,28 @@ Exception
├── PipelexConfigError → error_domain = CONFIG
├── PipelexSetupError → error_domain = CONFIG
├── CogtError cogt/exceptions.py — error_category, provider_metadata
- │ ├── LLMCompletionError ← per-instance category from the worker
+ │ │ → error_domain derived from error_category (no per-class declaration)
+ │ ├── LLMCompletionError ← per-instance category from the worker → per-instance domain
│ ├── ImgGenGenerationError ← per-instance category
+ │ ├── LLMPromptSpecError ← class-level CONTENT → INPUT → HTTP 422
+ │ ├── LLMConfigError ← class-level CONFIGURATION → CONFIG
│ ├── ModelNotFoundError ← sibling family raised on provider HTTP 404
│ │ ├── LLMModelNotFoundError / ImgGenModelNotFoundError
│ │ └── ExtractModelNotFoundError / SearchModelNotFoundError
│ └── ... (see worker classification) ...
- ├── PipelineExecutionError pipeline/exceptions.py — error_domain = RUNTIME
+ ├── PipelineExecutionError pipeline/exceptions.py — error_domain = RUNTIME, but only as a floor
└── ... (one exceptions.py per package) ...
```
+`PipelineExecutionError`'s `RUNTIME` is deliberately a *floor*, applied only when the cause chain surfaced no domain — so a `CONTENT`-categorized inference failure now reaches the HTTP boundary as `INPUT` / 422 through every wrapping layer instead of being flattened to the wrapper's generic 500.
+
### Factory-time vs Runtime
| When | What carries metadata | How |
|------|----------------------|-----|
| **Class definition** | `error_domain`, `error_category` defaults, `user_action` defaults | Class-level attributes — one source of truth per exception type |
| **Raise time** | Per-instance `error_category`, `user_action`, `provider_metadata` | Constructor args — set by the worker that classified the failure |
-| **Report time** | `model`, `provider`, cause-chain fields | `fill_model_and_provider()` at the worker chokepoint; `_enrich_error_report_from_cause()` on `to_error_report()` |
+| **Report time** | `model`, `provider`, cause-chain fields; `error_domain` on the `CogtError` family | `fill_model_and_provider()` at the worker chokepoint; `InferenceErrorCategory.error_domain` derivation and `_enrich_error_report_from_cause()` on `to_error_report()` |
The "outcome" exceptions (`LLMCompletionError`, `ImgGenGenerationError`, `ExtractJobFailureError`, `SearchJobFailureError`) intentionally carry **no** class-level `error_category` — their category is genuinely per-instance, decided by the worker.
@@ -448,14 +478,17 @@ InferenceErrorCategory.TRANSIENT.is_retryable # True — only TRANSIENT
| Scenario | Behavior |
|----------|----------|
-| Rate limit hit | `TRANSIENT` → retryable; transport retry honors `Retry-After` |
-| Quota / billing exhausted | `CAPACITY` → non-retryable; `UserAction(CHECK_BILLING)` |
+| Rate limit hit | `TRANSIENT` → retryable; `error_domain = RUNTIME`; transport retry honors `Retry-After` (a provider 429 answers 429 regardless of domain) |
+| Quota / billing exhausted | `CAPACITY` → non-retryable; `UserAction(CHECK_BILLING)`; `error_domain = RUNTIME` → HTTP 500 |
| Bad API key | `CONFIGURATION` → non-retryable; `error_domain = CONFIG` → HTTP 500 |
| Model or deployment not found (provider HTTP 404) | Raises a dedicated `*ModelNotFoundError` sibling (`LLMModelNotFoundError`, `ImgGenModelNotFoundError`, `ExtractModelNotFoundError`, `SearchModelNotFoundError`); operator re-raises `PipeOperatorModelAvailabilityError` |
-| Content-policy violation | `CONTENT` → non-retryable; `UserAction(CHANGE_INPUT)` |
-| LLM returns schema-mismatched JSON | `instructor` re-asks; if exhausted → `UNKNOWN` |
-| Connection dropped mid-request | `AMBIGUOUS` → non-retryable (outcome unknown) |
-| Wrapper exception (no own category) | Inherits cause's classification via enrichment |
+| Content-policy violation | `CONTENT` → non-retryable; `UserAction(CHANGE_INPUT)`; `error_domain = INPUT` → **HTTP 422** |
+| Malformed prompt image / bad prompt parameter | `CONTENT` class-level (`PromptImageFormatError`, `LLMPromptParameterError`, …) → `error_domain = INPUT` → **HTTP 422** |
+| Any other provider **HTTP 400** | `CONTENT` → `error_domain = INPUT` → **HTTP 422**. This is the widest reach of the derivation: a 400 covers a context-length overflow and a parameter the model rejects alike, and an engine-side request-construction fault lands here too — reported as the caller's to fix, and absent from the 5xx rate |
+| Local file extractor raises a builtin (docling, pypdfium2) | `ValueError` / `RuntimeError` / `FileNotFoundError` → `CONTENT` → `error_domain = INPUT` → **HTTP 422**; `OSError` → `TRANSIENT` (see `_LOCAL_EXTRACT_BY_TYPE_NAME`) |
+| LLM returns schema-mismatched JSON | `instructor` re-asks; if exhausted → `UNKNOWN` → no `error_domain` asserted → HTTP 500 |
+| Connection dropped mid-request | `AMBIGUOUS` → non-retryable (outcome unknown); `error_domain = RUNTIME` |
+| Wrapper exception (no own category) | Inherits cause's classification via enrichment — including the domain the cause derived |
| Failure on a distributed worker | `ErrorReport` recovered from the transport's serialized details — same classification as local |
| Worker exception with no `ErrorReport` | Synthesized fallback report — `error_domain = RUNTIME` |
diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.md
index 6a91bf111..cae77ac58 100644
--- a/pipelex/cli/agent_cli/CLAUDE.md
+++ b/pipelex/cli/agent_cli/CLAUDE.md
@@ -102,7 +102,7 @@ commands/
## Key Patterns
- **Output contract**: Commands with `--format` emit success via `agent_success_formatted(result, markdown_renderer, output_format)` — JSON or a markdown renderer per the explicit `output_format` argument. `agent_error(message, error_type, cause)` dispatches JSON or markdown by reading the `_agent_cli_error_format` ContextVar, which each `--format`-aware command sets via `set_agent_cli_error_format(error_format or output_format)` at function entry. Exceptions that print directly to stdout: `fmt`/`lint` (plxt passthrough), `concept`/`pipe` (raw TOML). Markdown renderers: `format_run_markdown` (`run/_output_helpers.py`), `format_validate_markdown` (lifted to the non-CLI `pipelex/pipeline/validation_render.py` so `pipelex-api` can import it without CLI/Typer deps), `format_fix_markdown` (non-CLI `pipelex/pipeline/fixes/fix_render.py`), `_format_init_markdown` (`init_cmd.py`).
-- **Error classification**: Each error type maps to a domain (`input`, `config`, `runtime`), a hint string, and a `retryable` flag. See `AGENT_ERROR_HINTS` dict in `agent_output.py`. The `error_domain` also drives the HTTP-status mapping for downstream APIs — see `error_domain_to_http_status()` in `pipelex/base_exceptions.py`.
+- **Error classification**: Each error carries a domain (`input`, `config`, `runtime`), a hint string, and a `retryable` flag. `agent_error()` reads them **report-first**: a `PipelexError` cause's `to_error_report()` wins, and the `AGENT_ERROR_HINTS` / `AGENT_ERROR_DOMAINS` dicts in `agent_output.py` are the fallback for error types that cannot self-describe (builtins, third-party classes, synthetic `error_type` labels). Two ways a class self-describes, and both bar it from the dicts: a class-level `error_domain` / `user_action`, **or** — for the `CogtError` family — an `error_category`, from which `InferenceErrorCategory.error_domain` derives the domain (so `CONTENT` inference failures report `input`, and a dict entry for such a class would be unreachable). `tests/unit/pipelex/cli/test_agent_output_drift.py` enforces both. When a derived domain is wrong for a class, declare an explicit `error_domain` on the class — `ModelChoiceNotFoundError` does, because a mistyped model reference is the caller's to fix even though the category is `CONFIGURATION`. The `error_domain` also drives the HTTP-status mapping for downstream APIs — see `error_domain_to_http_status()` in `pipelex/base_exceptions.py` and [Error Model](../../../docs/under-the-hood/error-model.md).
- **The `migration` field on a configuration error**: A `PipelexConfigError` carries one when a scan of this machine's configuration directories found something — and only then, so its presence is the test for whether the migration history has anything to say. Whether a command *repairs* it is the separate `would_write` field: true means the configuration is *old*, and the loop is `pipelex-agent migrate --dry-run --format json`, show the user, then `--yes`; false means the block is a diagnosis its `plans` carry and the command would rewrite nothing, so branching on presence alone sends an agent to a run with nothing to do. Its `plans` are the same shape that command emits under its own `plans` key. `error_domain` stays `config`: a domain the hook specification does not know routes to BLOCK, which would stop an agent instead of telling it what to run. See `docs/migration-ledger.md` → "Reporting a stale configuration on a validation error".
- **Init**: All commands that need Pipelex use `make_pipelex_for_agent_cli(library_dirs)`. It catches init errors and routes them through `agent_error()`.
- **Async core**: Run and validate are async — commands use `asyncio.run()`.
diff --git a/pipelex/cli/agent_cli/commands/agent_output.py b/pipelex/cli/agent_cli/commands/agent_output.py
index 19cb8df5c..a1ffa3755 100644
--- a/pipelex/cli/agent_cli/commands/agent_output.py
+++ b/pipelex/cli/agent_cli/commands/agent_output.py
@@ -95,6 +95,15 @@ def get_agent_cli_error_format() -> CliOutputFormat:
# migrated to class-level metadata. A PipelexError subclass that declares
# class-level error_domain / user_action must NOT appear here — enforced by
# tests/unit/pipelex/cli/test_agent_output_drift.py.
+#
+# A CogtError subclass carrying an error_category self-describes too, without any
+# class-level error_domain of its own: InferenceErrorCategory.error_domain derives
+# one, and to_error_report() puts it on the report, so the report-first read at the
+# bottom of agent_error() always wins and an AGENT_ERROR_DOMAINS entry for such a
+# class can never be read. Those are barred from this dict as well, by the same
+# drift test — a dead entry is exactly the rot it exists to prevent. When the
+# derived domain is not the one this CLI wants, fix it on the class (declare an
+# explicit error_domain, as ModelChoiceNotFoundError does), never here.
AGENT_ERROR_HINTS: dict[str, str] = {
# Model/routing errors
"ModelChoiceNotFoundError": (
@@ -177,7 +186,6 @@ RETRYABLE_ERROR_TYPES: set[str] = {
AGENT_ERROR_DOMAINS: dict[str, str] = {
# input = agent can fix (bad .mthds, wrong args, bad JSON)
- "ModelChoiceNotFoundError": "input",
"PipeValidationError": "input",
"FixBundleError": "input",
"FileNotFoundError": "input",
@@ -198,9 +206,7 @@ AGENT_ERROR_DOMAINS: dict[str, str] = {
"ClientAuthenticationError": "config",
"PipeOperatorModelChoiceError": "config",
"PipeOperatorModelAvailabilityError": "config",
- "ModelDeckPresetValidatonError": "config",
"BinaryNotFoundError": "config",
- "GatewayUnknownModelError": "config",
"InitConfigError": "config",
}
diff --git a/pipelex/cogt/exceptions.py b/pipelex/cogt/exceptions.py
index db67f1fca..5c6d3719b 100644
--- a/pipelex/cogt/exceptions.py
+++ b/pipelex/cogt/exceptions.py
@@ -5,7 +5,7 @@ from typing import TYPE_CHECKING
from typing_extensions import override
-from pipelex.base_exceptions import ErrorReport, PipelexError, iter_cause_chain
+from pipelex.base_exceptions import ErrorDomain, ErrorReport, PipelexError, iter_cause_chain
from pipelex.cogt.inference.error_classification import ProviderErrorMetadata, UserAction, UserActionKind
from pipelex.system.pipelex_service.types import RemoteConfigSource
@@ -41,6 +41,36 @@ class InferenceErrorCategory(StrEnum):
):
return False
+ @property
+ def error_domain(self) -> ErrorDomain | None:
+ """The :class:`~pipelex.base_exceptions.ErrorDomain` this category implies — who can fix it.
+
+ The category a worker assigns is already the authoritative statement of *whose fault*
+ an inference failure is, so :meth:`CogtError.to_error_report` derives the domain from it
+ rather than making every leaf class in the family declare the same fact twice.
+
+ ``CONTENT`` is the one mapping that changes an HTTP answer: a content-policy refusal, a
+ malformed prompt image, a bad prompt parameter are all properties of material the caller
+ submitted, so they belong in ``INPUT`` and answer 422 rather than 500.
+
+ ``UNKNOWN`` deliberately maps to ``None``. It means classification itself failed, and
+ ``RUNTIME`` would be a claim this code cannot support; an absent domain already renders
+ 500, so the honest answer costs nothing.
+
+ ``CAPACITY -> RUNTIME`` does not disturb the provider-429 passthrough:
+ :attr:`~pipelex.base_exceptions.ErrorReport.http_status` checks
+ ``provider_metadata.status_code`` before it consults the domain.
+ """
+ match self:
+ case InferenceErrorCategory.CONTENT:
+ return ErrorDomain.INPUT
+ case InferenceErrorCategory.CONFIGURATION:
+ return ErrorDomain.CONFIG
+ case InferenceErrorCategory.TRANSIENT | InferenceErrorCategory.CAPACITY | InferenceErrorCategory.AMBIGUOUS:
+ return ErrorDomain.RUNTIME
+ case InferenceErrorCategory.UNKNOWN:
+ return None
+
class CogtError(PipelexError):
error_category: InferenceErrorCategory | None = None
@@ -98,9 +128,19 @@ class CogtError(PipelexError):
# ``tests/unit/pipelex/cogt/test_cogt_provider_metadata_wrapper_wins.py``.
base_report = super().to_error_report()
own_retryable = self.error_category.is_retryable if self.error_category is not None else None
+ # ``error_domain`` is derived from this error's own category rather than declared per leaf
+ # class, so the two fields can never contradict each other on the wire. Precedence mirrors
+ # every other field here — a class-level ``error_domain`` set explicitly on the leaf wins,
+ # then the derivation, then whatever ``base_report`` already inherited from the cause chain
+ # (which for a ``CogtError`` cause is that cause's own derivation). Deriving from
+ # ``self.error_category`` and not from ``base_report.error_category`` is deliberate: the
+ # report field is typed ``str``, and the same wrapper-wins precedence on both fields makes
+ # the two agree anyway — an inherited category rides in with the domain it derived.
+ own_domain = self.error_category.error_domain if self.error_category is not None else None
return base_report.model_copy(
update={
"error_category": self.error_category or base_report.error_category,
+ "error_domain": self.error_domain or own_domain or base_report.error_domain,
"retryable": own_retryable if own_retryable is not None else base_report.retryable,
"model": self.model_handle or base_report.model,
"provider": self.backend_name or base_report.provider,
@@ -158,6 +198,15 @@ class ModelChoiceNotFoundError(CogtError):
"""
error_category = InferenceErrorCategory.CONFIGURATION
+ # Declared explicitly, against the grain of the CONFIGURATION category's ``CONFIG`` derivation,
+ # because the two fields are answering different questions here. The *category* is right: from
+ # the provider call's point of view the setup is wrong and no retry will help. But this class
+ # exists to report a mistyped model reference in material the caller authored — its message
+ # carries "Did you mean:" suggestions and lists the available options — so the caller is who
+ # fixes it, on the hosted API (a submitted method naming an unknown model) as much as in a
+ # local ``.mthds`` file. An operator-side deck fault surfaces as
+ # ``ModelDeckPresetValidatonError`` instead, which keeps the derived ``CONFIG``.
+ error_domain = ErrorDomain.INPUT
def __init__(
self,
diff --git a/pipelex/pipeline/exceptions.py b/pipelex/pipeline/exceptions.py
index 4f9a6535f..c1be6f79c 100644
--- a/pipelex/pipeline/exceptions.py
+++ b/pipelex/pipeline/exceptions.py
@@ -232,10 +232,19 @@ class PipeIOContractError(PipelexError):
class PipelineInputContentError(PipelexError):
"""A pipeline input's content reference (url) is unusable.
- Raised by the input normalizer when an Image/Document input carries a
- blank url, or a local path that cannot be read. The caller supplied the
- value — INPUT domain, so API servers answer 422, never a sanitized 500
- (a blank url used to surface as IsADirectoryError('.') → 500).
+ Raised by the input normalizer when an Image/Document input carries a local
+ path that cannot be read. The caller supplied the value — INPUT domain, so
+ API servers answer 422, never a sanitized 500 (a blank url used to surface
+ as IsADirectoryError('.') → 500).
+
+ Deliberately NOT caller-facing: the message names the resolved path and the
+ ``OSError`` subclass that rejected it, which are server-side filesystem
+ facts. Surviving STRICT disclosure would turn the report into an
+ existence/permission oracle over the runner's filesystem for any
+ authenticated caller — ``PermissionError`` on a path that exists reads
+ differently from ``FileNotFoundError`` on one that does not. The
+ caller-facing half of this family is ``PipelineInputUrlMissingError``,
+ whose message carries nothing but the accepted schemes.
"""
error_domain = ErrorDomain.INPUT
@@ -245,4 +254,16 @@ class PipelineInputContentError(PipelexError):
"Provide a valid url on every Image/Document input (https://, data:, pipelex-storage://, or an existing local file when running locally)."
),
)
- caller_facing_message = True
+
+
+class PipelineInputUrlMissingError(PipelineInputContentError):
+ """An Image/Document input carries a blank url.
+
+ The message states only the accepted schemes — no path, no server-side fact
+ — so it is caller-facing copy and survives STRICT disclosure intact, where
+ the placeholder would leave the caller with nothing to act on.
+ (``caller_facing_message`` is the *report* field; the class-level flag that
+ sets it is ``_authors_caller_facing_message``.)
+ """
+
+ _authors_caller_facing_message = True
diff --git a/pipelex/pipeline/input_normalizer.py b/pipelex/pipeline/input_normalizer.py
index fe16fc61c..dc37b854b 100644
--- a/pipelex/pipeline/input_normalizer.py
+++ b/pipelex/pipeline/input_normalizer.py
@@ -17,7 +17,7 @@ from pipelex.core.stuffs.document_content import DocumentContent
from pipelex.core.stuffs.image_content import ImageContent
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.structured_content import StructuredContent
-from pipelex.pipeline.exceptions import PipelineInputContentError
+from pipelex.pipeline.exceptions import PipelineInputContentError, PipelineInputUrlMissingError
from pipelex.runtime_hub import get_storage_provider
from pipelex.tools.misc.file_utils import load_binary_async
from pipelex.tools.misc.filetype_utils import detect_file_type_from_bytes
@@ -220,7 +220,7 @@ async def _normalize_url_content(
"""
if not content.url.strip():
msg = f"{type(content).__name__} input has a blank url — provide https://, data:, pipelex-storage://, or a local file path."
- raise PipelineInputContentError(msg)
+ raise PipelineInputUrlMissingError(msg)
resolved_uri = resolve_uri(content.url)
diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txt
index 0b921f572..7b7532c25 100644
--- a/tests/data/errors/error_identity.txt
+++ b/tests/data/errors/error_identity.txt
@@ -242,6 +242,7 @@ PipelexSetupError | Pipelex setup | https://docs.pipelex.com/latest/errors/pipel
PipelexUnexpectedError | Unexpected internal error | https://docs.pipelex.com/latest/errors/pipelex-unexpected-error/
PipelineExecutionError | Pipeline execution | https://docs.pipelex.com/latest/errors/pipeline-execution-error/
PipelineInputContentError | Pipeline input content | https://docs.pipelex.com/latest/errors/pipeline-input-content-error/
+PipelineInputUrlMissingError | Pipeline input url missing | https://docs.pipelex.com/latest/errors/pipeline-input-url-missing-error/
PipelineManagerAlreadyExistsError | Pipeline manager already exists | https://docs.pipelex.com/latest/errors/pipeline-manager-already-exists-error/
PipelineManagerNotFoundError | Pipeline manager not found | https://docs.pipelex.com/latest/errors/pipeline-manager-not-found-error/
PluginApiVersionMismatchError | Plugin api version mismatch | https://docs.pipelex.com/latest/errors/plugin-api-version-mismatch-error/
diff --git a/tests/unit/pipelex/cli/test_agent_output.py b/tests/unit/pipelex/cli/test_agent_output.py
index 609bd71a9..b5704be80 100644
--- a/tests/unit/pipelex/cli/test_agent_output.py
+++ b/tests/unit/pipelex/cli/test_agent_output.py
@@ -24,8 +24,15 @@ from pipelex.cli.agent_cli.commands.agent_output import (
record_setup_warning,
set_agent_cli_error_format,
)
-from pipelex.cogt.exceptions import CogtError, InferenceBackendCredentialsError, InferenceBackendCredentialsErrorType, InferenceErrorCategory
+from pipelex.cogt.exceptions import (
+ CogtError,
+ InferenceBackendCredentialsError,
+ InferenceBackendCredentialsErrorType,
+ InferenceErrorCategory,
+ ModelChoiceNotFoundError,
+)
from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
+from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.pipeline.exceptions import ValidateBundleError
if TYPE_CHECKING:
@@ -340,17 +347,45 @@ class TestAgentOutput:
assert "retryable" not in parsed
def test_agent_error_error_domain_and_category_coexist(self, capsys: pytest.CaptureFixture[str]) -> None:
- """error_domain (from lookup) and error_category (from report) should both appear."""
- # Use an error_type that is in AGENT_ERROR_DOMAINS
- error_type = "ModelChoiceNotFoundError"
+ """error_domain (from lookup) and error_category (from report) should both appear.
+
+ The cause carries the ``UNKNOWN`` category deliberately: every other category derives an
+ ``error_domain`` onto the report, and the report-first read then wins outright, so the
+ lookup fallback would never be exercised. ``UNKNOWN`` asserts no domain — classification
+ itself failed — which leaves exactly the composition this test is about: the category comes
+ from the report, the domain from the lookup.
+ """
+ # An error_type in AGENT_ERROR_DOMAINS that is NOT a CogtError subclass, so no derived
+ # domain can pre-empt the lookup.
+ error_type = "PipeOperatorModelChoiceError"
assert error_type in AGENT_ERROR_DOMAINS, "precondition: error_type must be in AGENT_ERROR_DOMAINS"
- cause = CogtError("model not found", error_category=InferenceErrorCategory.CONFIGURATION)
+ cause = CogtError("model not found", error_category=InferenceErrorCategory.UNKNOWN)
with pytest.raises(typer.Exit):
agent_error("model not found", error_type=error_type, cause=cause)
parsed = json.loads(capsys.readouterr().err)
assert parsed["error_domain"] == AGENT_ERROR_DOMAINS[error_type]
+ assert parsed["error_category"] == "unknown"
+
+ def test_agent_error_report_domain_beats_the_lookup(self, capsys: pytest.CaptureFixture[str]) -> None:
+ """A categorized CogtError cause supplies the domain itself, so the lookup is not consulted.
+
+ `ModelChoiceNotFoundError` used to be an `AGENT_ERROR_DOMAINS` entry reading `input`. It now
+ declares that domain on the class, which is what the report carries — same answer for this
+ CLI, from the single source of truth the drift test enforces.
+ """
+ cause = ModelChoiceNotFoundError(
+ message="model not found",
+ model_type=ModelType.LLM,
+ model_choice="gpt-nope",
+ )
+ with pytest.raises(typer.Exit):
+ agent_error("model not found", error_type="ModelChoiceNotFoundError", cause=cause)
+
+ parsed = json.loads(capsys.readouterr().err)
+ assert "ModelChoiceNotFoundError" not in AGENT_ERROR_DOMAINS, "the class is the single source of truth now"
+ assert parsed["error_domain"] == "input"
assert parsed["error_category"] == "configuration"
def test_agent_error_uses_report_error_domain(self, capsys: pytest.CaptureFixture[str]) -> None:
diff --git a/tests/unit/pipelex/cli/test_agent_output_drift.py b/tests/unit/pipelex/cli/test_agent_output_drift.py
index 058200a5f..49d59aba8 100644
--- a/tests/unit/pipelex/cli/test_agent_output_drift.py
+++ b/tests/unit/pipelex/cli/test_agent_output_drift.py
@@ -11,6 +11,7 @@ import importlib
from pipelex.base_exceptions import PipelexError
from pipelex.cli.agent_cli.commands.agent_output import AGENT_ERROR_DOMAINS, AGENT_ERROR_HINTS, RETRYABLE_ERROR_TYPES
+from pipelex.cogt.exceptions import CogtError
# Modules defining every PipelexError subclass referenced by the lookup dicts.
# Imported so PipelexError.__subclasses__() sees them when the registry is built.
@@ -91,6 +92,30 @@ class TestAgentOutputDrift:
f"is redundant — remove it so the class is the single source of truth."
)
+ def test_category_derived_error_domain_not_duplicated_in_dict(self) -> None:
+ """A CogtError subclass whose error_category derives a domain must not sit in AGENT_ERROR_DOMAINS either.
+
+ Such a class self-describes without declaring an ``error_domain`` of its own:
+ ``InferenceErrorCategory.error_domain`` derives one and ``CogtError.to_error_report()``
+ puts it on the report, so ``agent_error()``'s report-first read always wins and the
+ lookup entry is unreachable. ``test_class_level_error_domain_not_duplicated_in_dict``
+ does not catch these, because the class attribute is genuinely ``None``.
+ """
+ for cls in _all_pipelex_error_subclasses():
+ if not issubclass(cls, CogtError):
+ continue
+ category = cls.error_category
+ if category is None:
+ continue
+ derived_domain = category.error_domain
+ if derived_domain is None:
+ continue
+ assert cls.__name__ not in AGENT_ERROR_DOMAINS, (
+ f"{cls.__name__} derives error_domain {derived_domain!r} from its {category!r} category, "
+ f"so its AGENT_ERROR_DOMAINS entry can never be read — remove it. If that derived domain "
+ f"is wrong for this class, declare an explicit class-level error_domain on the class instead."
+ )
+
def test_class_level_user_action_not_duplicated_in_dict(self) -> None:
"""A subclass that declares class-level user_action must not also sit in AGENT_ERROR_HINTS."""
for cls in _all_pipelex_error_subclasses():
diff --git a/tests/unit/pipelex/cogt/test_data.py b/tests/unit/pipelex/cogt/test_data.py
index f1a211d49..f8dc63774 100644
--- a/tests/unit/pipelex/cogt/test_data.py
+++ b/tests/unit/pipelex/cogt/test_data.py
@@ -1,5 +1,6 @@
from typing import ClassVar
+from pipelex.base_exceptions import ErrorDomain
from pipelex.cogt.exceptions import InferenceErrorCategory
@@ -12,3 +13,16 @@ class ExceptionTestData:
("capacity_not_retryable", InferenceErrorCategory.CAPACITY, False),
("ambiguous_not_retryable", InferenceErrorCategory.AMBIGUOUS, False),
]
+
+ # (topic, category, expected_error_domain, expected_http_status)
+ # Exhaustive over InferenceErrorCategory — the exhaustiveness itself is asserted by
+ # ``test_category_domain_cases_cover_every_category``, so a new category cannot be added
+ # without deciding which domain it maps to.
+ CATEGORY_DOMAIN_CASES: ClassVar[list[tuple[str, InferenceErrorCategory, ErrorDomain | None, int]]] = [
+ ("transient_is_runtime", InferenceErrorCategory.TRANSIENT, ErrorDomain.RUNTIME, 500),
+ ("configuration_is_config", InferenceErrorCategory.CONFIGURATION, ErrorDomain.CONFIG, 500),
+ ("content_is_input", InferenceErrorCategory.CONTENT, ErrorDomain.INPUT, 422),
+ ("capacity_is_runtime", InferenceErrorCategory.CAPACITY, ErrorDomain.RUNTIME, 500),
+ ("ambiguous_is_runtime", InferenceErrorCategory.AMBIGUOUS, ErrorDomain.RUNTIME, 500),
+ ("unknown_asserts_no_domain", InferenceErrorCategory.UNKNOWN, None, 500),
+ ]
diff --git a/tests/unit/pipelex/cogt/test_inference_error_domain.py b/tests/unit/pipelex/cogt/test_inference_error_domain.py
new file mode 100644
index 000000000..159ebf6a0
--- /dev/null
+++ b/tests/unit/pipelex/cogt/test_inference_error_domain.py
@@ -0,0 +1,135 @@
+"""The `InferenceErrorCategory` -> `ErrorDomain` derivation on the `CogtError` family.
+
+An inference failure used to report no `error_domain` at all, so every one of them — a
+content-policy refusal included — answered HTTP 500. The category the worker already
+assigned is the authoritative statement of *whose fault it is*, so the domain is derived
+from it rather than declared a second time on each of the several dozen leaf classes.
+"""
+
+import pytest
+
+from pipelex.base_exceptions import ErrorDomain, PipelexError
+from pipelex.cogt.exceptions import CogtError, InferenceErrorCategory, LLMCompletionError
+from pipelex.cogt.inference.error_classification import ProviderErrorMetadata
+from pipelex.cogt.inference.provider_name import ProviderName
+from tests.unit.pipelex.cogt.test_data import ExceptionTestData
+
+
+class _ExplicitInputDomainError(CogtError):
+ """Test-only leaf that declares a domain of its own, against its category's grain."""
+
+ error_domain = ErrorDomain.INPUT
+ error_category = InferenceErrorCategory.CONFIGURATION
+
+
+class _InputDomainCauseError(PipelexError):
+ """Test-only non-Cogt cause carrying an INPUT domain, to exercise the cause fallback."""
+
+ error_domain = ErrorDomain.INPUT
+
+
+class TestInferenceErrorDomain:
+ """InferenceErrorCategory.error_domain, and how CogtError.to_error_report() derives from it."""
+
+ # --- the mapping itself ---
+
+ @pytest.mark.parametrize(
+ ("_topic", "category", "expected_domain", "_expected_status"),
+ ExceptionTestData.CATEGORY_DOMAIN_CASES,
+ )
+ def test_category_error_domain(
+ self,
+ _topic: str,
+ category: InferenceErrorCategory,
+ expected_domain: ErrorDomain | None,
+ _expected_status: int,
+ ) -> None:
+ """Each category maps to the domain that says who can fix that class of failure."""
+ assert category.error_domain is expected_domain
+
+ def test_category_domain_cases_cover_every_category(self) -> None:
+ """The parametrized table is exhaustive — a new category cannot slip in undecided."""
+ covered = {category for _topic, category, _domain, _status in ExceptionTestData.CATEGORY_DOMAIN_CASES}
+ assert covered == set(InferenceErrorCategory)
+
+ def test_unknown_asserts_no_domain(self) -> None:
+ """UNKNOWN means classification failed, so it must not assert a domain it does not know."""
+ assert InferenceErrorCategory.UNKNOWN.error_domain is None
+
+ # --- the derivation on the report ---
+
+ @pytest.mark.parametrize(
+ ("_topic", "category", "expected_domain", "expected_status"),
+ ExceptionTestData.CATEGORY_DOMAIN_CASES,
+ )
+ def test_report_derives_domain_from_category(
+ self,
+ _topic: str,
+ category: InferenceErrorCategory,
+ expected_domain: ErrorDomain | None,
+ expected_status: int,
+ ) -> None:
+ """A categorized CogtError reports the derived domain and the HTTP status it implies."""
+ report = LLMCompletionError("boom", error_category=category).to_error_report()
+ assert report.error_domain == expected_domain
+ assert report.http_status == expected_status
+
+ def test_content_failure_is_now_a_422(self) -> None:
+ """The behavior change: a content-classified inference failure is the caller's to fix."""
+ report = LLMCompletionError("the prompt was refused", error_category=InferenceErrorCategory.CONTENT).to_error_report()
+ assert report.error_domain == ErrorDomain.INPUT
+ assert report.http_status == 422
+
+ def test_uncategorized_cogt_error_still_has_no_domain(self) -> None:
+ """No category means nothing to derive from — the report stays unclassified, and 500."""
+ report = CogtError("plain error").to_error_report()
+ assert report.error_domain is None
+ assert report.http_status == 500
+
+ def test_explicit_class_domain_beats_the_derivation(self) -> None:
+ """A leaf that declares its own domain keeps it, even when its category maps elsewhere."""
+ report = _ExplicitInputDomainError("declared its own domain").to_error_report()
+ assert report.error_category == InferenceErrorCategory.CONFIGURATION
+ assert report.error_domain == ErrorDomain.INPUT
+
+ def test_uncategorized_cogt_error_still_inherits_the_cause_domain(self) -> None:
+ """With nothing of its own to derive from, the cause chain still supplies the domain."""
+ cogt_error = CogtError("wrapped")
+ cogt_error.__cause__ = _InputDomainCauseError("the caller's fault")
+ report = cogt_error.to_error_report()
+ assert report.error_domain == ErrorDomain.INPUT
+
+ def test_own_category_beats_the_cause_domain(self) -> None:
+ """Wrapper-wins: the outer error's own category decides, as it already does for the category."""
+ cogt_error = CogtError("wrapped", error_category=InferenceErrorCategory.CONFIGURATION)
+ cogt_error.__cause__ = _InputDomainCauseError("the caller's fault")
+ report = cogt_error.to_error_report()
+ assert report.error_domain == ErrorDomain.CONFIG
+
+ def test_provider_429_still_wins_over_the_derived_domain(self) -> None:
+ """The rate-limit passthrough is checked before the domain, so CAPACITY -> RUNTIME cannot mask it."""
+ report = LLMCompletionError(
+ "rate limited",
+ error_category=InferenceErrorCategory.CAPACITY,
+ provider_metadata=ProviderErrorMetadata(provider=ProviderName.OPENAI, sdk_exception_type="RateLimitError", status_code=429),
+ ).to_error_report()
+ assert report.error_domain == ErrorDomain.RUNTIME
+ assert report.http_status == 429
+
+ # --- the invariant that keeps the two fields from disagreeing on the wire ---
+
+ @pytest.mark.parametrize(
+ ("_topic", "category", "_expected_domain", "_expected_status"),
+ ExceptionTestData.CATEGORY_DOMAIN_CASES,
+ )
+ def test_domain_and_category_never_disagree(
+ self,
+ _topic: str,
+ category: InferenceErrorCategory,
+ _expected_domain: ErrorDomain | None,
+ _expected_status: int,
+ ) -> None:
+ """For any CogtError with a category and no declared domain, the two report fields agree."""
+ report = LLMCompletionError("boom", error_category=category).to_error_report()
+ assert report.error_category is not None
+ assert report.error_domain == InferenceErrorCategory(report.error_category).error_domain
diff --git a/tests/unit/pipelex/exceptions/test_class_level_metadata.py b/tests/unit/pipelex/exceptions/test_class_level_metadata.py
index b43aac316..0d7e8498b 100644
--- a/tests/unit/pipelex/exceptions/test_class_level_metadata.py
+++ b/tests/unit/pipelex/exceptions/test_class_level_metadata.py
@@ -17,7 +17,13 @@ from pipelex.cogt.exceptions import (
)
from pipelex.core.stuffs.exceptions import DateContentError
from pipelex.mthds_parsing.exceptions import MthdsParserError
-from pipelex.pipeline.exceptions import PipeExecutionError, PipelineExecutionError, ValidateBundleError
+from pipelex.pipeline.exceptions import (
+ PipeExecutionError,
+ PipelineExecutionError,
+ PipelineInputContentError,
+ PipelineInputUrlMissingError,
+ ValidateBundleError,
+)
from pipelex.plugins.exceptions import UnknownSecretsMethodError, UnknownStorageMethodError
from pipelex.system.exceptions import EnvVarNotFoundError
from pipelex.system.pipe_run_mode import PipeRunMode
@@ -47,6 +53,7 @@ class TestClassLevelMetadata:
("pipeline_execution", _PIPELINE_EXEC_ERROR, ErrorDomain.RUNTIME),
("pipe_execution", PipeExecutionError("boom"), ErrorDomain.RUNTIME),
("validate_bundle", ValidateBundleError("boom"), ErrorDomain.INPUT),
+ ("pipeline_input_content", PipelineInputContentError("boom"), ErrorDomain.INPUT),
("interpreter", MthdsParserError("boom"), ErrorDomain.INPUT),
("setup", PipelexSetupError("boom"), ErrorDomain.CONFIG),
("config", PipelexConfigError("boom"), ErrorDomain.CONFIG),
@@ -101,6 +108,15 @@ class TestClassLevelMetadata:
[
("interpreter", MthdsParserError("boom"), True),
("validate_bundle", ValidateBundleError("boom"), True),
+ # Regression pin: this class declared the *report field* name (``caller_facing_message``)
+ # instead of the class-level flag (``_authors_caller_facing_message``), so its
+ # caller-facing message was silently redacted under STRICT disclosure.
+ ("pipeline_input_url_missing", PipelineInputUrlMissingError("boom"), True),
+ # Security pin, and the reason the family is split: this class's message names the
+ # resolved local path and the OSError subclass that rejected it. Flagging it
+ # caller-facing would let STRICT disclosure answer "does this server-side path exist,
+ # and may the runner read it?" for any authenticated caller.
+ ("pipeline_input_content", PipelineInputContentError("boom"), False),
("csv", CsvError("boom"), True),
("unknown_storage_method", UnknownStorageMethodError(method="bogus", registered_methods=["local", "s3"]), True),
("unknown_secrets_method", UnknownSecretsMethodError(method="bogus", registered_methods=["env"]), True),
diff --git a/tests/unit/pipelex/exceptions/test_wrapper_error_enrichment.py b/tests/unit/pipelex/exceptions/test_wrapper_error_enrichment.py
index afbd390cd..84d25b8ac 100644
--- a/tests/unit/pipelex/exceptions/test_wrapper_error_enrichment.py
+++ b/tests/unit/pipelex/exceptions/test_wrapper_error_enrichment.py
@@ -49,6 +49,32 @@ class TestWrapperErrorEnrichment:
assert report.error_category == InferenceErrorCategory.TRANSIENT
assert report.retryable is True
+ def test_surfaces_input_domain_of_a_content_categorized_cause(self) -> None:
+ """A CONTENT-categorized CogtError reaches the wrapper as INPUT / 422, not the generic RUNTIME floor.
+
+ This is what the class docstring has always promised — that the RUNTIME floor applies only
+ when the cause chain surfaces no domain. Until the CogtError family derived a domain from its
+ category, no inference failure ever surfaced one, so the promise was vacuous and the floor
+ fired every time.
+ """
+ cogt_error = CogtError(message="the prompt was refused", error_category=InferenceErrorCategory.CONTENT)
+ pipe_run_error = PipeRunError(message="pipe failed", run_mode=PipeRunMode.LIVE, pipe_code="some_pipe")
+ pipe_run_error.__cause__ = cogt_error
+ pipe_router_error = PipeRouterError(
+ message="router failed",
+ run_mode=PipeRunMode.LIVE,
+ pipe_code="some_pipe",
+ output_name=None,
+ pipe_stack=["some_pipe"],
+ )
+ pipe_router_error.__cause__ = pipe_run_error
+
+ report = _make_pipeline_execution_error(cause=pipe_router_error).to_error_report()
+
+ assert report.error_domain == ErrorDomain.INPUT, "the wrapper's RUNTIME floor must not mask a caller-fixable cause"
+ assert report.http_status == 422
+ assert report.error_category == InferenceErrorCategory.CONTENT
+
def test_falls_back_to_runtime_unknown_without_cause(self) -> None:
"""With no PipelexError cause, PipelineExecutionError reports the generic RUNTIME / UNKNOWN floor."""
report = _make_pipeline_execution_error(cause=None).to_error_report()
diff --git a/tests/unit/pipelex/pipeline/test_input_normalizer.py b/tests/unit/pipelex/pipeline/test_input_normalizer.py
index d41a90b8a..bf3226235 100644
--- a/tests/unit/pipelex/pipeline/test_input_normalizer.py
+++ b/tests/unit/pipelex/pipeline/test_input_normalizer.py
@@ -5,6 +5,11 @@ with a blank url resolved as local path '', `Path('')` became `'.'`, and the
uncaught `IsADirectoryError` escaped as an InternalServerError. Both the blank
url and any unreadable local path must surface as the INPUT-domain
`PipelineInputContentError` (→ 422 at the API layer), never a sanitized 500.
+
+The family is split on what its message may disclose: the blank-url arm
+(`PipelineInputUrlMissingError`) names only the accepted schemes and is
+caller-facing copy, while the unreadable-path arm names the resolved path and
+the OSError subclass and must stay redacted under STRICT disclosure.
"""
from pathlib import Path
@@ -12,13 +17,14 @@ from pathlib import Path
import pytest
from pytest_mock import MockerFixture
+from pipelex.base_exceptions import INTERNAL_ERROR_PLACEHOLDER, DisclosureMode
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.document_content import DocumentContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
-from pipelex.pipeline.exceptions import PipelineInputContentError
+from pipelex.pipeline.exceptions import PipelineInputContentError, PipelineInputUrlMissingError
from pipelex.pipeline.input_normalizer import normalize_data_urls_to_storage
from pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract
@@ -49,9 +55,45 @@ class TestInputNormalizerUrlGuards:
async def test_blank_url_raises_input_error(self, mocker: MockerFixture, blank_url: str) -> None:
_patch_storage_and_config(mocker)
- with pytest.raises(PipelineInputContentError, match="blank url"):
+ with pytest.raises(PipelineInputUrlMissingError, match="blank url"):
await normalize_data_urls_to_storage(_memory_with_document(blank_url), storage_scope="test/scope")
+ async def test_blank_url_message_survives_strict_disclosure(self, mocker: MockerFixture) -> None:
+ """The blank-url message names only the accepted schemes, so STRICT keeps it.
+
+ Under the placeholder a caller who simply forgot a url is told "internal
+ error" and has nothing to act on.
+ """
+ _patch_storage_and_config(mocker)
+
+ with pytest.raises(PipelineInputUrlMissingError) as exc_info:
+ await normalize_data_urls_to_storage(_memory_with_document(""), storage_scope="test/scope")
+
+ strict = exc_info.value.to_error_report().to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert "blank url" in strict["message"]
+
+ async def test_unreadable_path_message_is_redacted_under_strict_disclosure(self, mocker: MockerFixture, tmp_path: Path) -> None:
+ """The unreadable-path message must NOT reach a caller under STRICT disclosure.
+
+ It names the resolved path and the OSError subclass that rejected it. Letting
+ those through would answer "does this server-side path exist, and may the runner
+ read it?" — ``PermissionError`` on an existing path reads differently from
+ ``FileNotFoundError`` on one that does not — for any authenticated caller of a
+ deployment that leaves ``is_upload_local_content_enabled`` on.
+ """
+ _patch_storage_and_config(mocker)
+ missing_path = tmp_path / "nope.pdf"
+
+ with pytest.raises(PipelineInputContentError) as exc_info:
+ await normalize_data_urls_to_storage(_memory_with_document(str(missing_path)), storage_scope="test/scope")
+
+ report = exc_info.value.to_error_report()
+ assert str(missing_path) in report.message, "precondition: the raw message carries the path"
+ strict = report.to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert strict["message"] == INTERNAL_ERROR_PLACEHOLDER
+ assert str(missing_path) not in str(strict)
+ assert "FileNotFoundError" not in str(strict)
+
async def test_directory_path_raises_input_error(self, mocker: MockerFixture, tmp_path: Path) -> None:
"""A local path that IS a directory must be an input error, not an
escaped IsADirectoryError (the '.'-as-url production failure mode).
diff --git a/wip/inference-error-domain/plan.md b/wip/inference-error-domain/plan.md
new file mode 100644
index 000000000..2656f92a7
--- /dev/null
+++ b/wip/inference-error-domain/plan.md
@@ -0,0 +1,93 @@
+---
+status: active
+item: L-260831-17614f
+---
+
+# Derive `error_domain` for the `CogtError` family from `InferenceErrorCategory`
+
+## Verdict on [L-260831-17614f](http://localhost:4747/i/L-260831-17614f)
+
+The item is justified, and the codebase already expects the fix. Verified on `dev` (2026-08-31):
+
+- `CogtError` (`pipelex/cogt/exceptions.py`) declares `error_category`, `user_action`, `provider_metadata`, `model_handle`, `backend_name` — and no `error_domain`. Reproduced: `LLMCompletionError("boom", error_category=CONTENT).to_error_report()` → `domain: None | status: 500 | category: content | retryable: False`.
+- `error_domain_to_http_status` (`pipelex/base_exceptions.py`) maps `None` → 500, so every caller-fixable inference failure (content-policy refusal, bad prompt parameter, malformed prompt image, gateway request-limit refusal once `feature/Gateway-request-limits` lands) answers as a server error. Only the provider-429 passthrough escapes.
+- The wrapper layer was *built* for this and is currently fed nothing: `PipelineExecutionError`'s docstring (`pipelex/pipeline/exceptions.py`) says it "inherits `error_domain` … from the wrapped `__cause__` chain … and only falls back to a generic RUNTIME / UNKNOWN classification when the cause chain surfaces none". The cause chain surfaces none, always — the fallback fires on every inference failure. The enrichment plumbing (`_enrich_error_report_from_cause`, `report.error_domain or cause_report.error_domain`) needs zero changes; only the leaf family must start supplying a domain.
+- It matches the established direction: [L-260829-643af2](http://localhost:4747/i/L-260829-643af2) (`error_domain=input` on `MethodRefError`) and [L-260829-fa8267](http://localhost:4747/i/L-260829-fa8267) (entry-lookup failures → INPUT) are the same move on neighboring families.
+
+## Design
+
+### The mapping — a property on `InferenceErrorCategory`
+
+Add `InferenceErrorCategory.error_domain`, an exhaustive `match` like the existing `is_retryable`:
+
+| Category | Domain | HTTP effect |
+|---|---|---|
+| `CONTENT` | `INPUT` | **500 → 422** — the behavior change |
+| `CONFIGURATION` | `CONFIG` | 500, unchanged — report becomes truthful |
+| `TRANSIENT`, `CAPACITY`, `AMBIGUOUS` | `RUNTIME` | 500, unchanged |
+| `UNKNOWN` | `None` | 500, unchanged — "could not classify" must not assert a domain |
+
+`UNKNOWN → None` is deliberate: `RUNTIME` would be a false claim, and unclassified already renders 500. `CAPACITY → RUNTIME` does not disturb the provider-429 passthrough, which `ErrorReport.http_status` checks before the domain.
+
+### The derivation — in `CogtError.to_error_report()`
+
+Derive from the **effective** category the report ends up carrying, so `error_domain` and `error_category` can never disagree on the wire:
+
+```python
+effective_category = self.error_category or base_report.error_category
+derived_domain = effective_category.error_domain if effective_category is not None else None
+# in the model_copy update:
+"error_domain": self.error_domain or derived_domain or base_report.error_domain,
+```
+
+Precedence: an explicit class-level `error_domain` wins (the `pipelex/cogt/content_generation/exceptions.py` classes already declaring `INPUT` keep it), then the category derivation, then the cause chain. This is the same wrapper-wins-when-set semantics the method already uses for every other field.
+
+### Semantics check on `CONTENT → INPUT`
+
+`ErrorDomain.INPUT` means "the caller can fix it". Every `CONTENT`-classified class is a property of the submitted material — `LLMPromptSpecError`, `LLMPromptParameterError`, `PromptImageFactoryError`, `PromptImageFormatError`, `PromptDocumentFactoryError`, `ImgGenPromptError`, `ImgGenParameterError` — plus provider content-policy refusals from `classify_inference_error`. On the hosted API the method and its inputs are both caller-side, so 422 is right. If a specific class turns out misclassified, that is a category fix on that class, not a reason to abandon the derivation.
+
+## Implementation steps
+
+1. **`InferenceErrorCategory.error_domain` property** in `pipelex/cogt/exceptions.py` (exhaustive `match`, returns `ErrorDomain | None`). Import `ErrorDomain` — already imported transitively via `base_exceptions`; add the explicit name.
+2. **Derivation in `CogtError.to_error_report()`** as above.
+3. **Tests** (red-green):
+ - Parametrized category → domain test, exhaustive over the enum.
+ - `LLMCompletionError(category=CONTENT)` report: `error_domain == INPUT`, `http_status == 422`.
+ - `CONFIGURATION` leaf → `CONFIG`, 500; `UNKNOWN` leaf → domain `None`, 500.
+ - Explicit declaration wins: a `content_generation` INPUT class with a non-CONTENT category keeps INPUT.
+ - Chain test: `PipelineExecutionError` wrapping a `CONTENT`-categorized `CogtError` surfaces `INPUT` / 422 through the wrapper (this pins the docstring's promise, which today is vacuously untested).
+ - Consistency invariant: for any `CogtError` with a category and no explicit domain, `report.error_domain == report.error_category.error_domain`.
+4. **Sweep existing tests** that pin `error_domain is None` or 500 for cogt/inference errors — at least `tests/unit/pipelex/exceptions/test_wrapper_error_enrichment.py`, `tests/unit/pipelex/providers/azure_rest/test_azure_worker_error_handling.py`, `tests/unit/pipelex/test_error_report_disclosure_mode.py`, plus whatever `make agent-test` reddens.
+5. **Docs**: update `docs/under-the-hood/error-model.md` — the Layer-1 classification section, the `error_domain_to_http_status` section, and the class-tree annotations gain the category→domain derivation. No `gei`/`gep` needed (no class added or renamed).
+6. **Changelog**: `Unreleased`, marked breaking — content-classified inference failures now report `error_domain: input` and answer HTTP 422 instead of 500.
+7. **Cross-repo verification** (read-only, same session): grep `pipelex-api` for hand-mapped inference statuses (it consumes `ErrorReport.http_status`, so it should pick the change up for free) and confirm `pipelex-server/transport/` remains untouched (grep for `error_domain` already comes back empty there). File ledger items only if a consumer hand-maps.
+
+## Implementation record
+
+Ratified and executed on `dev`. Every step above landed as written; what follows is only what the plan could not know in advance.
+
+**The derivation reads `self.error_category`, not the plan's `effective_category`.** The plan proposed deriving from `self.error_category or base_report.error_category`, but `ErrorReport.error_category` is typed `str` — and `model_copy(update=...)` bypasses validation, so what is actually in that field is whatever the previous layer put there. Calling `.error_domain` on it is not type-safe. The shipped form is `self.error_domain or own_domain or base_report.error_domain`, where `own_domain` derives from this error's own typed category, and it produces identical results for every case: an error with no category of its own inherits both fields from the cause chain in the same precedence order, so the two can still never disagree. The consistency invariant test pins that.
+
+**`UNKNOWN` is not in `CATEGORY_RETRYABLE_CASES`.** The existing category table in `tests/unit/pipelex/cogt/test_data.py` was never exhaustive. The new `CATEGORY_DOMAIN_CASES` is, and `test_category_domain_cases_cover_every_category` asserts the exhaustiveness against `set(InferenceErrorCategory)`, so a future category cannot be added without deciding its domain.
+
+**The "explicit declaration wins" precedence needed a synthetic subject.** The plan expected `pipelex/cogt/content_generation/exceptions.py` to supply one, but its three `INPUT`-domain classes are `PipelexError` subclasses, not `CogtError` — they never reach this derivation at all. No `CogtError` subclass declares an `error_domain` today, so the precedence is pinned by a test-only leaf (`_ExplicitInputDomainError`) declaring `INPUT` against a `CONFIGURATION` category.
+
+**A pre-existing bug found next door, and fixed.** `PipelineInputContentError` (`pipelex/pipeline/exceptions.py`) declared `caller_facing_message = True` — the name of the *report field*, not of the class-level flag `_authors_caller_facing_message`. The declaration was inert, so the class's caller-facing message (which names the caller's own url) was replaced by the internal-error placeholder under STRICT disclosure. Fixed, and pinned in the class-level-metadata sweep. Mutation-verified: reverting the flag name reddens the new row.
+
+**Review found the flag could not sit on that class as it stood, and split the family.** One class, two raise sites, two very different messages: `input_normalizer.py`'s blank-url arm states only the accepted schemes, while its unreadable-path arm interpolates `resolved_uri.path` and `type(exc).__name__`. Making the *class* caller-facing let the second one through STRICT too, which turns the report into an existence/permission oracle over the runner's filesystem — `PermissionError` on a path that exists reads differently from `FileNotFoundError` on one that does not — for any authenticated caller of a deployment leaving `is_upload_local_content_enabled` on (the shipped default, and what `pipelex-api`'s own `.pipelex/pipelex.toml` ships; `pipelex-server/api-hosted` sets it `false` in all three env configs after an earlier local-file-disclosure incident, so the hosted plane was never exposed). `PipelineInputUrlMissingError` now carries the blank-url message and the flag; `PipelineInputContentError` keeps the unreadable-path message and no flag. Pinned in both directions, in the metadata sweep and in `test_input_normalizer.py`, and mutation-verified: putting the flag back on the base class reddens both.
+
+**The review also caught a generated artifact the first pass left stale.** `ModelChoiceNotFoundError`'s explicit `error_domain = INPUT` changes its generated error page, and `make gep` had not been re-run. Regenerated alongside the new class's page.
+
+**Cross-repo verification came back clean.** `pipelex-server/transport/` mentions `error_domain` nowhere. `pipelex-api` consumes `ErrorReport.http_status` and picks the change up for free — its `_ERROR_TYPE_STATUS_OVERRIDES` map holds only `MethodRefError` subclasses (the separate [L-260829-643af2](http://localhost:4747/i/L-260829-643af2)) plus two pipeline/temporal classes, none of them `CogtError`, so there is no hand-mapping to unwind and no ledger item to file.
+
+**The sweep in step 4 was incomplete, and only the full suite found it.** `tests/unit/pipelex/cli/test_agent_output.py::test_agent_error_error_domain_and_category_coexist` went red. The cause was a real design collision, not a stale assertion: `agent_error()` reads the domain report-first and falls back to an `AGENT_ERROR_DOMAINS` lookup, and three of that dict's entries are `CogtError` subclasses whose derived domain now pre-empts the lookup. Two agreed with the dict (`ModelDeckPresetValidatonError`, `GatewayUnknownModelError` — both `CONFIGURATION` → `config`) and were removed as unreachable. One conflicted: `ModelChoiceNotFoundError` was mapped `input` there, deliberately, with a matching "check the model name for typos" hint — and derived `config`. Resolved on the class, not in the test: it now declares `error_domain = ErrorDomain.INPUT` explicitly, which the derivation's precedence honours. The category stays `CONFIGURATION`, correctly — the two fields answer different questions here, and the explicit declaration is exactly the escape hatch that precedence exists for.
+
+The module's own rule ("a class that self-describes must NOT appear in these dicts", enforced by `test_agent_output_drift.py`) already covered the class-level-attribute case but was blind to derivation, since `cls.error_domain` is genuinely `None` on those classes. A new arm, `test_category_derived_error_domain_not_duplicated_in_dict`, closes that — mutation-verified by re-adding `GatewayUnknownModelError` and watching it fail. The coexist test itself was rewritten rather than deleted: its premise (lookup domain + report category composing) is still reachable, but now only through an `UNKNOWN`-categorized cause, which is the one category that asserts no domain.
+
+**One consequence the plan did not anticipate: the validate hook's routing improves.** `docs/specs/hook-lint-pipeline.md` routes `error_domain ∈ {config, runtime}` to WARN and everything else — including an absent domain — to BLOCK. A `CONFIGURATION`-categorized failure surfacing through dry-run validate (a model-deck miss, missing credentials, an unknown gateway model) used to fall through to the default block, telling the agent to edit a `.mthds` file that was not at fault; it now warns, which is what that spec's own rationale asks for. `CONTENT`-categorized ones keep blocking, as they did before. The routing rule itself is unchanged, so no spec edit was needed.
+
+## Out of scope
+
+- The gateway request-limit classification itself — that is [L-260831-adcf35](http://localhost:4747/i/L-260831-adcf35), in flight on `feature/Gateway-request-limits` (worktree `_two`). This plan is independent and lands on `dev`; the two compose without ordering constraints.
+- Re-auditing whether each class's `error_category` is correct. The derivation faithfully translates today's classification; category fixes are their own diffs.
+- `MethodRefError` ([L-260829-643af2](http://localhost:4747/i/L-260829-643af2)) and entry-lookup domains ([L-260829-fa8267](http://localhost:4747/i/L-260829-fa8267)) — same direction, separate items.