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: give the --pipe slice miss the INPUT domain (#1182)
Louis Choquelbcd1b5722604
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex 4d3a0490a..75d81bee9 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,8 +1,8 @@contract = "cli-docs"-digest = "sha256:26081eec477bf9277bbb4dec7490c21f5ef92506b61e2e21555979440d760e9d"+digest = "sha256:f248fe213446457c1d1ba69bed204c9741fc91a1dd965969a3065ac7be4af20d"reviewed_by = "Louis Choquel"-reviewed_at = "2026-09-01T12:40:49Z"-rationale = "The two validate not-found arms stopped hardcoding PipeNotFoundError as the reported error_type and now name the class that actually failed, since the entry-shaped lookups raise EntryPipeNotFoundError. Reviewed docs/tools/cli/ — agent-cli.md documents the error envelope generically and enumerates no per-command error types, so nothing there was stale. Added the rule to the Error classification bullet in pipelex/cli/agent_cli/CLAUDE.md: with the report-first read, a hardcoded label detaches the reported class from the domain and hint the cause's report puts on the same envelope."+reviewed_at = "2026-09-01T14:16:51Z"+rationale = "The --pipe slice miss now raises EntryPipeNotFoundError, so the agent-CLI validate_pipe_in_bundle_core docstring names it instead of the base. Reviewed docs/tools/cli/ -- agent-cli.md and validate.md document the --pipe flag and the error envelope generically, naming no per-command error class and no exit code that moved (the not-found arm still exits 2), so nothing there was stale. Reviewed pipelex/cli/agent_cli/CLAUDE.md -- its Error classification bullet already states the report-first rule and cites the two validate not-found arms; this change is what finally makes the validate bundle arm's label carry a real domain, which the bullet already describes, so no edit was needed."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"@@ -47,7 +47,7 @@ rationale = "The two validate not-found arms stopped hardcoding PipeNotFoundErro"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:df5e7f80a328932ffde901eda8d0585d009678ad""pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:4bc7f4e91ddb3900a75356f8f8e6ba5a586a3690""pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"-"pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:6e9e8488573fe17d7769608e299879a092ceaf6c"+"pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:df07de7f203f57041907e080bc5fd80f9f593301""pipelex/cli/agent_cli/commands/validate/app.py" = "blob:d2d0ed19288c2d1c25be1650dd962189fcdb3b86""pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:27cc2c0b0a7fb5d3a232c6c3ce44663572e14260""pipelex/cli/agent_cli/commands/validate/method_cmd.py" = "blob:794914167c13975bc0cdff7b301a8268ff1b79b6"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6e1714cb4..2508e2915 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -20,6 +20,7 @@### Fixed- **An unknown or ambiguous entry `pipe_code` is reported as the caller's mistake, not a server fault**: the two entry-shaped lookups — the ones a CLI argument and an API request field land in — raised the bare `PipeNotFoundError` / `PipeLibraryError`, which declare no `error_domain`, so `ErrorReport.http_status` fell through to 500. A caller typo in the `pipe_code` of a run request therefore came back as an internal error, logged with a traceback and looking retryable to every SDK, for a mistake only the caller could fix — and the same typo already answered 422 on the build routes, which catch those classes explicitly, so one input produced two verdicts depending on the route. Two dedicated classes now carry `ErrorDomain.INPUT` and a `CHANGE_INPUT` action: `EntryPipeNotFoundError` when the entry lookup resolves nothing, `EntryPipeAmbiguousError` when a bare code is declared in several domains. Both subclass the errors they replace, so every existing catcher still matches, and every presentation derives from the domain at once — 422 on the API, the classification the agent CLI reports, the hosted status. Both are caller-facing copy that survives STRICT disclosure, since the message names only the caller's own `pipe_code` and the qualified `pipe_ref`s of bundles they loaded themselves — which is the only thing that makes an ambiguity actionable. In-body resolution is deliberately untouched: `get_optional_pipe` / `get_required_pipe` keep raising the undomained classes, because a ref written inside a bundle is not a caller's input mistake. The one crossing case is translated rather than left to leak: an ambiguous `alias->bare_code` is detected one frame down, inside the alias-scoped search, and the entry lookup re-raises it as `EntryPipeAmbiguousError` keeping the original as its cause. The agent CLI's `validate` arms stopped hardcoding `PipeNotFoundError` as the reported `error_type` and now name the class that actually failed, which is where the domain and hint on that envelope come from.+- **A typo'd `--pipe` / `pipe_ref` slice selector is reported as the caller's mistake too**: bundle validation narrowed to one pipe (`pipelex-agent validate bundle --pipe`, its `validate method --pipe` twin, and the `pipe_ref` field the build routes forward) raised the undomained `PipeNotFoundError` when the selector named nothing in the bundle, so the same caller typo that answers 422 through the entry lookups came back as a 500 through this one — the divergence the entry-pipe classification above was meant to remove, left in place one module over. The selector is entry-shaped input by the same definition (a code a human typed at an entry point), so the miss now raises `EntryPipeNotFoundError` with its `INPUT` domain and `CHANGE_INPUT` action, keeping the raise site's own bundle-scoped wording, which names only the codes the caller supplied. It is a subclass of the class it replaces, so every existing catcher still matches; the hand-written 422 mapping the public runner API keeps for this case becomes redundant once a release carries the change.- **A `native.JSON` input produced a fill-in template the runtime refused**: the input-form deriver grouped `native.JSON` with the three natives the standard calls structureless — `Dynamic`, `Anything` and `Composite` — so its descriptor node was `unknown`, which every inputs-template projection renders as the empty object. But `JSON` is not structureless: its pinned blueprint carries a required `json_obj`, and `JSONContent` refuses a payload without it, so the template a caller was handed for a `JSON` input could never be filled in and submitted. It now expands through the same pinned-structure arm as `Date`, `Html`, `Page`, `TextAndImages` and `SearchResult`, rendering `{"json_obj": {}}`, which the input shaper takes back. The engine's own `_pinned_structure` already drew the line in exactly this place — it returns a structure for `JSON` and `None` for the other three — so the deriver is now consistent with it, and the empty object stays the honest rendering for the natives that genuinely withhold their shape. The shared projection corpus gained a pipe covering all three of the natives it can reach at a slot position, which is where the defect had been sitting unmeasured. See [Projection Fixture Corpus](contribute/generate-projection-corpus.md).- **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).diff --git a/docs/errors/entry-pipe-not-found-error.md b/docs/errors/entry-pipe-not-found-error.mdindex f098e8e22..7cc8cadf4 100644--- a/docs/errors/entry-pipe-not-found-error.md+++ b/docs/errors/entry-pipe-not-found-error.md@@ -17,6 +17,6 @@ An entry-shaped `pipe_code` — one a human typed — resolved to no pipe.| `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 declaring it is loaded. |+| `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/under-the-hood/error-model.md b/docs/under-the-hood/error-model.mdindex 698c30f77..69160aa0b 100644--- a/docs/under-the-hood/error-model.md+++ b/docs/under-the-hood/error-model.md@@ -488,7 +488,7 @@ InferenceErrorCategory.TRANSIENT.is_retryable # True — only TRANSIENT| 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` |-| Unknown or ambiguous entry `pipe_code` (a CLI argument, a run request's field) | `EntryPipeNotFoundError` / `EntryPipeAmbiguousError` → `UserAction(CHANGE_INPUT)`; `error_domain = INPUT` → **HTTP 422**, and caller-facing under STRICT. The in-body lookups (`get_optional_pipe` / `get_required_pipe`) keep raising the undomained `PipeNotFoundError` / `PipeLibraryError`: a ref written inside a bundle is not the caller's input |+| Unknown or ambiguous entry `pipe_code` (a CLI argument, a run request's field, the `--pipe` / `pipe_ref` slice selector of bundle validation) | `EntryPipeNotFoundError` / `EntryPipeAmbiguousError` → `UserAction(CHANGE_INPUT)`; `error_domain = INPUT` → **HTTP 422**, and caller-facing under STRICT. The in-body lookups (`get_optional_pipe` / `get_required_pipe`) keep raising the undomained `PipeNotFoundError` / `PipeLibraryError`: a ref written inside a bundle is not the caller's input || 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/builder/operations/validate_ops.py b/pipelex/builder/operations/validate_ops.pyindex 13a9acb51..e4cba9c45 100644--- a/pipelex/builder/operations/validate_ops.py+++ b/pipelex/builder/operations/validate_ops.py@@ -185,7 +185,7 @@ async def validate_pipe_in_bundle(Loads the bundle's pipes into the library (so the requested pipe's dependencies resolve), thendry-runs ONLY the requested pipe via ``dry_run_pipe_codes`` — so an unrelated unimplemented``PipeSignature`` or failing sibling does not block validating one implemented slice. ``validate_bundle``- raises ``PipeNotFoundError`` when ``pipe_code`` is not defined in the bundle (no vacuous success).+ raises ``EntryPipeNotFoundError`` when ``pipe_code`` is not defined in the bundle (no vacuous success).Args:bundle_path: Path to the bundle file.@@ -197,7 +197,9 @@ async def validate_pipe_in_bundle(Raises:ValidateBundleError: If validation fails.- PipeNotFoundError: If ``pipe_code`` is not defined in the bundle.+ EntryPipeNotFoundError: If ``pipe_code`` is not defined in the bundle. The caller-supplied+ selector makes it INPUT-domained; it is a ``PipeNotFoundError`` subclass, so an existing+ ``except PipeNotFoundError`` still catches it."""result = await validate_bundle(mthds_file_path=bundle_path, library_dirs=library_dirs, dry_run_pipe_codes=[pipe_code])diff --git a/pipelex/cli/agent_cli/commands/validate/_validate_core.py b/pipelex/cli/agent_cli/commands/validate/_validate_core.pyindex 6e9e84885..df07de7f2 100644--- a/pipelex/cli/agent_cli/commands/validate/_validate_core.py+++ b/pipelex/cli/agent_cli/commands/validate/_validate_core.py@@ -210,7 +210,9 @@ async def validate_pipe_in_bundle_core(Raises:ValidateBundleError: If validation fails.- PipeNotFoundError: If `pipe_code` is not defined in the bundle.+ EntryPipeNotFoundError: If `pipe_code` is not defined in the bundle. The caller-supplied+ selector makes it INPUT-domained; it is a `PipeNotFoundError` subclass, so an existing+ `except PipeNotFoundError` still catches it."""result = await validate_bundle(mthds_file_path=bundle_path,diff --git a/pipelex/libraries/pipe/exceptions.py b/pipelex/libraries/pipe/exceptions.pyindex 41e81efd8..14db261ff 100644--- a/pipelex/libraries/pipe/exceptions.py+++ b/pipelex/libraries/pipe/exceptions.py@@ -16,18 +16,26 @@ class EntryPipeNotFoundError(PipeNotFoundError):The in-body sibling `PipeNotFoundError` reports a ref written inside a bundle, which is a faultof the loaded methods and stays unclassified. This one reports a code the caller supplied at an- entry point (a CLI argument, the `pipe_code` field of a run request), so it is the caller's own- typo: INPUT domain, which every presentation derives from at once — 422 rather than a 500 that- reads as retryable to every SDK.+ entry point (a CLI argument, the `pipe_code` field of a run request, the `--pipe` / `pipe_ref`+ slice selector of bundle validation), so it is the caller's own typo: INPUT domain, which every+ presentation derives from at once — 422 rather than a 500 that reads as retryable to every SDK.Caller-facing copy: the message names only the caller's own `pipe_code`, so STRICT disclosure- keeps it verbatim. The flag spans every raise site of the class, and this class has exactly one.+ keeps it verbatim. The flag spans every raise site of the class, so each one owes that invariant:+ a message here may name what the caller typed and nothing from the loaded library."""error_domain = ErrorDomain.INPUTuser_action = UserAction(kind=UserActionKind.CHANGE_INPUT,- detail="Check the pipe code for typos and make sure the bundle declaring it is loaded.",+ # Scope-neutral on purpose, because a class-level detail cannot name the scope its raise+ # sites work in and they do not share one: the entry lookup serves run, show and build as+ # much as validate, and misses because nothing loaded declares the code, while the `--pipe`+ # slice misses because the bundle being sliced does not declare it — even when another+ # loaded bundle does. Either wording that names one of those scopes is false at the other+ # site. Both raise sites carry a precise message of their own, so the detail only has to+ # stop asserting a scope it cannot know.+ detail="Check the pipe code for typos and make sure the bundle in scope for this operation declares it.",)_declared_title = "Entry pipe not found"_authors_caller_facing_message = Truediff --git a/pipelex/pipeline/validate_bundle.py b/pipelex/pipeline/validate_bundle.pyindex ee4cdc00c..9cc7d225e 100644--- a/pipelex/pipeline/validate_bundle.py+++ b/pipelex/pipeline/validate_bundle.py@@ -24,7 +24,7 @@ from pipelex.interpreter_hub import ()from pipelex.libraries.exceptions import LibraryError, LibraryLoadingErrorfrom pipelex.libraries.library_utils import get_pipelex_mthds_files_from_dirs-from pipelex.libraries.pipe.exceptions import PipeNotFoundError+from pipelex.libraries.pipe.exceptions import EntryPipeNotFoundError, PipeNotFoundErrorfrom pipelex.mthds_parsing.exceptions import MthdsParserErrorfrom pipelex.mthds_parsing.handle_pipe_errors import (categorize_pipe_factory_error,@@ -161,10 +161,13 @@ def translate_to_validate_bundle_error() -> Generator[None, None, None]:pipe_validation_errors=pipe_validation_errors,) from validation_errorexcept PipeNotFoundError:- # PipeNotFoundError is a PipeLibraryError (hence a LibraryError), but it is NOT a bundle- # merge/load failure: it means a requested --pipe slice names a pipe absent from the bundle.- # It has its own dedicated CLI handler (execute_validate's `except PipeNotFoundError`), so it- # must propagate raw rather than be folded into a ValidateBundleError by the arm below.+ # The base class on purpose: the slice miss raised by ``_pipes_to_dry_run`` is the+ # INPUT-domained ``EntryPipeNotFoundError`` subclass, and this arm must let it through raw,+ # domain and all. PipeNotFoundError is a PipeLibraryError (hence a LibraryError), but it is+ # NOT a bundle merge/load failure: it means a requested --pipe slice names a pipe absent from+ # the bundle. It has its own dedicated CLI handler (execute_validate's+ # `except PipeNotFoundError`), so it must propagate raw rather than be folded into a+ # ValidateBundleError by the arm below.raiseexcept LibraryError as library_error:# Library merge / load failures that are NOT pydantic ValidationErrors: undeclared@@ -214,8 +217,11 @@ def _pipes_to_dry_run(loaded_pipes: list[PipeAbstract], *, dry_run_pipe_codes: lnarrows the dry-run sweep to just the selected pipe (signatures are never an error either way — D-B).Raises:- PipeNotFoundError: when ``dry_run_pipe_codes`` names a pipe absent from the loaded bundle —- so a typo'd ``--pipe`` argument fails loudly instead of passing vacuously.+ EntryPipeNotFoundError: when ``dry_run_pipe_codes`` names a pipe absent from the loaded+ bundle — so a typo'd ``--pipe`` argument fails loudly instead of passing vacuously. The+ selector is caller-supplied entry-shaped input, not a ref written inside a bundle, so it+ carries the INPUT domain (→ 422) rather than the undomained base class (→ 500). Every+ ``except PipeNotFoundError`` downstream still matches: it is a subclass."""if dry_run_pipe_codes is None:return loaded_pipes@@ -226,7 +232,10 @@ def _pipes_to_dry_run(loaded_pipes: list[PipeAbstract], *, dry_run_pipe_codes: lif missing:missing_str = ", ".join(f"'{code}'" for code in sorted(missing))msg = f"Pipe(s) {missing_str} not found in the bundle. Check for typos and make sure they are declared in the bundle."- raise PipeNotFoundError(msg)+ # The bundle-scoped wording stays the raise site's own — more precise here than the class's+ # library-lookup message — and is safe under ``_authors_caller_facing_message``: it names only+ # the caller's own selector codes (derived from ``wanted``), nothing from the loaded library.+ raise EntryPipeNotFoundError(msg)return selecteddiff --git a/tests/integration/pipelex/cli/test_agent_validate_pipe_in_bundle.py b/tests/integration/pipelex/cli/test_agent_validate_pipe_in_bundle.pyindex e3e6bbeba..af070d024 100644--- a/tests/integration/pipelex/cli/test_agent_validate_pipe_in_bundle.py+++ b/tests/integration/pipelex/cli/test_agent_validate_pipe_in_bundle.py@@ -7,11 +7,12 @@ from typing import TYPE_CHECKINGimport pytest+from pipelex.base_exceptions import INTERNAL_ERROR_PLACEHOLDER, DisclosureMode, ErrorDomainfrom pipelex.cli.agent_cli.commands.validate._validate_core import (validate_bundle_core,validate_pipe_in_bundle_core,)-from pipelex.libraries.pipe.exceptions import PipeNotFoundError+from pipelex.libraries.pipe.exceptions import EntryPipeNotFoundErrorif TYPE_CHECKING:from collections.abc import Iterator@@ -179,8 +180,11 @@ class TestAgentValidatePipeInBundle:self,implemented_plus_signature_dir: Path,) -> None:- # Selecting a pipe that is not defined in the bundle is an error, not a vacuous success.- with pytest.raises(PipeNotFoundError):+ # Selecting a pipe that is not defined in the bundle is an error, not a vacuous success. The+ # `--pipe` / `pipe_ref` selector is entry-shaped input the caller typed, so the miss must be+ # the INPUT-domained EntryPipeNotFoundError — not the undomained base, which every+ # presentation would render as a 500 server fault for a mistake only the caller can fix.+ with pytest.raises(EntryPipeNotFoundError) as exc_info:asyncio.run(validate_pipe_in_bundle_core(bundle_path=implemented_plus_signature_dir / "bundle.mthds",@@ -188,6 +192,20 @@ class TestAgentValidatePipeInBundle:library_dirs=[implemented_plus_signature_dir],))+ report = exc_info.value.to_error_report()+ assert report.error_domain == ErrorDomain.INPUT+ assert report.http_status == 422+ # The raise site keeps its own bundle-scoped wording, which names the caller's own code.+ assert "does_not_exist" in report.message+ # `to_error_report()` never redacts, so the assertion above cannot prove the class-level+ # `_authors_caller_facing_message` invariant this raise site inherits. Project through the+ # STRICT serialization — the untrusted-surface one — where a message that is NOT declared+ # caller-facing is replaced by the placeholder. This is what pins the promise the class+ # docstring makes of every raise site: the wording may name what the caller typed, so it+ # survives verbatim, and nothing from the loaded library rides along with it.+ strict_payload = report.to_dict(disclosure_mode=DisclosureMode.STRICT)+ assert strict_payload["message"] != INTERNAL_ERROR_PLACEHOLDER+ assert "does_not_exist" in strict_payload["message"]def test_pipe_slice_cross_package_controller_reports_skipped_not_success(self,diff --git a/tests/unit/pipelex/exceptions/test_class_level_metadata.py b/tests/unit/pipelex/exceptions/test_class_level_metadata.pyindex 622fa7dae..14b82044f 100644--- a/tests/unit/pipelex/exceptions/test_class_level_metadata.py+++ b/tests/unit/pipelex/exceptions/test_class_level_metadata.py@@ -82,7 +82,7 @@ class TestClassLevelMetadata:("entry_pipe_not_found",EntryPipeNotFoundError("boom"),- "Check the pipe code for typos and make sure the bundle declaring it is loaded.",+ "Check the pipe code for typos and make sure the bundle in scope for this operation declares it.",),("entry_pipe_ambiguous",diff --git a/wip/pipe-slice-error-domain/plan.md b/wip/pipe-slice-error-domain/plan.mdnew file mode 100644index 000000000..6dc97db6a--- /dev/null+++ b/wip/pipe-slice-error-domain/plan.md@@ -0,0 +1,117 @@+---+status: active+item: L-260901-296dfb+---++# Give the `--pipe` / `pipe_ref` slice miss in `validate_bundle` the INPUT domain++Follow-up to the entry-pipe error-domain work (`wip/entry-pipe-error-domain/plan.md`, PR #1180), which deliberately left this raise site out of its diff and filed it as L-260901-296dfb.++## The bug, verified++`_pipes_to_dry_run` (`pipelex/pipeline/validate_bundle.py:229`) raises the bare, undomained `PipeNotFoundError` when `dry_run_pipe_codes` names a pipe absent from the loaded bundle. Its own docstring calls the trigger "a typo'd `--pipe` argument" — entry-shaped input a human typed, exactly the case PR #1180 classified for the two library lookups. The class declares no `error_domain`, so `ErrorReport.http_status` falls through `error_domain_to_http_status(None)` to 500.++Live probe on `dev` (same caller typo, two verdicts):++```bash+.venv/bin/pipelex-agent validate bundle tests/data/input_semantics/probe_bundle.mthds --pipe nonexistent_zzz --format json+# → error_type: PipeNotFoundError, NO error_domain, no hint++.venv/bin/pipelex-agent validate pipe nonexistent_zzz --format json+# → error_type: EntryPipeNotFoundError, error_domain: input, CHANGE_INPUT hint+```++The only consumer that repairs this is `pipelex-api`'s `api/routes/pipelex/build/runner.py:174`, which catches `PipeNotFoundError` by hand and maps it to a 422 — the same "one input, two verdicts depending on the route" shape PR #1180's changelog says it removes. Any other surface reaching `validate_bundle` with `dry_run_pipe_codes` renders the caller's typo as a server fault, logged with a traceback and looking retryable to every SDK.++## Design++**Raise `EntryPipeNotFoundError` at the existing site — no new class.** The `--pipe` / `pipe_ref` selector is entry-shaped input by the class's own definition ("one a human typed... a CLI argument, the `pipe_code` field of a run request"), so the concept already has a home. Reusing it means:++- Every current catcher keeps matching, because all of them catch the base `PipeNotFoundError`: the passthrough in `validate_bundle.py`'s `translate_to_validate_bundle_error` (`except PipeNotFoundError: raise`), the agent CLI arms (`bundle_cmd.py`, `pipe_cmd.py`), the bare CLI (`cli/commands/validate/_validate_core.py`), and `pipelex-api`'s hand catch.+- No new error identity: `make gei` / `make gep` produce no diff for a new class (verify by running them — the class docstring's summary line, which is all the generated page renders, does not change).+- The agent CLI arms already pass `error_type=type(exc).__name__` (PR #1180's carry-along), so the envelope will name `EntryPipeNotFoundError` and the INPUT domain + `CHANGE_INPUT` hint riding it report-first will finally be attributed to the class that declares them. `bundle_cmd.py:190`'s comment ("The real class, not the caught base") stops describing an intent and starts describing behaviour — no edit needed there.++**The message stays the raise site's own.** `_pipes_to_dry_run` keeps its bundle-scoped wording ("Pipe(s) 'x' not found in the bundle. Check for typos and make sure they are declared in the bundle.") — more precise here than the class's library-lookup message. This is safe under `_authors_caller_facing_message = True`: the flag spans every raise site of the class, and this message names only the caller's own `--pipe` codes (derived from `wanted`, which is caller-supplied), nothing from the loaded library.++**Docstring corrections that must ride the same diff:**++- `EntryPipeNotFoundError`'s docstring says "this class has exactly one [raise site]" — after this change it has two. Reword the caller-facing-copy paragraph to state the invariant per raise site instead of counting them.+- `_pipes_to_dry_run`'s `Raises:` section names `PipeNotFoundError` — update to `EntryPipeNotFoundError` and say why (caller-supplied selector → INPUT domain).+- `builder/operations/validate_ops.py`'s docstrings name `PipeNotFoundError` for this path — update the wording (the subclass still satisfies any `except`, but the docs should name the real class).++**Out of scope, unaffected:** the in-body lookups (`get_optional_pipe` / `get_required_pipe`) and `bundle_validator.py`'s sweep-time `except PipeNotFoundError` (it catches sub-pipe resolution misses during the dry-run sweep; `_pipes_to_dry_run` runs before the sweep and its raise never reaches that arm).++**The `pipelex-api` half is a dependent ledger item, not this diff.** Once a pipelex release carries this change, `build/runner.py`'s hand-written `except PipeNotFoundError` → 422 catch becomes redundant: the global `PipelexError` handler (`api/exception_handlers.py`) renders `report.http_status`, which the INPUT domain now makes 422 on its own. Dropping the catch is `pipelex-api` work gated on that release — filed as its own item, blocked by L-260901-296dfb (see the ledger).++## Phases++### Phase 1 — red tests++- `tests/integration/pipelex/cli/test_agent_validate_pipe_in_bundle.py::test_pipe_slice_unknown_pipe_raises_not_found`: tighten `pytest.raises(PipeNotFoundError)` to `EntryPipeNotFoundError`, and assert on the caught error's `to_error_report()`: `error_domain == ErrorDomain.INPUT`, `http_status == 422`, and the message still names the missing code. This is the red test: it fails on `dev` because the raise is the bare base class.+- Verify the class-metadata sweeps in `tests/unit/pipelex/exceptions/test_class_level_metadata.py` already pin `EntryPipeNotFoundError`'s domain, user action, and caller-facing flag (they do, from PR #1180) — nothing to add there.++### Phase 2 — implement++- `pipelex/pipeline/validate_bundle.py`: import `EntryPipeNotFoundError`, swap the raise at the `missing` check in `_pipes_to_dry_run`, update its `Raises:` docstring. Leave the `translate_to_validate_bundle_error` passthrough arm as `except PipeNotFoundError: raise` (the base catch is the point: it must let the subclass through raw), refreshing its comment to name the entry class.+- `pipelex/libraries/pipe/exceptions.py`: reword the `EntryPipeNotFoundError` docstring's "exactly one raise site" sentence.+- `pipelex/builder/operations/validate_ops.py`: update the docstring mentions.+- Phase 1's test goes green.++### Phase 3 — sweep, docs, gates++- Sweep the remaining catchers for message-matching or type branching the subclass would change — none expected: `_validate_core.py:242` (bare CLI, prints `str(exc)`), `pipe_cmd.py:187` (unreachable from this raise site but catches the base), `bundle_validator.py`'s sweep arm (unreachable, see Design).+- Run `make gei` and `make gep`; confirm both produce no diff (no new class, unchanged summary line). If `gep` does diff, commit the regenerated page.+- `docs/under-the-hood/error-model.md`: extend the Behavior Summary row for entry pipe lookups (line ~491) to mention the `--pipe` / `pipe_ref` bundle-slice miss as a third raise context of `EntryPipeNotFoundError`.+- `CHANGELOG.md` under `## [Unreleased]`: one condensed entry — fixed: a typo'd `--pipe` / `pipe_ref` slice selector in bundle validation now raises `EntryPipeNotFoundError` (INPUT domain → 422), matching the entry lookups, instead of the undomained base class that rendered 500 off the build route.+- `make agent-check`, targeted tests (`tests/unit/pipelex/pipeline/ tests/integration/pipelex/pipeline/ tests/unit/pipelex/cli/ tests/integration/pipelex/cli/`), then full `make agent-test` before the PR.++### Checkpoint++After Phase 3: record what landed, any deviations, and open the PR against `dev` with `Closes L-260901-296dfb` in the body. After the merge, the `pipelex-api` follow-up item becomes workable once a release carries the change.++## Checkpoint — all three phases landed++All three phases went in as designed. The raise site in `_pipes_to_dry_run` now raises `EntryPipeNotFoundError`, keeping its own bundle-scoped message, and the same live probe that opened this plan answers with `error_type: EntryPipeNotFoundError`, `error_domain: input` and the `CHANGE_INPUT` hint — the divergence against `validate pipe <typo>` is closed.++**What the design predicted and the run confirmed.** `make gei` and `make gep` both produced no diff, as expected for a reused class whose docstring summary line did not change. No catcher needed touching: every one of them catches the base `PipeNotFoundError`, and the whole targeted suite (pipeline, CLI at all three levels, libraries, exceptions, builder) is green with no assertion loosened anywhere. `bundle_cmd.py`'s `type(exc).__name__` label needed no edit and its comment now describes behaviour rather than intent — the probe output is the evidence.++**The one thing the plan did not anticipate: the `cli-docs` drift contract reopened.** The docstring edit in `pipelex/cli/agent_cli/commands/validate/_validate_core.py` is a trigger file, so `make agent-check` failed on an open contract even though the change is a two-line docstring. The review was done for real against both targets and found nothing stale: `docs/tools/cli/` documents the `--pipe` flag and the error envelope generically, naming no per-command error class, and no exit code moved (the not-found arm still exits 2); `pipelex/cli/agent_cli/CLAUDE.md`'s Error classification bullet already states the report-first rule and cites these two arms, and this change is precisely what gives the `validate bundle` arm's label a real domain to carry. Recorded with `make drift-ack CONTRACT=cli-docs`; the ack file rides the same commit.++**Deliberate wording choice on the class docstring.** The plan asked for the "exactly one raise site" sentence to be reworded to state the invariant per raise site instead of counting them, and that is what went in — the caller-facing-copy paragraph now says the flag spans every raise site and each one owes the invariant (name what the caller typed, nothing from the loaded library). The entry-point list in the first paragraph gained the slice selector alongside the CLI argument and the run request's `pipe_code`, so the class definition names all three of its doors.++**What is next.** The `pipelex-api` half stays a dependent item: once a release carries this change, `build/runner.py`'s hand-written `except PipeNotFoundError` → 422 catch is redundant, since the global handler renders `report.http_status` and the INPUT domain makes that 422 on its own.++## Pre-landing review — what was fixed and what was deferred++A pre-landing review (Claude adversarial subagent plus a Codex `exec` pass, both read-only against `dev`) confirmed the change is correct and found no reachable defect. The attacks that came back clean, with what was actually checked: `dry_run_pipe_codes` has exactly two in-repo call sites and both pass a caller-typed selector; `missing ⊆ wanted` by construction, so the message can only name caller strings; no code anywhere branches on the exact type or the `error_type` string for this hierarchy — every catcher is an `isinstance` on the base; the `except PipeNotFoundError: raise` passthrough at `validate_bundle.py:163` genuinely precedes `except LibraryError` at `:172` and no arm above it is an ancestor; and the error-identity snapshot and the generated error page were both re-derived with no diff.++Three things changed as a result.++**The changelog named a command that does not exist.** The entry said the fix covers `pipelex validate --pipe`. It does not: `pipelex validate bundle` carries no `--pipe` option at all (verified against `--help`), and the bare CLI's one `--pipe`, on `validate method`, routes through `execute_validate(pipe_code=…, bundle_path=None)` into the `elif pipe_code:` arm at `cli/commands/validate/_validate_core.py:174` → `get_required_entry_pipe` — the lookup PR #1180 already classified, never `_pipes_to_dry_run`. The raise site this campaign changed is reached only by `pipelex-agent validate bundle|method --pipe` and by `builder/operations/validate_pipe_in_bundle`, which `pipelex-api` calls with the request's `pipe_ref`. The entry now names those. The class docstring and the error-model row are unaffected: they describe the selector without claiming a binary.++**The new test could not see the invariant it was written to protect.** It asserted on `to_error_report()`, where the message is verbatim regardless of `_authors_caller_facing_message` — redaction happens only in `ErrorReport.to_dict(disclosure_mode=STRICT)`. Mutation-verified both ways: forcing the flag off left every test in the module green before, and reddens the new assertion now. This matters more after this campaign than before it, because the reworded docstring deliberately stops counting raise sites and says each one owes the invariant — so the promise needed a guard at a raise site, not only the class-level metadata sweep's guard on a hand-built instance.++**The class's `user_action` detail was false at the new raise site.** It read "make sure the bundle declaring it is loaded", which fits the library lookup but not the slice: `_pipes_to_dry_run` filters only the target bundle's pipes, so a pipe declared in a loaded `--library-dir` bundle still reports missing and the hint sent the caller to load something already loaded. Since a class-level `user_action` spans every raise site the same way the caller-facing flag does, the wording was changed to "make sure it is declared in the bundle being validated". That replacement was itself false at the other site, and the PR review caught it — see the round-1 section below for the wording that actually holds at both. The pinned expectation and the generated error page moved with it.++**Deferred, deliberately.**++- *The INPUT domain is a property of the call sites, not of the function.* Nothing in `_pipes_to_dry_run`'s signature constrains `dry_run_pipe_codes` to caller-typed input, and `validate_bundle` is a public entry point. The near-miss is one frame up: `cli/method_resolver.py` falls back to the fetched method manifest's `main_pipe`, and it stays out of the slice only because the agent CLI's `method_cmd.py` gates on the raw `--pipe` option while passing the resolved code. If that gate is ever loosened, a broken manifest would report as the caller's typo. Not a defect today — every reachable caller supplies a typed selector — and moving the classification up to the boundaries would mean two translation sites for one condition, which is what this campaign removed. Worth revisiting only if a caller genuinely needs to slice by a server-derived code.+- *The `error_type` on the wire changes for this path*, from `PipeNotFoundError` to `EntryPipeNotFoundError`. Python catchers are unaffected by subclassing, but a consumer string-matching `error_type` is not. A sweep across every sibling repo found no such consumer — `pipelex-api` catches the Python class, and no `error_type`→status map holds either name. The exposure is identical to the one PR #1180 accepted for the entry lookups, and the workspace's no-backward-compatibility rule covers it.+- *Two workspace spec lines still name the old class*, `docs/specs/pipelex-validation-api.md:130` and `:144`, both stale since PR #1180 rather than because of this change, and both describing paths this campaign does not touch. Filed as its own item against `workspace`, with the trace.+- *The translation passthrough lets a second, in-body class escape too.* `validate_bundle.py`'s already-loaded branch calls `get_required_pipe` inside the same `with translate_to_validate_bundle_error()` block, and that raises the plain `PipeNotFoundError`, which the `except PipeNotFoundError: raise` arm re-raises raw as a non-`ValidateBundleError` exactly as it does the entry subclass. Present identically on `dev` before this campaign and untouched by it. It is also close to unreachable: that branch only runs when the bundle path is already loaded, and it looks up the blueprint's own `[pipe.<code>]` keys qualified with the blueprint's own domain — refs the loader just registered. If it did fire, the CLI's dedicated not-found handler turns it into a clean exit 2 rather than a crash.+- *Two surfaces of the new behaviour have no test.* Nothing asserts the emitted agent-CLI envelope for the slice miss — the `error_type`, the `error_domain` and the exit code that `bundle_cmd.py`'s arm produces — and `builder/operations/validate_pipe_in_bundle` has no non-mocked not-found test, which is the entry the changelog's "422 through the build routes" claim actually rests on. Both are one-line passthroughs over behaviour the integration test already pins at the raise site, which is why they were left.+- *The `pipelex-api` follow-up is a wire change, not a pure cleanup.* Dropping that route's hand-written catch keeps 422 and the `input` domain, but hands the RFC 7807 `type`, `title` and `error_type` over to the class and loses the route's "not found in the submitted closure" framing in `detail` — and `type` is the field the hosted-envelope spec designates for SDK branching. Recorded on the dependent item so whoever works it decides deliberately.++## Review round 1 — the hint was still false, at the other site++The pre-landing review above rewrote the class's `user_action` detail to "make sure it is declared in the bundle being validated" and recorded it as true at both raise sites. It is not. The PR's local reviewers — Codex reading the branch diff, corroborated by an independent verification pass — caught that the replacement simply moved the falsehood from the rarer site to the busier one.++`get_required_entry_pipe` is not a validation door. It has thirteen call sites and only three of them validate: the rest are the pipeline execution seam behind `pipelex run pipe`, the agent CLI's `PIPELEX` runner arm and the hosted run request's `pipe_code`; `show pipe`; the four `cli/commands/build/` cores; the three hosted `builder/operations/` build ops; and the in-process dry run. On every one of those, nothing is being validated, and the detail reaches the caller as the agent-CLI `hint` and as `user_action` in the 422 body — it survives STRICT precisely because this class declares `_authors_caller_facing_message`. So the campaign shipped a remedy naming a thing that does not exist, on the majority of the paths that raise it.++The diagnosis of the *original* wording stands: `validate_bundle` discards what the `--library-dir` load returns, so `loaded_pipes` really is scoped to the submitted bundle and "make sure the bundle declaring it is loaded" really did send the caller to load something already loaded. Both wordings were false at exactly one site each.++The fix is to stop naming a scope at all, because a class-level detail spans raise sites that do not share one: **"Check the pipe code for typos and make sure the bundle in scope for this operation declares it."** Each raise site already carries a precise message of its own — the entry lookup's "make sure its bundle is loaded", the slice's "make sure they are declared in the bundle" — so the class detail does not have to supply the scope, only to stop asserting a wrong one. A per-site override or a class split would have bought the same accuracy for two translation sites where one honest sentence does, which is the shape this campaign existed to remove.++The pinned expectation in the class-metadata sweep and the generated error page moved with the string; `make gep` rewrote exactly the one `user_action` row and nothing else. The error-identity snapshot is untouched, as expected for a detail-only change.++What the same round confirmed rather than changed, each checked against the code: the caller-facing invariant genuinely holds at the new raise site, since `missing = wanted - matched` puts the library-derived strings only on the subtrahend side where they can remove elements but never contribute one; the entry subclass really does survive `translate_to_validate_bundle_error`, because the passthrough arm precedes the `LibraryError` arm that would have folded it into an undomained `ValidateBundleError` and made the whole campaign a no-op; and nothing anywhere dispatches on the exact class or on the `error_type` string, every consumer being an `except` or an `isinstance` on the base, with the agent CLI's hint and domain lookups report-first in any case.