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.

feat(errors): a closed registry for validation error types (#1138)

Louis Choquel113dcf9291bd
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 17baf84f0..1e1269c6a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,16 @@
# Changelog
+## [Unreleased]
+
+### Added
+
+- **The `error_type` values a validation verdict can carry are now an enumerable, closed registry**: a `.mthds` bundle that fails validation reports each fault under an `error_type`, and until now there was no way to ask the runtime which faults exist. The values were reachable only by reading raise sites, and the only curated list of them lived outside this repo, in a hand-maintained conformance suite that could silently fall behind. `pipelex/validation_error_types.py` now holds the vocabulary in full and enumerates it as `VALIDATION_ERROR_TYPES`, so a consumer building coverage over the language surface — a test corpus, a client mapping faults onto its own UI — reads the registry instead of collecting strings from whichever diagnostics it happened to have seen. It is a **union of the enums the runtime already raises**, never a second list beside them: the two stage vocabularies plus a new `ValidationResidualErrorType` naming the one residual channel that had no enum of its own and rode an inline string. A member added to any of them is in the registry the moment it is declared. `ValidationErrorItem.error_type` is typed against their union, which is what makes the registry closed rather than merely documented — an unregistered string can no longer be constructed or parsed onto an item — and which publishes the vocabulary into the OpenAPI schema served for `/validate`, where the field was previously an open `string`. **No wire value changed**, including the dry-run residual's `DryRunError`: it keeps the exception-class spelling it has always had, because normalizing it would break every consumer that pins the string and would buy nothing an enumeration does not already give. Membership means a value is reachable on the wire, not that it is worth exercising — the advisory-only warning type and the two `unknown_*` fallbacks are in the registry and a coverage consumer excludes them on its own side, with a reason, rather than pruning the runtime's truth.
+
+### Changed
+
+- **Two test fixtures were naming faults that do not exist**, and typing `error_type` against the registry is what surfaced them: one item claimed `MISSING_CONCEPT` — a code no enum has ever defined — and others used member names (`INADEQUATE_OUTPUT_CONCEPT`) where the wire carries values (`inadequate_output_concept`). Every one of them was accepted silently while the field was an open string, so the tests asserted on renderings of a fault the runtime cannot produce. They now name registry members.
+- **The two stage error-type enums moved to `pipelex/validation_error_types.py`** from `pipelex/core/pipes/exceptions.py`, where the exceptions that raise them import them back. The vocabulary is a wire contract rather than pipe machinery, and it has to sit below `base_exceptions` for the wire item to be typed against it at all — the same low-level placement, for the same reason, as `pipelex/suggested_fix.py`.
+
## [v0.48.0] - 2026-08-20
### Added
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index 745d4f2c4..99c432eb8 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -91,6 +91,16 @@ Besides `category` and `message`, each item carries whatever identity fields its
`ValidationErrorItem` and the builder are the single source of truth across surfaces: `build_validation_error_items()` (`pipelex/pipeline/validation_errors.py`) is called by both `ValidateBundleError.to_error_report()` (the API path) and the agent CLI's `extract_validation_errors()` (the CLI JSON envelope), so the two structured shapes cannot drift. The item lives in `pipelex/base_exceptions.py` alongside `ErrorReport` — not next to the source error-data models — because `ErrorReport` references it as a typed field and the root exceptions module must not import the `pipelex.core` error modules.
+#### The `error_type` registry — the closed vocabulary of faults
+
+An item's `error_type` names the fault it reports, and that vocabulary is closed: `pipelex/validation_error_types.py` holds it in full, enumerated as `VALIDATION_ERROR_TYPES`. A consumer that needs to know which faults the language surface can report — a coverage gate, a test corpus, a client mapping errors onto its own UI — reads that registry instead of collecting strings from whichever diagnostics it happens to have seen.
+
+The registry is the union of the enums the runtime already raises, never a second list beside them: `PipeValidationErrorType` and `PipeFactoryErrorType` are the two stage vocabularies, and `ValidationResidualErrorType` names the one residual channel with no stage enum of its own. A member added to any of the three is in the registry the moment it is declared. `ValidationErrorItem.error_type` is typed against their union, so an unregistered string cannot be constructed or parsed onto an item — which is what makes the enumeration *closed* rather than merely documented, and what publishes the vocabulary into the OpenAPI schema `pipelex-api` serves for `/validate`.
+
+Two spellings live in that one vocabulary, deliberately. The stage enums are snake_case codes (`missing_input_variable`); the dry-run residual is `DryRunError`, the name of the exception that produced it, because that residual is raised as an error object rather than classified into a code. Normalizing it would be a wire break across every consumer that pins the string, and it would buy nothing — the enumeration is closed either way.
+
+Membership means a value is *reachable on the wire*, not that it is a useful thing to exercise. `optional_force_redundant` rides `warnings` and never an invalid verdict, and the two `unknown_*` fallbacks fire on states no author can ask for. A consumer building coverage over the registry excludes those on its own side with a stated reason, rather than pruning them from the runtime truth here — that is what the [MTHDS Test Corpus](../contribute/mthds-test-corpus.md) vocabulary generator will do when its `error.*` namespace arrives with this registry.
+
`validation_errors` is one of the fields kept under STRICT disclosure (it is in `_STRICT_KEPT_FIELDS`): the items describe the caller's *own* submitted bundle, not server internals, so redacting them would gut the hosted path's diagnostics.
```python
@@ -423,6 +433,7 @@ InferenceErrorCategory.TRANSIENT.is_retryable # True — only TRANSIENT
|------|---------|
| `pipelex/base_exceptions.py` | `PipelexError`, `ErrorReport`, `ErrorDomain`, `ValidationErrorItem`, `error_domain_to_http_status()` |
| `pipelex/pipeline/validation_errors.py` | `build_validation_error_items()` — shared CLI/API structured bundle-validation builder |
+| `pipelex/validation_error_types.py` | The closed `error_type` registry — `VALIDATION_ERROR_TYPES`, `PipeValidationErrorType`, `PipeFactoryErrorType`, `ValidationResidualErrorType` |
| `pipelex/cogt/exceptions.py` | `CogtError`, `InferenceErrorCategory` |
| `pipelex/cogt/inference/error_classification.py` | Extract — `ProviderErrorMetadata`, `SDKErrorEnvelope`, `UserAction`, `UserActionKind`, per-provider `extract_*_metadata` functions, pure discriminators |
| `pipelex/cogt/inference/error_classify.py` | Classify — `classify_inference_error()`, `ClassificationResult` |
diff --git a/pipelex/base_exceptions.py b/pipelex/base_exceptions.py
index 4d1458d52..d9013adfc 100644
--- a/pipelex/base_exceptions.py
+++ b/pipelex/base_exceptions.py
@@ -10,6 +10,7 @@ from pipelex.migration.plan import MigrationPlan
from pipelex.suggested_fix import SuggestedFix
from pipelex.tools.misc.string_utils import pascal_case_to_kebab, pascal_case_to_sentence
from pipelex.urls import URLs
+from pipelex.validation_error_types import ValidationErrorType
def iter_cause_chain(exc: BaseException) -> Iterator[BaseException]:
@@ -292,10 +293,14 @@ class ValidationErrorItem(BaseModel):
subset its :attr:`category` produces, and the unset fields drop out of the
``exclude_none`` wire projection.
- Built exclusively by ``pipelex.pipeline.validation_errors.build_validation_error_items``,
- which both the agent CLI (``extract_validation_errors``) and the API path
+ The error channel is built exclusively by
+ ``pipelex.pipeline.validation_errors.build_validation_error_items``, which both the agent
+ CLI (``extract_validation_errors``) and the API path
(``ValidateBundleError.to_error_report``) call — so the CLI's structured
- output and the API's 422 ``validation_errors`` can never drift.
+ output and the API's 422 ``validation_errors`` can never drift. The same
+ item type also carries the report's advisory ``warnings``, built by
+ ``pipelex.pipeline.optionality_warnings``: a warning is the same shape of
+ diagnostic, differing only in that it does not make the verdict invalid.
``source`` is the declaring file path (CLI) or the per-content source the API
threads onto the in-memory load path — it hands a consumer the owning file
@@ -309,7 +314,13 @@ class ValidationErrorItem(BaseModel):
category: ValidationErrorCategory = Field(strict=False)
message: str
- error_type: str | None = None
+ # Typed against the closed registry in ``pipelex.validation_error_types``, so the vocabulary a
+ # consumer can observe here IS that registry — an unregistered string cannot be constructed
+ # onto an item. ``None`` stays legal for the parse-level residual, which reports a message with
+ # no identified fault behind it. No ``strict=False`` here, unlike ``category`` above: pydantic
+ # refuses that constraint on a union field, and the model declares no strict config, so the
+ # union already validates leniently — a plain wire string resolves to its registry member.
+ error_type: ValidationErrorType | None = None
pipe_code: str | None = None
concept_code: str | None = None
domain_code: str | None = None
diff --git a/pipelex/core/exceptions.py b/pipelex/core/exceptions.py
index 02fc828c6..2743f8703 100644
--- a/pipelex/core/exceptions.py
+++ b/pipelex/core/exceptions.py
@@ -1,6 +1,6 @@
from pydantic import BaseModel, Field
-from pipelex.core.pipes.exceptions import PipeFactoryErrorType, PipeValidationErrorType
+from pipelex.validation_error_types import PipeFactoryErrorType, PipeValidationErrorType
class PipeFactoryErrorData(BaseModel):
diff --git a/pipelex/core/pipes/exceptions.py b/pipelex/core/pipes/exceptions.py
index 6ecb531d5..77121f70b 100644
--- a/pipelex/core/pipes/exceptions.py
+++ b/pipelex/core/pipes/exceptions.py
@@ -1,5 +1,3 @@
-from enum import StrEnum
-
from typing_extensions import override
from pipelex.base_exceptions import PipelexError
@@ -9,18 +7,7 @@ from pipelex.cogt.llm.llm_setting import LLMModelChoice
from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.cogt.models.model_reference import ModelReference
from pipelex.system.pipe_run_mode import PipeRunMode
-
-
-class PipeFactoryErrorType(StrEnum):
- """Types of pipe factory errors.
-
- These error types are raised during pipe creation from blueprints.
- """
-
- UNKNOWN_CONCEPT = "unknown_concept"
-
- # Generic fallback for unexpected factory errors
- UNKNOWN_FACTORY_ERROR = "unknown_factory_error"
+from pipelex.validation_error_types import PipeFactoryErrorType, PipeValidationErrorType
class PipeFactoryError(PipelexError):
@@ -111,224 +98,6 @@ class PipeOperatorModelChoiceError(PipelexError):
return self.desc()
-class PipeValidationErrorType(StrEnum):
- """Types of pipe validation errors.
-
- These error types are raised during pipe validation from Pipe/Concept classes.
- """
-
- MISSING_INPUT_VARIABLE = "missing_input_variable"
- EXTRANEOUS_INPUT_VARIABLE = "extraneous_input_variable"
- INPUT_STUFF_SPEC_MISMATCH = "input_stuff_spec_mismatch"
- INADEQUATE_OUTPUT_CONCEPT = "inadequate_output_concept"
- INADEQUATE_OUTPUT_MULTIPLICITY = "inadequate_output_multiplicity"
-
- CIRCULAR_DEPENDENCY_ERROR = "circular_dependency_error"
-
- LLM_OUTPUT_CANNOT_BE_IMAGE = "llm_output_cannot_be_image"
- INVALID_PIPE_CODE_SYNTAX = "invalid_pipe_code_syntax"
- UNKNOWN_PIPE_TYPE = "unknown_pipe_type"
- # A `[pipe.x]` section declared no `type` yet carries fields beyond the signature contract
- # (`description`, `inputs`, `output`). The author is describing an implementation without naming
- # its type — the counterpart to UNKNOWN_PIPE_TYPE (a declared-but-invalid type).
- MISSING_PIPE_TYPE = "missing_pipe_type"
- BATCH_ITEM_NAME_COLLISION = "batch_item_name_collision"
-
- # Presence-marker grammar misuse, detected at blueprint parse time: a presence marker
- # (`?` or `!`) combined with a multiplicity suffix, or `!` on an output (D1, D4 of the
- # optionals design).
- OPTIONAL_MARKER_INVALID = "optional_marker_invalid"
-
- # Static absence-taint violations (D6/D7/D11 of the optionals design): a maybe-absent slot
- # escaping through a non-optional controller boundary; a `continue`-reachable PipeCondition
- # without a `?` output; an unguarded template reference to a declared-optional input; a
- # required structure field fed by a maybe-absent PipeParallel branch.
- OPTIONAL_NOT_HANDLED = "optional_not_handled"
- OPTIONAL_OUTPUT_REQUIRED = "optional_output_required"
- OPTIONAL_INPUT_UNGUARDED = "optional_input_unguarded"
- OPTIONAL_BRANCH_REQUIRED_FIELD = "optional_branch_required_field"
-
- # Advisory-only (rides the validation report's `warnings` array, never raised as an error):
- # a `!` (force) input whose slot is guaranteed present in every analyzed flow — the
- # assertion can never fire.
- OPTIONAL_FORCE_REDUNDANT = "optional_force_redundant"
-
- # Blueprint parse-time concept error: a bundle declares a concept whose code collides with a
- # native Pipelex concept (`Text`, `Number`, …). Structurally suppressible — set only at the
- # single `validate_concept_keys` raise site — so the fix planner keys on it safely.
- NATIVE_CONCEPT_REDECLARATION = "native_concept_redeclaration"
-
- # Wiring / reference-resolution failures, detected when validating a pipe's contract against the
- # merged library (a referenced concept or dependency pipe does not resolve).
- UNRESOLVED_CONCEPT = "unresolved_concept"
- UNRESOLVED_PIPE_DEPENDENCY = "unresolved_pipe_dependency"
-
- # Generic fallback for unexpected validation errors
- UNKNOWN_VALIDATION_ERROR = "unknown_validation_error"
-
- @property
- def is_controller_input_drift(self) -> bool:
- """True for the input-drift trio the fix planner can act on when enriched."""
- match self:
- case (
- PipeValidationErrorType.MISSING_INPUT_VARIABLE
- | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE
- | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH
- ):
- return True
- case (
- PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT
- | PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY
- | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR
- | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE
- | PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX
- | PipeValidationErrorType.UNKNOWN_PIPE_TYPE
- | PipeValidationErrorType.MISSING_PIPE_TYPE
- | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION
- | PipeValidationErrorType.OPTIONAL_MARKER_INVALID
- | PipeValidationErrorType.OPTIONAL_NOT_HANDLED
- | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
- | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
- | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
- | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
- | PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
- | PipeValidationErrorType.UNRESOLVED_CONCEPT
- | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
- | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
- ):
- return False
-
- @property
- def is_inadequate_output(self) -> bool:
- """True for the output-mismatch pair the fix planner can act on when enriched."""
- match self:
- case PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT | PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY:
- return True
- case (
- PipeValidationErrorType.MISSING_INPUT_VARIABLE
- | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE
- | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH
- | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR
- | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE
- | PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX
- | PipeValidationErrorType.UNKNOWN_PIPE_TYPE
- | PipeValidationErrorType.MISSING_PIPE_TYPE
- | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION
- | PipeValidationErrorType.OPTIONAL_MARKER_INVALID
- | PipeValidationErrorType.OPTIONAL_NOT_HANDLED
- | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
- | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
- | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
- | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
- | PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
- | PipeValidationErrorType.UNRESOLVED_CONCEPT
- | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
- | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
- ):
- return False
-
- @property
- def is_inadequate_output_multiplicity(self) -> bool:
- """True only for the multiplicity-mismatch case.
-
- The required/provided concept-ref suffix appended by the error categorizer is suppressed
- for this case: a multiplicity mismatch has the same concept on both sides by definition
- (the concept-compatibility check passed just before it fired), so the suffix would print
- two identical refs and its list-repr brackets would masquerade as `[]` multiplicity syntax.
- """
- match self:
- case PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY:
- return True
- case (
- PipeValidationErrorType.MISSING_INPUT_VARIABLE
- | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE
- | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH
- | PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT
- | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR
- | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE
- | PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX
- | PipeValidationErrorType.UNKNOWN_PIPE_TYPE
- | PipeValidationErrorType.MISSING_PIPE_TYPE
- | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION
- | PipeValidationErrorType.OPTIONAL_MARKER_INVALID
- | PipeValidationErrorType.OPTIONAL_NOT_HANDLED
- | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
- | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
- | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
- | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
- | PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
- | PipeValidationErrorType.UNRESOLVED_CONCEPT
- | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
- | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
- ):
- return False
-
- @property
- def is_native_concept_redeclaration(self) -> bool:
- """True for the blueprint-channel native-concept redeclaration the fix planner strips."""
- match self:
- case PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION:
- return True
- case (
- PipeValidationErrorType.MISSING_INPUT_VARIABLE
- | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE
- | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH
- | PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT
- | PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY
- | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR
- | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE
- | PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX
- | PipeValidationErrorType.UNKNOWN_PIPE_TYPE
- | PipeValidationErrorType.MISSING_PIPE_TYPE
- | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION
- | PipeValidationErrorType.OPTIONAL_MARKER_INVALID
- | PipeValidationErrorType.OPTIONAL_NOT_HANDLED
- | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
- | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
- | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
- | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
- | PipeValidationErrorType.UNRESOLVED_CONCEPT
- | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
- | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
- ):
- return False
-
- @property
- def is_invalid_pipe_code_syntax(self) -> bool:
- """True for the invalid-pipe-code-syntax error the fix planner strips when it is enriched.
-
- Gates entry to ``strip-namespace``; the planner still requires the ``stripped_pipe_code``
- enrichment, so un-strippable syntax errors (malformed codes, cross-package dotted refs)
- fall through as ``None`` even though they share this ``error_type``.
- """
- match self:
- case PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX:
- return True
- case (
- PipeValidationErrorType.MISSING_INPUT_VARIABLE
- | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE
- | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH
- | PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT
- | PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY
- | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR
- | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE
- | PipeValidationErrorType.UNKNOWN_PIPE_TYPE
- | PipeValidationErrorType.MISSING_PIPE_TYPE
- | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION
- | PipeValidationErrorType.OPTIONAL_MARKER_INVALID
- | PipeValidationErrorType.OPTIONAL_NOT_HANDLED
- | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
- | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
- | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
- | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
- | PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
- | PipeValidationErrorType.UNRESOLVED_CONCEPT
- | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
- | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
- ):
- return False
-
-
class PipeValidationError(ValueError):
def __init__(
self,
diff --git a/pipelex/libraries/concept_reference_validation.py b/pipelex/libraries/concept_reference_validation.py
index e6daf5007..4c91793f0 100644
--- a/pipelex/libraries/concept_reference_validation.py
+++ b/pipelex/libraries/concept_reference_validation.py
@@ -1,10 +1,10 @@
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.exceptions import PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.core.qualified_ref import QualifiedRef
from pipelex.libraries.concept.exceptions import ConceptLibraryError
from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipelexBundleBlueprint
+from pipelex.validation_error_types import PipeValidationErrorType
def _split_concept_ref_context(context: str) -> tuple[str | None, str | None, str]:
diff --git a/pipelex/libraries/library.py b/pipelex/libraries/library.py
index 4c0a7d530..6b109429f 100644
--- a/pipelex/libraries/library.py
+++ b/pipelex/libraries/library.py
@@ -8,7 +8,6 @@ from pydantic import BaseModel, Field, PrivateAttr
from pipelex import log
from pipelex.base_exceptions import PipelexUnexpectedError
from pipelex.core.exceptions import PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.core.qualified_ref import QualifiedRef, QualifiedRefError
from pipelex.libraries.concept.concept_library import ConceptLibrary
from pipelex.libraries.concept.exceptions import ConceptLibraryError
@@ -18,6 +17,7 @@ from pipelex.libraries.pipe.exceptions import PipeLibraryError, PipeNotFoundErro
from pipelex.libraries.pipe.pipe_library import PipeLibrary
from pipelex.pipe_controllers.pipe_controller import PipeController
from pipelex.tools.typing.pydantic_utils import empty_list_factory_of
+from pipelex.validation_error_types import PipeValidationErrorType
if TYPE_CHECKING:
from pipelex.core.concepts.concept import Concept
diff --git a/pipelex/mthds_parsing/handle_pipe_errors.py b/pipelex/mthds_parsing/handle_pipe_errors.py
index 3af269077..79181d3ae 100644
--- a/pipelex/mthds_parsing/handle_pipe_errors.py
+++ b/pipelex/mthds_parsing/handle_pipe_errors.py
@@ -5,7 +5,8 @@ from pydantic import ValidationError
from pydantic_core import ErrorDetails
from pipelex.core.exceptions import PipeFactoryErrorData, PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeFactoryError, PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeFactoryError, PipeValidationError
+from pipelex.validation_error_types import PipeValidationErrorType
class ModelScope(StrEnum):
diff --git a/pipelex/mthds_parsing/pipe_sorter.py b/pipelex/mthds_parsing/pipe_sorter.py
index 2f9b1a9f8..6717abdce 100644
--- a/pipelex/mthds_parsing/pipe_sorter.py
+++ b/pipelex/mthds_parsing/pipe_sorter.py
@@ -1,7 +1,8 @@
"""Topological sorting utilities for pipe dependencies."""
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipeBlueprintUnion
+from pipelex.validation_error_types import PipeValidationErrorType
def sort_pipes_by_dependencies(
diff --git a/pipelex/mthds_parsing/validation_error_categorizer.py b/pipelex/mthds_parsing/validation_error_categorizer.py
index 826a836ec..56821488a 100644
--- a/pipelex/mthds_parsing/validation_error_categorizer.py
+++ b/pipelex/mthds_parsing/validation_error_categorizer.py
@@ -5,13 +5,13 @@ from pydantic_core import ErrorDetails
from pipelex import log
from pipelex.core.exceptions import PipelexBundleBlueprintValidationErrorData
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.mthds_parsing.exceptions import (
InvalidPipeCodeSyntaxError,
NativeConceptRedeclarationError,
)
from pipelex.mthds_parsing.handle_pipe_errors import extract_wrapped_pipe_validation_error
from pipelex.mthds_parsing.helpers import ValidationErrorScope, get_error_scope
+from pipelex.validation_error_types import PipeValidationErrorType
PIPELEX_BUNDLE_BLUEPRINT_DOMAIN_FIELD = "domain"
PIPELEX_BUNDLE_BLUEPRINT_SOURCE_FIELD = "source"
diff --git a/pipelex/pipe_controllers/batch/pipe_batch_blueprint.py b/pipelex/pipe_controllers/batch/pipe_batch_blueprint.py
index c63162f6d..ffa9344de 100644
--- a/pipelex/pipe_controllers/batch/pipe_batch_blueprint.py
+++ b/pipelex/pipe_controllers/batch/pipe_batch_blueprint.py
@@ -2,8 +2,9 @@ from typing import Literal
from typing_extensions import override
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.pipe_machinery.pipe_blueprint import PipeBlueprint
+from pipelex.validation_error_types import PipeValidationErrorType
class PipeBatchBlueprint(PipeBlueprint):
diff --git a/pipelex/pipe_controllers/condition/pipe_condition.py b/pipelex/pipe_controllers/condition/pipe_condition.py
index 001e5dfb9..19dbfe519 100644
--- a/pipelex/pipe_controllers/condition/pipe_condition.py
+++ b/pipelex/pipe_controllers/condition/pipe_condition.py
@@ -7,7 +7,7 @@ from pipelex.cogt.templating.template_rendering import render_template
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.absence import AbsenceKind, AbsenceRecord
from pipelex.core.memory.working_memory import MAIN_STUFF_NAME, WorkingMemory
-from pipelex.core.pipes.exceptions import PipeRunError, PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeRunError, PipeValidationError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.inputs.input_stuff_specs_factory import InputStuffSpecsFactory
from pipelex.core.pipes.pipe_output import PipeOutput
@@ -22,6 +22,7 @@ from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
+from pipelex.validation_error_types import PipeValidationErrorType
if TYPE_CHECKING:
from pipelex.libraries.library_crate import LibraryCrate
diff --git a/pipelex/pipe_controllers/parallel/pipe_parallel.py b/pipelex/pipe_controllers/parallel/pipe_parallel.py
index cfb9274ba..1292c0722 100644
--- a/pipelex/pipe_controllers/parallel/pipe_parallel.py
+++ b/pipelex/pipe_controllers/parallel/pipe_parallel.py
@@ -11,7 +11,7 @@ from pipelex.core.concepts.exceptions import ConceptValueError
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.absence import AbsenceRecord
from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.core.pipes.exceptions import PipeRunError, PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeRunError, PipeValidationError
from pipelex.core.pipes.inputs.exceptions import InputStuffSpecNotFoundError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.inputs.input_stuff_specs_factory import InputStuffSpecsFactory
@@ -37,6 +37,7 @@ from pipelex.pipe_machinery.pipe_abstract import CompanionSlot
from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
+from pipelex.validation_error_types import PipeValidationErrorType
if TYPE_CHECKING:
from collections.abc import Coroutine
diff --git a/pipelex/pipe_controllers/sequence/pipe_sequence.py b/pipelex/pipe_controllers/sequence/pipe_sequence.py
index c337e0e75..0cf76482e 100644
--- a/pipelex/pipe_controllers/sequence/pipe_sequence.py
+++ b/pipelex/pipe_controllers/sequence/pipe_sequence.py
@@ -4,7 +4,7 @@ from pydantic import field_validator
from typing_extensions import override
from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.pipes.inputs.exceptions import InputStuffSpecNotFoundError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.inputs.input_stuff_specs_factory import InputStuffSpecsFactory
@@ -28,6 +28,7 @@ from pipelex.pipe_controllers.sub_pipe import SubPipe
from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
+from pipelex.validation_error_types import PipeValidationErrorType
if TYPE_CHECKING:
from pipelex.libraries.library_crate import LibraryCrate
diff --git a/pipelex/pipe_controllers/sub_pipe_blueprint.py b/pipelex/pipe_controllers/sub_pipe_blueprint.py
index 25ae53be5..61014283f 100644
--- a/pipelex/pipe_controllers/sub_pipe_blueprint.py
+++ b/pipelex/pipe_controllers/sub_pipe_blueprint.py
@@ -2,8 +2,9 @@ from typing import Self
from pydantic import BaseModel, ConfigDict, model_validator
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.tools.typing.validation_utils import has_more_than_one_among_attributes_from_list
+from pipelex.validation_error_types import PipeValidationErrorType
class SubPipeBlueprint(BaseModel):
diff --git a/pipelex/pipe_machinery/pipe_abstract.py b/pipelex/pipe_machinery/pipe_abstract.py
index 4daa9d796..770ee9161 100644
--- a/pipelex/pipe_machinery/pipe_abstract.py
+++ b/pipelex/pipe_machinery/pipe_abstract.py
@@ -13,7 +13,7 @@ from pipelex.core.concepts.concept import Concept
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.absence import AbsenceKind, AbsenceRecord
from pipelex.core.memory.working_memory import MAIN_STUFF_NAME, WorkingMemory
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.pipes.inputs.exceptions import OptionalValueAbsentError, PipeRunInputsError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs, NamedStuffSpec
from pipelex.core.pipes.pipe_output import PipeOutput
@@ -43,6 +43,7 @@ from pipelex.system.telemetry.otel_factory import OtelFactory
from pipelex.system.telemetry.telemetry_manager_abstract import TelemetryManagerAbstract
from pipelex.tools.misc.package_utils import get_package_version
from pipelex.tools.misc.string_utils import is_snake_case
+from pipelex.validation_error_types import PipeValidationErrorType
if TYPE_CHECKING:
from pipelex.system.trace_context import TraceContext
diff --git a/pipelex/pipe_machinery/pipe_blueprint.py b/pipelex/pipe_machinery/pipe_blueprint.py
index 0c402587a..ebdf534e3 100644
--- a/pipelex/pipe_machinery/pipe_blueprint.py
+++ b/pipelex/pipe_machinery/pipe_blueprint.py
@@ -7,7 +7,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
from pipelex.core.concepts.exceptions import ConceptStringError
from pipelex.core.concepts.validation import validate_concept_ref_or_code
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.pipes.variable_multiplicity import (
MULTIPLICITY_PATTERN,
PipeVariableMultiplicityError,
@@ -15,6 +15,7 @@ from pipelex.core.pipes.variable_multiplicity import (
parse_concept_with_multiplicity,
)
from pipelex.pipe_machinery.validation import validate_input_name
+from pipelex.validation_error_types import PipeValidationErrorType
# A signature is NOT an executable pipe kind: it is deliberately absent from `PipeType` and
# `PipeCategory`. This is the one extra `type` tag the parse-time allowlists admit beyond the
diff --git a/pipelex/pipe_machinery/pipe_factory.py b/pipelex/pipe_machinery/pipe_factory.py
index 031e3b707..33e4264c1 100644
--- a/pipelex/pipe_machinery/pipe_factory.py
+++ b/pipelex/pipe_machinery/pipe_factory.py
@@ -5,7 +5,7 @@ from typing_extensions import runtime_checkable
from pipelex.core.concepts.helpers import strip_markers_from_concept_ref_or_code
from pipelex.core.concepts.native.concept_native import NativeConceptCode
-from pipelex.core.pipes.exceptions import PipeFactoryError, PipeFactoryErrorType
+from pipelex.core.pipes.exceptions import PipeFactoryError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.inputs.input_stuff_specs_factory import InputStuffSpecsFactory
from pipelex.core.pipes.stuff_spec.exceptions import StuffSpecFactoryError
@@ -14,6 +14,7 @@ from pipelex.core.pipes.stuff_spec.stuff_spec_factory import StuffSpecFactory
from pipelex.interpreter_hub import get_concept_library
from pipelex.pipe_machinery.pipe_blueprint import PipeBlueprint, PipeCategory, PipeType
from pipelex.runtime_hub import get_class_registry
+from pipelex.validation_error_types import PipeFactoryErrorType
if TYPE_CHECKING:
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
diff --git a/pipelex/pipe_machinery/template_guard_lint.py b/pipelex/pipe_machinery/template_guard_lint.py
index 77ee36a3c..4647ff70d 100644
--- a/pipelex/pipe_machinery/template_guard_lint.py
+++ b/pipelex/pipe_machinery/template_guard_lint.py
@@ -5,11 +5,12 @@ validation fails with `OPTIONAL_INPUT_UNGUARDED` and the precise fix.
"""
from pipelex.cogt.templating.template_preprocessor import rewrite_template_sigils
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError
from pipelex.tools.jinja2.jinja2_optional_guards import detect_unguarded_optional_references
from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.validation_error_types import PipeValidationErrorType
def lint_optional_input_guards(
diff --git a/pipelex/pipe_operators/compose/pipe_compose.py b/pipelex/pipe_operators/compose/pipe_compose.py
index 2521f4005..bd614af41 100644
--- a/pipelex/pipe_operators/compose/pipe_compose.py
+++ b/pipelex/pipe_operators/compose/pipe_compose.py
@@ -9,7 +9,7 @@ from pipelex.cogt.templating.template_preprocessor import rewrite_template_sigil
from pipelex.config import get_config
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.inputs.input_stuff_specs_factory import InputStuffSpecsFactory
from pipelex.core.pipes.pipe_output import PipeOutput
@@ -31,6 +31,7 @@ from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_require
from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
from pipelex.tools.templating.templating_style import TemplatingStyle
+from pipelex.validation_error_types import PipeValidationErrorType
class PipeComposeOutput(PipeOutput):
diff --git a/pipelex/pipe_operators/extract/pipe_extract.py b/pipelex/pipe_operators/extract/pipe_extract.py
index 7333d35c6..8cd6ea825 100644
--- a/pipelex/pipe_operators/extract/pipe_extract.py
+++ b/pipelex/pipe_operators/extract/pipe_extract.py
@@ -9,7 +9,7 @@ from pipelex.cogt.extract.extract_setting import ExtractModelChoice
from pipelex.cogt.models.model_deck_check import check_extract_choice_with_deck
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.interpreter_hub import get_concept_library, get_native_concept
@@ -17,6 +17,7 @@ from pipelex.kernel.extract_ops import build_extract_job_params, resolve_extract
from pipelex.pipe_operators.pipe_operator import PipeOperator
from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.system.job_metadata import JobMetadata
+from pipelex.validation_error_types import PipeValidationErrorType
class PipeExtractOutput(PipeOutput):
diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen.py b/pipelex/pipe_operators/img_gen/pipe_img_gen.py
index d5df044c0..ad0fbff16 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen.py
@@ -12,7 +12,7 @@ from pipelex.cogt.models.model_deck_check import check_img_gen_choice_with_deck
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.exceptions import WorkingMemoryStuffNotFoundError
from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity
@@ -31,6 +31,7 @@ from pipelex.pipe_run.pipe_run_params import PipeRunParams, output_multiplicity_
from pipelex.runtime_hub import get_class_registry, get_model_deck
from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.misc.image_utils import ImageFormat
+from pipelex.validation_error_types import PipeValidationErrorType
class PipeImgGenOutput(PipeOutput):
diff --git a/pipelex/pipe_operators/llm/pipe_llm.py b/pipelex/pipe_operators/llm/pipe_llm.py
index 64eb41652..b539fc6a6 100644
--- a/pipelex/pipe_operators/llm/pipe_llm.py
+++ b/pipelex/pipe_operators/llm/pipe_llm.py
@@ -12,7 +12,7 @@ from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.domains.domain import SpecialDomain
from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.core.pipes.exceptions import PipeRunError, PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeRunError, PipeValidationError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.inputs.input_stuff_specs_factory import InputStuffSpecsFactory
from pipelex.core.pipes.pipe_output import PipeOutput
@@ -41,6 +41,7 @@ from pipelex.system.job_metadata import JobMetadata
from pipelex.system.pipe_run_param_key import PipeRunParamKey
from pipelex.tools.templating.templating_style import TemplatingStyle
from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error
+from pipelex.validation_error_types import PipeValidationErrorType
if TYPE_CHECKING:
from pipelex.cogt.llm.llm_prompt import LLMPrompt
diff --git a/pipelex/pipe_operators/structure/pipe_structure.py b/pipelex/pipe_operators/structure/pipe_structure.py
index 5e4bba0f6..ae56b6813 100644
--- a/pipelex/pipe_operators/structure/pipe_structure.py
+++ b/pipelex/pipe_operators/structure/pipe_structure.py
@@ -11,7 +11,7 @@ from pipelex.cogt.templating.template_rendering import render_template
from pipelex.config import get_config
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.core.pipes.exceptions import PipeRunError, PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeRunError, PipeValidationError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.inputs.input_stuff_specs_factory import InputStuffSpecsFactory
from pipelex.core.pipes.pipe_output import PipeOutput
@@ -26,6 +26,7 @@ from pipelex.pipe_run.pipe_run_params import PipeRunParams, output_multiplicity_
from pipelex.runtime_hub import get_class_registry
from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.validation_error_types import PipeValidationErrorType
class PipeStructureOutput(PipeOutput):
diff --git a/pipelex/pipeline/optionality_warnings.py b/pipelex/pipeline/optionality_warnings.py
index e75d19569..7d15e8fb1 100644
--- a/pipelex/pipeline/optionality_warnings.py
+++ b/pipelex/pipeline/optionality_warnings.py
@@ -21,8 +21,8 @@ from collections.abc import Sequence
from typing import TYPE_CHECKING
from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.pipeline.controller_taint import ControllerTaintAnalysis
+from pipelex.validation_error_types import PipeValidationErrorType
if TYPE_CHECKING:
from pipelex.pipe_controllers.absence_taint import ForceConsumptionInfo
diff --git a/pipelex/pipeline/validation_errors.py b/pipelex/pipeline/validation_errors.py
index 87c1ef513..c5939e1d1 100644
--- a/pipelex/pipeline/validation_errors.py
+++ b/pipelex/pipeline/validation_errors.py
@@ -18,6 +18,7 @@ is no import cycle.
from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
from pipelex.core.exceptions import PipeFactoryErrorData, PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
from pipelex.pipeline.fixes.planner import plan_fix_for_blueprint_validation_error, plan_fix_for_pipe_validation_error
+from pipelex.validation_error_types import ValidationResidualErrorType
def build_validation_error_items(
@@ -131,7 +132,7 @@ def build_validation_error_items(
items.append(
ValidationErrorItem(
category=ValidationErrorCategory.DRY_RUN,
- error_type="DryRunError",
+ error_type=ValidationResidualErrorType.DRY_RUN_ERROR,
message=dry_run_error_message,
)
)
diff --git a/pipelex/validation_error_types.py b/pipelex/validation_error_types.py
new file mode 100644
index 000000000..ec32fb342
--- /dev/null
+++ b/pipelex/validation_error_types.py
@@ -0,0 +1,315 @@
+"""The closed registry of ``error_type`` values a bundle-validation diagnostic can carry.
+
+Every ``ValidationErrorItem`` — the per-error wire item behind the agent CLI's
+``validation_errors[]`` array and the API's ``/validate`` verdict — names the fault it reports
+in an ``error_type`` field. This module is where that vocabulary is defined, in full, and
+:data:`VALIDATION_ERROR_TYPES` is the enumeration of it: a consumer that wants to know which
+faults the language surface can report reads this registry rather than collecting strings from
+whatever diagnostics it happens to have seen.
+
+The registry is a **union of the enums the runtime already raises**, never a second list beside
+them. ``PipeValidationErrorType`` and ``PipeFactoryErrorType`` are the two vocabularies the
+validation stages produce, and :class:`ValidationResidualErrorType` names the one residual
+channel that has no stage enum of its own. Deriving the registry from them is what stops it
+from drifting: a member added to any of the three is in the registry the moment it is declared,
+with nothing here to remember to update.
+
+**Two spellings live in one vocabulary, deliberately.** The stage enums are snake_case codes
+(``missing_input_variable``), while the dry-run residual is ``DryRunError`` — the name of the
+exception that produced it, because that residual is raised as an error object rather than
+classified into a code. Normalizing the residual would be a wire break across every consumer
+that pins it, and it buys nothing: a reader consuming this registry gets the closed set either
+way, and the corpus tag vocabulary already normalizes registry codes to snake_case on the way
+in (``DryRunError`` → ``error.dry_run_error``, exactly as ``YesNo`` → ``native.yes_no``).
+
+This module is deliberately low-level — stdlib only, and no ``pipelex`` imports at all — for the
+same reason ``pipelex.suggested_fix`` is: ``pipelex.base_exceptions``, where
+``ValidationErrorItem`` lives, types its ``error_type`` field against :data:`ValidationErrorType`
+and must be able to import it without an import cycle. The stage enums live here rather than
+beside the exceptions that raise them precisely so that typing is possible; the exception classes
+in ``pipelex.core.pipes.exceptions`` import them back.
+"""
+
+from enum import StrEnum
+from typing import TypeAlias
+
+
+class PipeValidationErrorType(StrEnum):
+ """Types of pipe validation errors.
+
+ These error types are raised during pipe validation from Pipe/Concept classes.
+ """
+
+ MISSING_INPUT_VARIABLE = "missing_input_variable"
+ EXTRANEOUS_INPUT_VARIABLE = "extraneous_input_variable"
+ INPUT_STUFF_SPEC_MISMATCH = "input_stuff_spec_mismatch"
+ INADEQUATE_OUTPUT_CONCEPT = "inadequate_output_concept"
+ INADEQUATE_OUTPUT_MULTIPLICITY = "inadequate_output_multiplicity"
+
+ CIRCULAR_DEPENDENCY_ERROR = "circular_dependency_error"
+
+ LLM_OUTPUT_CANNOT_BE_IMAGE = "llm_output_cannot_be_image"
+ INVALID_PIPE_CODE_SYNTAX = "invalid_pipe_code_syntax"
+ UNKNOWN_PIPE_TYPE = "unknown_pipe_type"
+ # A `[pipe.x]` section declared no `type` yet carries fields beyond the signature contract
+ # (`description`, `inputs`, `output`). The author is describing an implementation without naming
+ # its type — the counterpart to UNKNOWN_PIPE_TYPE (a declared-but-invalid type).
+ MISSING_PIPE_TYPE = "missing_pipe_type"
+ BATCH_ITEM_NAME_COLLISION = "batch_item_name_collision"
+
+ # Presence-marker grammar misuse, detected at blueprint parse time: a presence marker
+ # (`?` or `!`) combined with a multiplicity suffix, or `!` on an output (D1, D4 of the
+ # optionals design).
+ OPTIONAL_MARKER_INVALID = "optional_marker_invalid"
+
+ # Static absence-taint violations (D6/D7/D11 of the optionals design): a maybe-absent slot
+ # escaping through a non-optional controller boundary; a `continue`-reachable PipeCondition
+ # without a `?` output; an unguarded template reference to a declared-optional input; a
+ # required structure field fed by a maybe-absent PipeParallel branch.
+ OPTIONAL_NOT_HANDLED = "optional_not_handled"
+ OPTIONAL_OUTPUT_REQUIRED = "optional_output_required"
+ OPTIONAL_INPUT_UNGUARDED = "optional_input_unguarded"
+ OPTIONAL_BRANCH_REQUIRED_FIELD = "optional_branch_required_field"
+
+ # Advisory-only (rides the validation report's `warnings` array, never raised as an error):
+ # a `!` (force) input whose slot is guaranteed present in every analyzed flow — the
+ # assertion can never fire.
+ OPTIONAL_FORCE_REDUNDANT = "optional_force_redundant"
+
+ # Blueprint parse-time concept error: a bundle declares a concept whose code collides with a
+ # native Pipelex concept (`Text`, `Number`, …). Structurally suppressible — set only at the
+ # single `validate_concept_keys` raise site — so the fix planner keys on it safely.
+ NATIVE_CONCEPT_REDECLARATION = "native_concept_redeclaration"
+
+ # Wiring / reference-resolution failures, detected when validating a pipe's contract against the
+ # merged library (a referenced concept or dependency pipe does not resolve).
+ UNRESOLVED_CONCEPT = "unresolved_concept"
+ UNRESOLVED_PIPE_DEPENDENCY = "unresolved_pipe_dependency"
+
+ # Generic fallback for unexpected validation errors
+ UNKNOWN_VALIDATION_ERROR = "unknown_validation_error"
+
+ @property
+ def is_controller_input_drift(self) -> bool:
+ """True for the input-drift trio the fix planner can act on when enriched."""
+ match self:
+ case (
+ PipeValidationErrorType.MISSING_INPUT_VARIABLE
+ | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE
+ | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH
+ ):
+ return True
+ case (
+ PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT
+ | PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY
+ | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR
+ | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE
+ | PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX
+ | PipeValidationErrorType.UNKNOWN_PIPE_TYPE
+ | PipeValidationErrorType.MISSING_PIPE_TYPE
+ | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION
+ | PipeValidationErrorType.OPTIONAL_MARKER_INVALID
+ | PipeValidationErrorType.OPTIONAL_NOT_HANDLED
+ | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
+ | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
+ | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
+ | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
+ | PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
+ | PipeValidationErrorType.UNRESOLVED_CONCEPT
+ | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
+ | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
+ ):
+ return False
+
+ @property
+ def is_inadequate_output(self) -> bool:
+ """True for the output-mismatch pair the fix planner can act on when enriched."""
+ match self:
+ case PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT | PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY:
+ return True
+ case (
+ PipeValidationErrorType.MISSING_INPUT_VARIABLE
+ | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE
+ | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH
+ | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR
+ | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE
+ | PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX
+ | PipeValidationErrorType.UNKNOWN_PIPE_TYPE
+ | PipeValidationErrorType.MISSING_PIPE_TYPE
+ | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION
+ | PipeValidationErrorType.OPTIONAL_MARKER_INVALID
+ | PipeValidationErrorType.OPTIONAL_NOT_HANDLED
+ | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
+ | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
+ | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
+ | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
+ | PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
+ | PipeValidationErrorType.UNRESOLVED_CONCEPT
+ | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
+ | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
+ ):
+ return False
+
+ @property
+ def is_inadequate_output_multiplicity(self) -> bool:
+ """True only for the multiplicity-mismatch case.
+
+ The required/provided concept-ref suffix appended by the error categorizer is suppressed
+ for this case: a multiplicity mismatch has the same concept on both sides by definition
+ (the concept-compatibility check passed just before it fired), so the suffix would print
+ two identical refs and its list-repr brackets would masquerade as `[]` multiplicity syntax.
+ """
+ match self:
+ case PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY:
+ return True
+ case (
+ PipeValidationErrorType.MISSING_INPUT_VARIABLE
+ | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE
+ | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH
+ | PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT
+ | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR
+ | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE
+ | PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX
+ | PipeValidationErrorType.UNKNOWN_PIPE_TYPE
+ | PipeValidationErrorType.MISSING_PIPE_TYPE
+ | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION
+ | PipeValidationErrorType.OPTIONAL_MARKER_INVALID
+ | PipeValidationErrorType.OPTIONAL_NOT_HANDLED
+ | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
+ | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
+ | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
+ | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
+ | PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
+ | PipeValidationErrorType.UNRESOLVED_CONCEPT
+ | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
+ | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
+ ):
+ return False
+
+ @property
+ def is_native_concept_redeclaration(self) -> bool:
+ """True for the blueprint-channel native-concept redeclaration the fix planner strips."""
+ match self:
+ case PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION:
+ return True
+ case (
+ PipeValidationErrorType.MISSING_INPUT_VARIABLE
+ | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE
+ | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH
+ | PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT
+ | PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY
+ | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR
+ | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE
+ | PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX
+ | PipeValidationErrorType.UNKNOWN_PIPE_TYPE
+ | PipeValidationErrorType.MISSING_PIPE_TYPE
+ | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION
+ | PipeValidationErrorType.OPTIONAL_MARKER_INVALID
+ | PipeValidationErrorType.OPTIONAL_NOT_HANDLED
+ | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
+ | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
+ | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
+ | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
+ | PipeValidationErrorType.UNRESOLVED_CONCEPT
+ | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
+ | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
+ ):
+ return False
+
+ @property
+ def is_invalid_pipe_code_syntax(self) -> bool:
+ """True for the invalid-pipe-code-syntax error the fix planner strips when it is enriched.
+
+ Gates entry to ``strip-namespace``; the planner still requires the ``stripped_pipe_code``
+ enrichment, so un-strippable syntax errors (malformed codes, cross-package dotted refs)
+ fall through as ``None`` even though they share this ``error_type``.
+ """
+ match self:
+ case PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX:
+ return True
+ case (
+ PipeValidationErrorType.MISSING_INPUT_VARIABLE
+ | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE
+ | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH
+ | PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT
+ | PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY
+ | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR
+ | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE
+ | PipeValidationErrorType.UNKNOWN_PIPE_TYPE
+ | PipeValidationErrorType.MISSING_PIPE_TYPE
+ | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION
+ | PipeValidationErrorType.OPTIONAL_MARKER_INVALID
+ | PipeValidationErrorType.OPTIONAL_NOT_HANDLED
+ | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
+ | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
+ | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
+ | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
+ | PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
+ | PipeValidationErrorType.UNRESOLVED_CONCEPT
+ | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
+ | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
+ ):
+ return False
+
+
+class PipeFactoryErrorType(StrEnum):
+ """Types of pipe factory errors.
+
+ These error types are raised during pipe creation from blueprints.
+ """
+
+ UNKNOWN_CONCEPT = "unknown_concept"
+
+ # Generic fallback for unexpected factory errors
+ UNKNOWN_FACTORY_ERROR = "unknown_factory_error"
+
+
+class ValidationResidualErrorType(StrEnum):
+ """The ``error_type`` of a validation residual — a failure with no stage-level error data.
+
+ A residual is what the wire projection emits when a bundle failed but no categorized
+ validation stage produced structured data to report. There is exactly one residual that names
+ itself: a dry-run failure surfaces a single message from a raised ``DryRunError`` / ``PipeRunError``,
+ so the item is tagged with that exception's own class name.
+
+ The other residual — the parse-level one, for a bundle that could not be turned into a
+ blueprint at all (a TOML-syntax error, an empty blueprint, an elaborator failure) — carries no
+ ``error_type`` and therefore no member here. That is not an omission: it fires for several
+ distinct underlying errors, and inventing one code for all of them would tell a consumer it
+ knows which fault occurred when it does not. Its message is the authoritative diagnostic.
+ """
+
+ DRY_RUN_ERROR = "DryRunError"
+
+
+ValidationErrorType: TypeAlias = PipeValidationErrorType | PipeFactoryErrorType | ValidationResidualErrorType
+"""The type of a bundle-validation diagnostic's ``error_type``.
+
+``ValidationErrorItem.error_type`` is typed against this alias, which is what makes the registry
+*closed* rather than merely documented: a value outside these three enums cannot be constructed
+onto the wire, so the enumeration below and the values a consumer actually observes cannot
+disagree.
+"""
+
+VALIDATION_ERROR_TYPES: tuple[ValidationErrorType, ...] = (
+ *PipeValidationErrorType,
+ *PipeFactoryErrorType,
+ *ValidationResidualErrorType,
+)
+"""Every ``error_type`` a bundle-validation diagnostic can carry, in a deterministic order.
+
+Ordered by contributing enum, then by declaration order within it — so a generated artifact keyed
+on this registry (the MTHDS Test Corpus tag vocabulary is the first) is stable across runs and a
+new member shows up as one added line rather than a reshuffle.
+
+The three enums are value-disjoint, and that is a property worth stating rather than assuming:
+were two of them to share a wire value, ``error_type`` would stop identifying the fault and the
+alias above would resolve it to whichever enum pydantic tried first. It is gated by
+``tests/unit/pipelex/errors/test_validation_error_types.py``.
+
+Membership says a value is *reachable on the wire*, never that it is a useful coverage target.
+The advisory-only member rides the validation report's ``warnings`` array and never an invalid
+verdict; the two ``unknown_*`` fallbacks fire on states no author can ask for. A consumer that
+needs to exercise each fault — the corpus's ``error.*`` axis — excludes those in its own
+generator, with a stated reason per exclusion, rather than pruning them from the runtime truth here.
+"""
diff --git a/tests/integration/pipelex/pipeline/test_controller_inputs_enrichment.py b/tests/integration/pipelex/pipeline/test_controller_inputs_enrichment.py
index c9e6b8990..83efa9a9d 100644
--- a/tests/integration/pipelex/pipeline/test_controller_inputs_enrichment.py
+++ b/tests/integration/pipelex/pipeline/test_controller_inputs_enrichment.py
@@ -15,9 +15,9 @@ from collections.abc import Callable
import pytest
from pipelex.core.exceptions import PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.validation_error_types import PipeValidationErrorType
_MISSING_INPUT_MTHDS = """
domain = "inputsfix_missing"
diff --git a/tests/integration/pipelex/pipeline/test_native_concept_redecl_enrichment.py b/tests/integration/pipelex/pipeline/test_native_concept_redecl_enrichment.py
index d3ac38358..882c59e1a 100644
--- a/tests/integration/pipelex/pipeline/test_native_concept_redecl_enrichment.py
+++ b/tests/integration/pipelex/pipeline/test_native_concept_redecl_enrichment.py
@@ -14,9 +14,9 @@ from collections.abc import Callable
import pytest
from pipelex.core.exceptions import PipelexBundleBlueprintValidationErrorData
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.validation_error_types import PipeValidationErrorType
_REDECL_TABLE_MTHDS = """
domain = "nativefix_table"
diff --git a/tests/integration/pipelex/pipeline/test_sequence_output_enrichment.py b/tests/integration/pipelex/pipeline/test_sequence_output_enrichment.py
index 93f9027d9..037427ede 100644
--- a/tests/integration/pipelex/pipeline/test_sequence_output_enrichment.py
+++ b/tests/integration/pipelex/pipeline/test_sequence_output_enrichment.py
@@ -15,9 +15,9 @@ from collections.abc import Callable
import pytest
from pipelex.core.exceptions import PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.validation_error_types import PipeValidationErrorType
_WRONG_CONCEPT_MTHDS = """
domain = "seqfix_concept"
diff --git a/tests/integration/pipelex/pipeline/test_strip_namespace_enrichment.py b/tests/integration/pipelex/pipeline/test_strip_namespace_enrichment.py
index 91b45263e..82de7298b 100644
--- a/tests/integration/pipelex/pipeline/test_strip_namespace_enrichment.py
+++ b/tests/integration/pipelex/pipeline/test_strip_namespace_enrichment.py
@@ -15,9 +15,9 @@ from collections.abc import Callable
import pytest
from pipelex.core.exceptions import PipelexBundleBlueprintValidationErrorData
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.validation_error_types import PipeValidationErrorType
# A same-domain over-qualified DECLARATION key; main_pipe is a valid bare pipe, so the only error is
# the dotted declaration. The qualified step ref survives (it resolves) — not an error.
diff --git a/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py b/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py
index 53c675af6..1e2dfdd26 100644
--- a/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py
+++ b/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py
@@ -23,9 +23,10 @@ import pytest
from pytest_mock import MockerFixture
from pipelex.base_exceptions import PipelexUnexpectedError, ValidationErrorCategory, ValidationErrorItem
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validate_bundle import _backfill_pipe_error_source, validate_bundle # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]
+from pipelex.validation_error_types import PipeValidationErrorType
_VALID_MTHDS = """
domain = "testapp"
diff --git a/tests/integration/pipelex/pipeline/test_validate_bundle_structured_errors.py b/tests/integration/pipelex/pipeline/test_validate_bundle_structured_errors.py
index ecd713514..4a9e6b9d3 100644
--- a/tests/integration/pipelex/pipeline/test_validate_bundle_structured_errors.py
+++ b/tests/integration/pipelex/pipeline/test_validate_bundle_structured_errors.py
@@ -24,9 +24,9 @@ from collections.abc import Callable
import pytest
from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.validation_error_types import PipeValidationErrorType
_UNKNOWN_CONCEPT_MTHDS = """
domain = "structured_unknown_concept"
diff --git a/tests/integration/pipelex/pipes/optionals/test_condition_optional_output_validation.py b/tests/integration/pipelex/pipes/optionals/test_condition_optional_output_validation.py
index 56b8b8a07..30a89699a 100644
--- a/tests/integration/pipelex/pipes/optionals/test_condition_optional_output_validation.py
+++ b/tests/integration/pipelex/pipes/optionals/test_condition_optional_output_validation.py
@@ -13,7 +13,7 @@ import pytest
from pydantic import ValidationError
from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.stuffs.text_content import TextContent
from pipelex.interpreter_hub import get_pipe_library
from pipelex.mthds_parsing.handle_pipe_errors import extract_wrapped_pipe_validation_error
@@ -23,6 +23,7 @@ from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipe_operators.func.pipe_func import PipeFunc
from pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint
from pipelex.system.registries.func_registry import func_registry
+from pipelex.validation_error_types import PipeValidationErrorType
_DOMAIN_CODE = "test_optionals_cond"
diff --git a/tests/integration/pipelex/pipes/optionals/test_optional_guard_lint.py b/tests/integration/pipelex/pipes/optionals/test_optional_guard_lint.py
index 334e8bc8d..32143c1a9 100644
--- a/tests/integration/pipelex/pipes/optionals/test_optional_guard_lint.py
+++ b/tests/integration/pipelex/pipes/optionals/test_optional_guard_lint.py
@@ -9,7 +9,6 @@ from typing import Callable
import pytest
from pydantic import ValidationError
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.mthds_parsing.handle_pipe_errors import extract_wrapped_pipe_validation_error
from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
from pipelex.pipe_controllers.condition.pipe_condition_blueprint import PipeConditionBlueprint
@@ -22,6 +21,7 @@ from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from pipelex.pipe_operators.search.pipe_search import PipeSearch
from pipelex.pipe_operators.search.pipe_search_blueprint import PipeSearchBlueprint
+from pipelex.validation_error_types import PipeValidationErrorType
_DOMAIN_CODE = "test_optionals_guard_lint"
diff --git a/tests/integration/pipelex/pipes/optionals/test_parallel_optional_combine_validation.py b/tests/integration/pipelex/pipes/optionals/test_parallel_optional_combine_validation.py
index 2e48d33c1..2d0bb864b 100644
--- a/tests/integration/pipelex/pipes/optionals/test_parallel_optional_combine_validation.py
+++ b/tests/integration/pipelex/pipes/optionals/test_parallel_optional_combine_validation.py
@@ -11,7 +11,7 @@ from pydantic import Field
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.stuffs.text_content import TextContent
from pipelex.interpreter_hub import get_concept_library, get_pipe_library
@@ -23,6 +23,7 @@ from pipelex.pipe_operators.func.pipe_func import PipeFunc
from pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint
from pipelex.runtime_hub import get_class_registry
from pipelex.system.registries.func_registry import func_registry
+from pipelex.validation_error_types import PipeValidationErrorType
_DOMAIN_CODE = "test_optionals_par_static"
diff --git a/tests/integration/pipelex/pipes/optionals/test_redundant_force_warning.py b/tests/integration/pipelex/pipes/optionals/test_redundant_force_warning.py
index 6410ab5ed..2ee8824b0 100644
--- a/tests/integration/pipelex/pipes/optionals/test_redundant_force_warning.py
+++ b/tests/integration/pipelex/pipes/optionals/test_redundant_force_warning.py
@@ -8,7 +8,6 @@ from typing import Callable
from pipelex.base_exceptions import ValidationErrorCategory
from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.core.stuffs.text_content import TextContent
from pipelex.interpreter_hub import get_pipe_library
from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
@@ -20,6 +19,7 @@ from pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint
from pipelex.pipeline.controller_taint import collect_controller_taint_analyses
from pipelex.pipeline.optionality_warnings import build_optionality_warnings
from pipelex.system.registries.func_registry import func_registry
+from pipelex.validation_error_types import PipeValidationErrorType
_DOMAIN_CODE = "test_redundant_force"
diff --git a/tests/integration/pipelex/pipes/optionals/test_taint_sequence_validation.py b/tests/integration/pipelex/pipes/optionals/test_taint_sequence_validation.py
index 42de46c0f..8f34052d4 100644
--- a/tests/integration/pipelex/pipes/optionals/test_taint_sequence_validation.py
+++ b/tests/integration/pipelex/pipes/optionals/test_taint_sequence_validation.py
@@ -9,7 +9,7 @@ from typing import Callable
import pytest
from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.stuffs.text_content import TextContent
from pipelex.interpreter_hub import get_pipe_library
from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
@@ -23,6 +23,7 @@ from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipe_operators.func.pipe_func import PipeFunc
from pipelex.pipe_operators.func.pipe_func_blueprint import PipeFuncBlueprint
from pipelex.system.registries.func_registry import func_registry
+from pipelex.validation_error_types import PipeValidationErrorType
_DOMAIN_CODE = "test_optionals_taint_seq"
diff --git a/tests/unit/pipelex/cli/agent_cli/test_fix_format.py b/tests/unit/pipelex/cli/agent_cli/test_fix_format.py
index c554f697b..03f94e38d 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_fix_format.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_fix_format.py
@@ -13,6 +13,7 @@ from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat
from pipelex.cli.agent_cli.commands.fix.bundle_cmd import fix_bundle_cmd
from pipelex.pipeline.fixes.fix_loop import FixBundleResult
from pipelex.suggested_fix import FixSafety, SuggestedFix
+from pipelex.validation_error_types import PipeValidationErrorType
if TYPE_CHECKING:
from pathlib import Path
@@ -35,7 +36,7 @@ def _applied_fix(source: str) -> SuggestedFix:
def _invalid_item(source: str) -> ValidationErrorItem:
return ValidationErrorItem(
category=ValidationErrorCategory.PIPE_VALIDATION,
- error_type="INADEQUATE_OUTPUT_CONCEPT",
+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT,
message="output mismatch",
source=source,
)
diff --git a/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py b/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py
index 1c74c2754..f31266cdc 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py
@@ -21,6 +21,7 @@ from pipelex.cli.agent_cli.commands.agent_output import (
)
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.suggested_fix import FixSafety, SuggestedFix
+from pipelex.validation_error_types import PipeValidationErrorType
if TYPE_CHECKING:
from collections.abc import Iterator
@@ -30,7 +31,7 @@ if TYPE_CHECKING:
def _fixable_item(*, source: Path) -> ValidationErrorItem:
return ValidationErrorItem(
category=ValidationErrorCategory.PIPE_VALIDATION,
- error_type="inadequate_output_multiplicity",
+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY,
pipe_code="brainstorm",
domain_code="story_studio",
source=str(source),
diff --git a/tests/unit/pipelex/cli/commands/fix/test_fix_bundle_human_format.py b/tests/unit/pipelex/cli/commands/fix/test_fix_bundle_human_format.py
index cc2327032..cbb668f5e 100644
--- a/tests/unit/pipelex/cli/commands/fix/test_fix_bundle_human_format.py
+++ b/tests/unit/pipelex/cli/commands/fix/test_fix_bundle_human_format.py
@@ -19,6 +19,7 @@ from pipelex.cli.commands.fix._fix_core import _remap_result_to_originals # pyr
from pipelex.cli.commands.fix.bundle_cmd import fix_bundle_cmd
from pipelex.pipeline.fixes.fix_loop import FixBundleResult
from pipelex.suggested_fix import FixSafety, SuggestedFix
+from pipelex.validation_error_types import PipeValidationErrorType
if TYPE_CHECKING:
from pathlib import Path
@@ -41,7 +42,7 @@ def _applied_fix(source: str | None) -> SuggestedFix:
def _remaining_item(source: str) -> ValidationErrorItem:
return ValidationErrorItem(
category=ValidationErrorCategory.PIPE_VALIDATION,
- error_type="MISSING_CONCEPT",
+ error_type=PipeValidationErrorType.UNRESOLVED_CONCEPT,
pipe_code="say_hi",
message="concept 'MissingConcept' is not declared",
source=source,
@@ -52,7 +53,7 @@ def _fixable_remaining_item(source: str) -> ValidationErrorItem:
"""A remaining error that still carries a suggested fix — e.g. skipped by --select/--ignore or left out of write scope."""
return ValidationErrorItem(
category=ValidationErrorCategory.PIPE_VALIDATION,
- error_type="INADEQUATE_OUTPUT_CONCEPT",
+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT,
pipe_code="list_ideas",
message="output concept does not match the last step",
source=source,
diff --git a/tests/unit/pipelex/cli/test_error_handlers_more.py b/tests/unit/pipelex/cli/test_error_handlers_more.py
index ac78d4500..e3d0028e7 100644
--- a/tests/unit/pipelex/cli/test_error_handlers_more.py
+++ b/tests/unit/pipelex/cli/test_error_handlers_more.py
@@ -32,7 +32,6 @@ from pipelex.cogt.exceptions import GatewayUnknownModelError, ModelDeckPresetVal
from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.core.exceptions import PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.core.validation import MIGRATE_COMMAND
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.system.pipelex_service.exceptions import (
@@ -44,6 +43,7 @@ from pipelex.system.pipelex_service.exceptions import (
)
from pipelex.system.pipelex_service.types import RemoteConfigSource
from pipelex.system.telemetry.exceptions import TelemetryConfigValidationError
+from pipelex.validation_error_types import PipeValidationErrorType
if TYPE_CHECKING:
from pytest_mock import MockerFixture
diff --git a/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py b/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py
index 5a89e106e..173886e2d 100644
--- a/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py
+++ b/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py
@@ -18,8 +18,8 @@ from rich.console import Console
from pipelex.cli.error_handlers import handle_validate_bundle_error
from pipelex.core.exceptions import PipeFactoryErrorData, PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeFactoryErrorType, PipeValidationErrorType
from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.validation_error_types import PipeFactoryErrorType, PipeValidationErrorType
if TYPE_CHECKING:
from pytest_mock import MockerFixture
diff --git a/tests/unit/pipelex/errors/test_validation_error_types.py b/tests/unit/pipelex/errors/test_validation_error_types.py
new file mode 100644
index 000000000..cdd4b4434
--- /dev/null
+++ b/tests/unit/pipelex/errors/test_validation_error_types.py
@@ -0,0 +1,74 @@
+"""Gates on the closed registry of bundle-validation ``error_type`` values.
+
+``pipelex.validation_error_types.VALIDATION_ERROR_TYPES`` is the enumeration consumers read to
+learn which faults the language surface can report — the ``/validate`` contract publishes it, and
+the MTHDS Test Corpus will generate its ``error.*`` tag namespace from it. These tests hold
+the two properties that enumeration depends on: that it is derived from the enums the runtime
+actually raises (so it cannot fall behind them), and that those enums do not collide on a wire
+value (so an ``error_type`` still identifies exactly one fault).
+"""
+
+import pytest
+from pydantic import ValidationError
+
+from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
+from pipelex.validation_error_types import (
+ VALIDATION_ERROR_TYPES,
+ PipeFactoryErrorType,
+ PipeValidationErrorType,
+ ValidationErrorType,
+ ValidationResidualErrorType,
+)
+
+
+class TestValidationErrorTypeRegistry:
+ def test_registry_holds_every_member_of_every_contributing_enum(self) -> None:
+ """The registry is the union of its sources, so nothing the runtime raises is missing.
+
+ Written as a set comparison rather than a length check: a member dropped from the registry
+ and a member added to a source enum are both failures, and both should name the member.
+ """
+ contributed = set(PipeValidationErrorType) | set(PipeFactoryErrorType) | set(ValidationResidualErrorType)
+ assert set(VALIDATION_ERROR_TYPES) == contributed
+
+ def test_registry_has_no_duplicate_wire_values(self) -> None:
+ """The contributing enums are value-disjoint, so an ``error_type`` identifies one fault.
+
+ Were two enums to share a value, the ``ValidationErrorType`` union would resolve it to
+ whichever member pydantic reached first, and a consumer keying on the string — the corpus's
+ ``error.*`` tags, conformance's per-error QA cases — would silently conflate two faults.
+ """
+ wire_values = [error_type.value for error_type in VALIDATION_ERROR_TYPES]
+ duplicates = sorted({value for value in wire_values if wire_values.count(value) > 1})
+ assert not duplicates, f"Validation error types sharing a wire value: {', '.join(duplicates)}"
+
+ def test_registry_order_is_deterministic(self) -> None:
+ """Two reads give the same order, so an artifact generated from the registry is stable."""
+ assert tuple(VALIDATION_ERROR_TYPES) == VALIDATION_ERROR_TYPES
+ assert list(VALIDATION_ERROR_TYPES) == [*PipeValidationErrorType, *PipeFactoryErrorType, *ValidationResidualErrorType]
+
+ # The three tests below hold that the registry is enforced when an item is parsed, not merely
+ # documented. They go through ``model_validate`` rather than the constructor on purpose: the
+ # closure that matters is the one a *consumer* meets, reading a plain JSON string off the wire
+ # and turning it back into a diagnostic. A typed constructor call proves only that the type
+ # checker agrees.
+
+ @pytest.mark.parametrize("error_type", VALIDATION_ERROR_TYPES)
+ def test_every_registered_type_is_accepted_by_its_wire_value(self, error_type: ValidationErrorType) -> None:
+ """A registry member round-trips through the plain string it serializes as."""
+ item = ValidationErrorItem.model_validate(
+ {"category": ValidationErrorCategory.PIPE_VALIDATION, "message": "whatever", "error_type": error_type.value}
+ )
+ assert item.error_type == error_type
+
+ def test_an_unregistered_error_type_is_refused(self) -> None:
+ """The failure mode this typing exists to stop: a fault named by an ad-hoc string."""
+ with pytest.raises(ValidationError):
+ ValidationErrorItem.model_validate(
+ {"category": ValidationErrorCategory.PIPE_VALIDATION, "message": "whatever", "error_type": "not_a_registered_error_type"}
+ )
+
+ def test_the_parse_level_residual_may_carry_no_error_type(self) -> None:
+ """``None`` stays legal — a bundle that never became a blueprint identifies no single fault."""
+ item = ValidationErrorItem.model_validate({"category": ValidationErrorCategory.BLUEPRINT_VALIDATION, "message": "Invalid TOML."})
+ assert item.error_type is None
diff --git a/tests/unit/pipelex/mthds_parsing/test_handle_pipe_errors_suffix.py b/tests/unit/pipelex/mthds_parsing/test_handle_pipe_errors_suffix.py
index 5d294453c..740094391 100644
--- a/tests/unit/pipelex/mthds_parsing/test_handle_pipe_errors_suffix.py
+++ b/tests/unit/pipelex/mthds_parsing/test_handle_pipe_errors_suffix.py
@@ -1,5 +1,6 @@
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.mthds_parsing.handle_pipe_errors import categorize_pipe_validation_with_libraries_error
+from pipelex.validation_error_types import PipeValidationErrorType
class TestRequiredProvidedSuffix:
diff --git a/tests/unit/pipelex/mthds_parsing/test_validation_error_categorizer.py b/tests/unit/pipelex/mthds_parsing/test_validation_error_categorizer.py
index 9944de358..b843a6857 100644
--- a/tests/unit/pipelex/mthds_parsing/test_validation_error_categorizer.py
+++ b/tests/unit/pipelex/mthds_parsing/test_validation_error_categorizer.py
@@ -1,8 +1,8 @@
import pytest
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.mthds_parsing.exceptions import MthdsParserError
from pipelex.mthds_parsing.parser import MthdsParser
+from pipelex.validation_error_types import PipeValidationErrorType
# A PipeBatch whose ``input_item_name`` equals its ``input_list_name`` — the collision
# ``PipeBatchBlueprint.validate_inputs`` raises as a ``PipeValidationError`` from inside a pydantic
diff --git a/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_validation.py b/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_validation.py
index 483aef7f1..b120cf13b 100644
--- a/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_validation.py
+++ b/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_validation.py
@@ -1,8 +1,9 @@
import pytest
from pydantic import ValidationError
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.pipe_controllers.batch.pipe_batch_blueprint import PipeBatchBlueprint
+from pipelex.validation_error_types import PipeValidationErrorType
class TestPipeBatchValidation:
diff --git a/tests/unit/pipelex/pipe_machinery/test_pipe_blueprint_presence_markers.py b/tests/unit/pipelex/pipe_machinery/test_pipe_blueprint_presence_markers.py
index 5694883d4..975e66aac 100644
--- a/tests/unit/pipelex/pipe_machinery/test_pipe_blueprint_presence_markers.py
+++ b/tests/unit/pipelex/pipe_machinery/test_pipe_blueprint_presence_markers.py
@@ -1,9 +1,10 @@
import pytest
from pydantic import ValidationError
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.mthds_parsing.handle_pipe_errors import extract_wrapped_pipe_validation_error
from pipelex.pipe_machinery.pipe_blueprint import PipeBlueprint
+from pipelex.validation_error_types import PipeValidationErrorType
class ConcretePipeBlueprint(PipeBlueprint):
diff --git a/tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_validate_inputs.py b/tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_validate_inputs.py
index 8a31d57ea..73bfaeff2 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_validate_inputs.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_validate_inputs.py
@@ -3,11 +3,12 @@ from typing import Callable
import pytest
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.interpreter_hub import get_library_manager
from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipe_operators.structure.pipe_structure import PipeStructure
from pipelex.pipe_operators.structure.pipe_structure_blueprint import PipeStructureBlueprint
+from pipelex.validation_error_types import PipeValidationErrorType
# Bundle that declares a domain concept refining native.Text. Used to verify that
# `validate_inputs_with_library` accepts Text-refining concepts at the strict=False level.
diff --git a/tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_validate_outputs.py b/tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_validate_outputs.py
index 71f752457..028765498 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_validate_outputs.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_validate_outputs.py
@@ -3,10 +3,11 @@ from typing import Callable
import pytest
-from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
+from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipe_operators.structure.pipe_structure import PipeStructure
from pipelex.pipe_operators.structure.pipe_structure_blueprint import PipeStructureBlueprint
+from pipelex.validation_error_types import PipeValidationErrorType
# Bundle declaring a domain concept that refines native.Text. The blueprint-layer guard at
# `PipeStructureBlueprint.validate_output` only catches literal Text strings (`"Text"`,
diff --git a/tests/unit/pipelex/pipeline/fixes/test_blueprint_fix_planner.py b/tests/unit/pipelex/pipeline/fixes/test_blueprint_fix_planner.py
index 381e3b530..b4d3a3ca3 100644
--- a/tests/unit/pipelex/pipeline/fixes/test_blueprint_fix_planner.py
+++ b/tests/unit/pipelex/pipeline/fixes/test_blueprint_fix_planner.py
@@ -9,9 +9,9 @@ all normalize to a ``concept.<Code>`` key).
"""
from pipelex.core.exceptions import PipelexBundleBlueprintValidationErrorData
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.pipeline.fixes.planner import plan_fix_for_blueprint_validation_error
from pipelex.suggested_fix import DeleteKeyOp, FixSafety, RenameTableKeyOp, SetKeyOp
+from pipelex.validation_error_types import PipeValidationErrorType
def _blueprint_error_data(
diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_loop_bail.py b/tests/unit/pipelex/pipeline/fixes/test_fix_loop_bail.py
index a5da92f1e..cb2918c64 100644
--- a/tests/unit/pipelex/pipeline/fixes/test_fix_loop_bail.py
+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_loop_bail.py
@@ -12,9 +12,9 @@ import pytest
from pytest_mock import MockerFixture
from pipelex.core.exceptions import PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.fixes.fix_loop import fix_bundle_file
+from pipelex.validation_error_types import PipeValidationErrorType
_MINIMAL_MTHDS = """domain = "seqfix_bail"
main_pipe = "declared_pipe"
diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_loop_multi_file_scoping.py b/tests/unit/pipelex/pipeline/fixes/test_fix_loop_multi_file_scoping.py
index 5272b5dc8..0e18b9dff 100644
--- a/tests/unit/pipelex/pipeline/fixes/test_fix_loop_multi_file_scoping.py
+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_loop_multi_file_scoping.py
@@ -19,9 +19,9 @@ import tomlkit
from pytest_mock import MockerFixture
from pipelex.core.exceptions import PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.fixes.fix_loop import fix_bundle_file
+from pipelex.validation_error_types import PipeValidationErrorType
_MINIMAL_MTHDS = """domain = "seqfix_scoping"
main_pipe = "list_ideas"
diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_loop_select_ignore.py b/tests/unit/pipelex/pipeline/fixes/test_fix_loop_select_ignore.py
index 73e5789f3..9ea81dc05 100644
--- a/tests/unit/pipelex/pipeline/fixes/test_fix_loop_select_ignore.py
+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_loop_select_ignore.py
@@ -13,9 +13,9 @@ import tomlkit
from pytest_mock import MockerFixture
from pipelex.core.exceptions import PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.fixes.fix_loop import fix_bundle_file
+from pipelex.validation_error_types import PipeValidationErrorType
_BUNDLE_MTHDS = """domain = "selectfix"
main_pipe = "list_ideas"
diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_planner.py b/tests/unit/pipelex/pipeline/fixes/test_fix_planner.py
index 1f406deff..999946ed6 100644
--- a/tests/unit/pipelex/pipeline/fixes/test_fix_planner.py
+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_planner.py
@@ -11,9 +11,9 @@ raise sites only), ``expected_inputs``/``declared_inputs`` for ``sync-controller
import pytest
from pipelex.core.exceptions import PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.pipeline.fixes.planner import plan_fix_for_pipe_validation_error
from pipelex.suggested_fix import DeleteKeyOp, EnsureTableOp, FixSafety, SetKeyOp
+from pipelex.validation_error_types import PipeValidationErrorType
# The inputs table of the pipe every input-drift case below is built around.
_INPUTS_TABLE_PATH = ["pipe", "make_summary", "inputs"]
diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_render.py b/tests/unit/pipelex/pipeline/fixes/test_fix_render.py
index 54cc508be..cddbeae96 100644
--- a/tests/unit/pipelex/pipeline/fixes/test_fix_render.py
+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_render.py
@@ -6,6 +6,7 @@ from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
from pipelex.pipeline.fixes.fix_loop import FixBundleResult
from pipelex.pipeline.fixes.fix_render import format_fix_markdown, format_fix_still_invalid_markdown
from pipelex.suggested_fix import FixSafety, SuggestedFix
+from pipelex.validation_error_types import PipeValidationErrorType
class TestFixRender:
@@ -113,7 +114,7 @@ class TestFixRender:
remaining_errors=[
ValidationErrorItem(
category=ValidationErrorCategory.PIPE_VALIDATION,
- error_type="unresolved_concept",
+ error_type=PipeValidationErrorType.UNRESOLVED_CONCEPT,
pipe_code="b",
concept_code="Missing",
message="Concept 'Missing' is not defined.",
@@ -152,7 +153,7 @@ class TestFixRender:
remaining_errors=[
ValidationErrorItem(
category=ValidationErrorCategory.PIPE_VALIDATION,
- error_type="unresolved_concept",
+ error_type=PipeValidationErrorType.UNRESOLVED_CONCEPT,
message="Concept 'Missing' is not defined.",
)
],
diff --git a/tests/unit/pipelex/pipeline/test_validate_bundle_error_report.py b/tests/unit/pipelex/pipeline/test_validate_bundle_error_report.py
index a21493262..832eda078 100644
--- a/tests/unit/pipelex/pipeline/test_validate_bundle_error_report.py
+++ b/tests/unit/pipelex/pipeline/test_validate_bundle_error_report.py
@@ -9,8 +9,8 @@ of only a single ``detail`` string. The cause-chain enrichment from the base
from pipelex.base_exceptions import DisclosureMode, ErrorDomain, ValidationErrorCategory
from pipelex.core.exceptions import PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.validation_error_types import PipeValidationErrorType
def _error_with_two_categories() -> ValidateBundleError:
diff --git a/tests/unit/pipelex/pipeline/test_validation_errors.py b/tests/unit/pipelex/pipeline/test_validation_errors.py
index 4fe38ecc1..24e8a796e 100644
--- a/tests/unit/pipelex/pipeline/test_validation_errors.py
+++ b/tests/unit/pipelex/pipeline/test_validation_errors.py
@@ -13,10 +13,10 @@ import json
from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
from pipelex.cli.agent_cli.commands.agent_output import extract_validation_errors
from pipelex.core.exceptions import PipeFactoryErrorData, PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeFactoryErrorType, PipeValidationErrorType
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validation_errors import build_validation_error_items
from pipelex.suggested_fix import DeleteKeyOp, RenameTableKeyOp, SetKeyOp
+from pipelex.validation_error_types import PipeFactoryErrorType, PipeValidationErrorType
def _build_items(exc: ValidateBundleError) -> list[ValidationErrorItem]:
diff --git a/tests/unit/pipelex/pipeline/test_validation_render.py b/tests/unit/pipelex/pipeline/test_validation_render.py
index b281dc690..599d14db4 100644
--- a/tests/unit/pipelex/pipeline/test_validation_render.py
+++ b/tests/unit/pipelex/pipeline/test_validation_render.py
@@ -13,6 +13,7 @@ from pipelex.pipeline.validation_render import (
render_invalid_validation_markdown,
)
from pipelex.suggested_fix import FixSafety, SuggestedFix
+from pipelex.validation_error_types import PipeValidationErrorType, ValidationResidualErrorType
class TestValidationRender:
@@ -158,7 +159,7 @@ class TestValidationRender:
items = [
ValidationErrorItem(
category=ValidationErrorCategory.PIPE_VALIDATION,
- error_type="inadequate_output_multiplicity",
+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY,
pipe_code="brainstorm",
domain_code="story_studio",
source="/w/bundle.mthds",
@@ -172,7 +173,7 @@ class TestValidationRender:
),
ValidationErrorItem(
category=ValidationErrorCategory.DRY_RUN,
- error_type="DryRunError",
+ error_type=ValidationResidualErrorType.DRY_RUN_ERROR,
message="Dry run failed: boom.",
),
]
diff --git a/tests/unit/pipelex/pipeline/test_validation_report.py b/tests/unit/pipelex/pipeline/test_validation_report.py
index 2292bd834..ce8437800 100644
--- a/tests/unit/pipelex/pipeline/test_validation_report.py
+++ b/tests/unit/pipelex/pipeline/test_validation_report.py
@@ -14,6 +14,7 @@ from pipelex.mthds_parsing.parser import MthdsParser
from pipelex.pipeline.bundle_validator import DryRunOutput, DryRunStatus
from pipelex.pipeline.pipe_io_contracts import IOMultiplicity, PipeIOContract, PipeOutputContract
from pipelex.pipeline.validation_report import build_validation_report
+from pipelex.validation_error_types import PipeValidationErrorType
_NO_MAIN_PIPE_MTHDS = """
domain = "alpha"
@@ -91,7 +92,7 @@ class TestBuildValidationReport:
blueprints = [MthdsParser.make_pipelex_bundle_blueprint(mthds_content=_MAIN_PIPE_MTHDS)]
warning_item = ValidationErrorItem(
category=ValidationErrorCategory.PIPE_VALIDATION,
- error_type="optional_force_redundant",
+ error_type=PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT,
pipe_code="do_it",
domain_code="beta",
variable_names=["doc"],
diff --git a/wip/pr-1138-review-notes.md b/wip/pr-1138-review-notes.md
new file mode 100644
index 000000000..a102dbf98
--- /dev/null
+++ b/wip/pr-1138-review-notes.md
@@ -0,0 +1,30 @@
+# PR #1138 review notes — deferred item
+
+PR: <https://github.com/Pipelex/pipelex/pull/1138> (`feature/MthdsTestCorpus-p3`, "a closed registry for validation error types")
+
+One item from the review-agent triage on this PR was deferred rather than fixed. Everything else raised on the PR was either fixed in place or answered on the thread.
+
+## The one-TestClass-per-module rule is absolute in writing, unenforced in practice, and shipped to users
+
+**Reporter:** `chatgpt-codex-connector` (P1), on `tests/unit/pipelex/errors/test_validation_error_types.py:51`. The specific violation it flagged was real and has been fixed in this PR — the module's two test classes were merged into one. What is deferred is the systemic question that fixing it exposed.
+
+**The rule.** `.claude/rules/pytest-standards.md` and its shipped kit copy `pipelex/kit/agent_rules/pytest_standards.md` both state it twice, without any qualifier:
+
+> `NEVER EVER put more than one TestClass into a test module.`
+
+> `- Always put tests inside Test classes: 1 TestClass per module.`
+
+It reaches contributors and agents through the generated repo-root `AGENTS.md` and `CLAUDE.md`, and it reaches *our users* through the kit rules we ship in the package.
+
+**What the codebase actually does.** Counting top-level `^class Test` declarations per module across `tests/`, after this PR's fix: 57 modules declare more than one, out of 1073 modules that declare at least one. The heaviest are `test_concept_representation_generator.py` (12 classes), `test_structured_content_composer.py` (11), `test_uri_resolver.py` (10), `test_migrate_commands.py` (10), `test_coverage_gate.py` (9), `test_validation_report.py` (9). These are not old stragglers: several landed within days of this PR, one of them the day before the review.
+
+**Why it drifts.** Nothing checks it. `make agent-check` runs `fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering drift-check`; `make check` adds the config, rules, URL, gateway-model, schema and migration checks plus `pylint`. No target in either aggregate, and no guard script anywhere, inspects test-class counts. Contrast the keyword-only convention, which is comparable in kind — a readability convention with no runtime consequence — and which is mechanically enforced by an AST guard wired into `agent-check`, `check`, and CI, complete with a grant registry for justified exceptions. That is what an enforced convention looks like in this repo; this one has no equivalent, so it is enforced only by whichever reviewer happens to notice.
+
+**Why it matters beyond tidiness.** We ship "NEVER EVER" to users in the kit rules while 5% of our own class-bearing test modules break it. That is a dogfooding defect: either the rule means what it says and we should be able to hold ourselves to it mechanically, or it is a default-with-exceptions and the wording overstates it. Both are defensible; the current state — an absolute prohibition that only a review bot ever enforces, and only on whichever PR it happens to read — is the one option that is not.
+
+**The open question, for a human to decide.** Two coherent resolutions, and choosing between them is a judgment call about how much we want to spend on test-file shape, not something a PR-review pass should settle unilaterally:
+
+1. **Add a guard.** A small AST check in the `check-keyword-only` mould, run in `agent-check` and CI. Because 57 modules already violate it, this needs either a one-off sweep to merge or split them, or a grandfathering allowlist analogous to `subject_grants.toml` — and an allowlist that starts with 57 entries is worth pausing over before adopting.
+2. **Soften the rule** in both `.claude/rules/pytest-standards.md` and the shipped `pipelex/kit/agent_rules/pytest_standards.md`, to something that matches how we actually write tests — for instance, one class per module by default, with more permitted when a module covers genuinely distinct seams. This costs nothing and removes the false absolute, but gives up the consistency the rule was reaching for.
+
+There is no urgency either way; nothing is broken and no gate is failing. It should be decided rather than left to erode further, since every week it goes unresolved adds more modules to whichever sweep option 1 would require.